@link-assistant/hive-mind 0.53.2 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @link-assistant/hive-mind
 
+## 0.54.0
+
+### Minor Changes
+
+- 4af584c: Add producer/consumer queue for /solve command in Telegram bot
+
+  This feature implements resource-aware throttling to prevent system overload when multiple /solve commands are submitted simultaneously.
+
+  **Queue Configuration (using usage ratios 0.0-1.0):**
+  - `RAM_THRESHOLD: 0.5` - Stop new commands if RAM usage > 50%
+  - `CPU_THRESHOLD: 0.5` - Stop new commands if CPU usage > 50%
+  - `DISK_THRESHOLD: 0.95` - One-at-a-time mode if disk usage > 95%
+  - `CLAUDE_SESSION_THRESHOLD: 0.9` - Stop if Claude 5-hour limit > 90%
+  - `CLAUDE_WEEKLY_THRESHOLD: 0.99` - One-at-a-time mode if weekly limit > 99%
+  - `GITHUB_API_THRESHOLD: 0.8` - Stop if GitHub API > 80% with parallel claude commands
+  - 1-minute minimum interval between command starts
+  - Running claude process detection
+
+  **Status Flow:**
+  - `Queued` - Initial status when command is added to queue
+  - `Waiting` - When start conditions are not met (with human-readable reason)
+  - `Starting` - When command is being started
+  - `Started` - Terminal status with session info (message tracking is released)
+
+  **Caching:**
+  - API calls (Claude, GitHub): 3-minute cache
+  - System metrics (RAM, CPU, disk): 2-minute cache
+  - Shared cache between /solve queue and /limits command
+
+  **Files Changed:**
+  - `limits.lib.mjs` - Merged from `claude-limits.lib.mjs` with added caching layer (replaces both `claude-limits.lib.mjs` and `telegram-limits.lib.mjs`)
+  - `telegram-solve-queue.lib.mjs` - Queue implementation with status tracking
+
+  **User Experience:**
+  - Messages are updated in-place as status changes
+  - Clear waiting reasons displayed (e.g., "Disk usage is 96% (threshold: 95%)")
+  - Queue status added to /limits command output
+
 ## 0.53.2
 
 ### Patch Changes

package/package.json

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

package/src/{claude-limits.lib.mjs → limits.lib.mjs}

@@ -780,7 +780,143 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
   return message;
 }
 
+// ============================================================================
+// Caching Layer
+// ============================================================================
+
+/**
+ * Cache TTL constants (in milliseconds)
+ */
+export const CACHE_TTL = {
+  API: 180000, // 3 minutes for API calls (Claude, GitHub)
+  SYSTEM: 120000, // 2 minutes for system metrics (RAM, CPU, disk)
+};
+
+/**
+ * Generic cache class with configurable TTL
+ */
+class LimitCache {
+  constructor(defaultTtlMs = CACHE_TTL.API) {
+    this.defaultTtlMs = defaultTtlMs;
+    this.cache = new Map();
+  }
+
+  get(key, ttlMs) {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    const effectiveTtl = ttlMs ?? entry.ttlMs ?? this.defaultTtlMs;
+    if (Date.now() - entry.timestamp > effectiveTtl) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  set(key, value, ttlMs) {
+    this.cache.set(key, { value, timestamp: Date.now(), ttlMs: ttlMs ?? this.defaultTtlMs });
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+
+  getStats() {
+    const now = Date.now();
+    let validEntries = 0;
+    let expiredEntries = 0;
+    for (const [, entry] of this.cache) {
+      const effectiveTtl = entry.ttlMs ?? this.defaultTtlMs;
+      if (now - entry.timestamp > effectiveTtl) {
+        expiredEntries++;
+      } else {
+        validEntries++;
+      }
+    }
+    return { validEntries, expiredEntries, totalEntries: this.cache.size };
+  }
+}
+
+let globalCache = null;
+
+export function getLimitCache() {
+  if (!globalCache) globalCache = new LimitCache();
+  return globalCache;
+}
+
+export function resetLimitCache() {
+  if (globalCache) {
+    globalCache.clear();
+    globalCache = null;
+  }
+}
+
+export async function getCachedClaudeLimits(verbose = false) {
+  const cache = getLimitCache();
+  const cached = cache.get('claude', CACHE_TTL.API);
+  if (cached) {
+    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached Claude limits');
+    return cached;
+  }
+  const result = await getClaudeUsageLimits(verbose);
+  if (result.success) cache.set('claude', result, CACHE_TTL.API);
+  return result;
+}
+
+export async function getCachedGitHubLimits(verbose = false) {
+  const cache = getLimitCache();
+  const cached = cache.get('github', CACHE_TTL.API);
+  if (cached) {
+    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached GitHub limits');
+    return cached;
+  }
+  const result = await getGitHubRateLimits(verbose);
+  if (result.success) cache.set('github', result, CACHE_TTL.API);
+  return result;
+}
+
+export async function getCachedMemoryInfo(verbose = false) {
+  const cache = getLimitCache();
+  const cached = cache.get('memory', CACHE_TTL.SYSTEM);
+  if (cached) {
+    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached memory info');
+    return cached;
+  }
+  const result = await getMemoryInfo(verbose);
+  if (result.success) cache.set('memory', result, CACHE_TTL.SYSTEM);
+  return result;
+}
+
+export async function getCachedCpuInfo(verbose = false) {
+  const cache = getLimitCache();
+  const cached = cache.get('cpu', CACHE_TTL.SYSTEM);
+  if (cached) {
+    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached CPU info');
+    return cached;
+  }
+  const result = await getCpuLoadInfo(verbose);
+  if (result.success) cache.set('cpu', result, CACHE_TTL.SYSTEM);
+  return result;
+}
+
+export async function getCachedDiskInfo(verbose = false) {
+  const cache = getLimitCache();
+  const cached = cache.get('disk', CACHE_TTL.SYSTEM);
+  if (cached) {
+    if (verbose) console.log('[VERBOSE] /limits-cache: Using cached disk info');
+    return cached;
+  }
+  const result = await getDiskSpaceInfo(verbose);
+  if (result.success) cache.set('disk', result, CACHE_TTL.SYSTEM);
+  return result;
+}
+
+export async function getAllCachedLimits(verbose = false) {
+  const [claude, github, memory, cpu, disk] = await Promise.all([getCachedClaudeLimits(verbose), getCachedGitHubLimits(verbose), getCachedMemoryInfo(verbose), getCachedCpuInfo(verbose), getCachedDiskInfo(verbose)]);
+  return { claude, github, memory, cpu, disk };
+}
+
 export default {
+  // Raw functions (no caching)
   getClaudeUsageLimits,
   getCpuLoadInfo,
   getMemoryInfo,
@@ -789,4 +925,15 @@ export default {
   getProgressBar,
   calculateTimePassedPercentage,
   formatUsageMessage,
+  // Cache management
+  CACHE_TTL,
+  getLimitCache,
+  resetLimitCache,
+  // Cached functions
+  getCachedClaudeLimits,
+  getCachedGitHubLimits,
+  getCachedMemoryInfo,
+  getCachedCpuInfo,
+  getCachedDiskInfo,
+  getAllCachedLimits,
 };

package/src/telegram-bot.mjs

@@ -44,14 +44,11 @@ const { parseGitHubUrl } = await import('./github.lib.mjs');
 // Import model validation for early validation with helpful error messages
 const { validateModelName } = await import('./model-validation.lib.mjs');
 
-// Import Claude limits library for /limits command
-const { getClaudeUsageLimits, getCpuLoadInfo, getMemoryInfo, getDiskSpaceInfo, getGitHubRateLimits, formatUsageMessage } = await import('./claude-limits.lib.mjs');
-
-// Import version info library for /version command
+// Import libraries for /limits, /version, and markdown escaping
+const { formatUsageMessage, getAllCachedLimits } = await import('./limits.lib.mjs');
 const { getVersionInfo, formatVersionMessage } = await import('./version-info.lib.mjs');
-
-// Import Telegram markdown escaping utilities
 const { escapeMarkdown, escapeMarkdownV2 } = await import('./telegram-markdown.lib.mjs');
+const { getSolveQueue, getRunningClaudeProcesses, createQueueExecuteCallback } = await import('./telegram-solve-queue.lib.mjs');
 
 const config = yargs(hideBin(process.argv))
   .usage('Usage: hive-telegram-bot [options]')
@@ -873,22 +870,26 @@ bot.command('limits', async ctx => {
     reply_to_message_id: ctx.message.message_id,
   });
 
-  // Get the usage limits, system info, and GitHub rate limits in parallel
-  const [result, cpuLoadResult, memoryResult, diskSpaceResult, githubLimitsResult] = await Promise.all([getClaudeUsageLimits(VERBOSE), getCpuLoadInfo(VERBOSE), getMemoryInfo(VERBOSE), getDiskSpaceInfo(VERBOSE), getGitHubRateLimits(VERBOSE)]);
+  // Get all limits using shared cache (3min for API, 2min for system)
+  const limits = await getAllCachedLimits(VERBOSE);
 
-  if (!result.success) {
-    // Edit the fetching message to show the error
-    // Escape the error message for MarkdownV2, preserving inline code blocks
-    const escapedError = escapeMarkdownV2(result.error, { preserveCodeBlocks: true });
+  if (!limits.claude.success) {
+    const escapedError = escapeMarkdownV2(limits.claude.error, { preserveCodeBlocks: true });
     await ctx.telegram.editMessageText(fetchingMessage.chat.id, fetchingMessage.message_id, undefined, `❌ ${escapedError}`, { parse_mode: 'MarkdownV2' });
     return;
   }
 
-  // Format and edit the fetching message with the results (pass all system info if available)
-  const message = '📊 *Usage Limits*\n\n' + formatUsageMessage(result.usage, diskSpaceResult.success ? diskSpaceResult.diskSpace : null, githubLimitsResult.success ? githubLimitsResult.githubRateLimit : null, cpuLoadResult.success ? cpuLoadResult.cpuLoad : null, memoryResult.success ? memoryResult.memory : null);
-  await ctx.telegram.editMessageText(fetchingMessage.chat.id, fetchingMessage.message_id, undefined, message, {
-    parse_mode: 'Markdown',
-  });
+  // Format the message with usage limits and queue status
+  let message = '📊 *Usage Limits*\n\n' + formatUsageMessage(limits.claude.usage, 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);
+  const solveQueue = getSolveQueue({ verbose: VERBOSE });
+  const queueStats = solveQueue.getStats();
+  const claudeProcs = await getRunningClaudeProcesses(VERBOSE);
+  const codeBlockEnd = message.lastIndexOf('```');
+  if (codeBlockEnd !== -1) {
+    const queueStatus = queueStats.queued > 0 || queueStats.processing > 0 ? `Pending: ${queueStats.queued}, Processing: ${queueStats.processing}` : 'Empty (no pending commands)';
+    message = message.slice(0, codeBlockEnd) + `\nSolve Queue\n${queueStatus}\nClaude processes: ${claudeProcs.count}\n` + message.slice(codeBlockEnd);
+  }
+  await ctx.telegram.editMessageText(fetchingMessage.chat.id, fetchingMessage.message_id, undefined, message, { parse_mode: 'Markdown' });
 });
 bot.command('version', async ctx => {
   VERBOSE && console.log('[VERBOSE] /version command received');
@@ -1073,15 +1074,23 @@ bot.command(/^solve$/i, async ctx => {
   }
 
   const requester = buildUserMention({ user: ctx.from, parseMode: 'Markdown' });
-  const escapedUrl = escapeMarkdown(args[0]);
   const optionsText = args.slice(1).join(' ') || 'none';
-  let infoBlock = `Requested by: ${requester}\nURL: ${escapedUrl}\nOptions: ${optionsText}`;
-  if (solveOverrides.length > 0) {
-    infoBlock += `\n🔒 Locked options: ${solveOverrides.join(' ')}`;
+  let infoBlock = `Requested by: ${requester}\nURL: ${escapeMarkdown(args[0])}\nOptions: ${optionsText}`;
+  if (solveOverrides.length > 0) infoBlock += `\n🔒 Locked options: ${solveOverrides.join(' ')}`;
+  const solveQueue = getSolveQueue({ verbose: VERBOSE });
+  const check = await solveQueue.canStartCommand();
+  const queueStats = solveQueue.getStats();
+  if (check.canStart && queueStats.queued === 0) {
+    const startingMessage = await ctx.reply(`🚀 Starting solve command...\n\n${infoBlock}`, { parse_mode: 'Markdown', reply_to_message_id: ctx.message.message_id });
+    await executeAndUpdateMessage(ctx, startingMessage, 'solve', args, infoBlock);
+  } else {
+    const queueItem = solveQueue.enqueue({ url: args[0], args, ctx, requester, infoBlock, tool: solveTool });
+    let queueMessage = `📋 Solve command queued (position #${queueStats.queued + 1})\n\n${infoBlock}`;
+    if (check.reason) queueMessage += `\n\n⏳ Waiting: ${check.reason}`;
+    const queuedMessage = await ctx.reply(queueMessage, { parse_mode: 'Markdown', reply_to_message_id: ctx.message.message_id });
+    queueItem.messageInfo = { chatId: queuedMessage.chat.id, messageId: queuedMessage.message_id };
+    if (!solveQueue.executeCallback) solveQueue.executeCallback = createQueueExecuteCallback(executeStartScreen);
   }
-
-  const startingMessage = await ctx.reply(`🚀 Starting solve command...\n\n${infoBlock}`, { parse_mode: 'Markdown', reply_to_message_id: ctx.message.message_id });
-  await executeAndUpdateMessage(ctx, startingMessage, 'solve', args, infoBlock);
 });
 
 bot.command(/^hive$/i, async ctx => {

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

@@ -0,0 +1,839 @@
+#!/usr/bin/env node
+/**
+ * Telegram Solve Queue Library
+ *
+ * Producer/consumer queue for /solve commands in the Telegram bot.
+ * Implements resource-aware throttling to prevent system overload.
+ *
+ * Features:
+ * - Resource checking (RAM, CPU, disk)
+ * - API limit checking (Claude, GitHub)
+ * - Minimum interval between command starts
+ * - Running process detection
+ * - Status tracking: Queued -> Waiting -> Starting -> Started
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1041
+ */
+
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+// Import centralized limits and caching
+import { getCachedClaudeLimits, getCachedGitHubLimits, getCachedMemoryInfo, getCachedCpuInfo, getCachedDiskInfo, getLimitCache } from './limits.lib.mjs';
+
+/**
+ * Configuration constants for queue throttling
+ * All thresholds use ratios (0.0 - 1.0) representing usage percentage
+ */
+export const QUEUE_CONFIG = {
+  // Resource thresholds (usage ratios: 0.0 - 1.0)
+  RAM_THRESHOLD: 0.5, // Stop if RAM usage > 50%
+  CPU_THRESHOLD: 0.5, // Stop if CPU usage > 50%
+  DISK_THRESHOLD: 0.95, // One-at-a-time if disk usage > 95%
+
+  // API limit thresholds (usage ratios: 0.0 - 1.0)
+  CLAUDE_SESSION_THRESHOLD: 0.9, // Stop if 5-hour limit > 90%
+  CLAUDE_WEEKLY_THRESHOLD: 0.99, // One-at-a-time if weekly limit > 99%
+  GITHUB_API_THRESHOLD: 0.8, // Stop if GitHub > 80% with parallel claude
+
+  // Timing
+  MIN_START_INTERVAL_MS: 60000, // 1 minute between starts
+  CONSUMER_POLL_INTERVAL_MS: 5000, // 5 seconds between queue checks
+
+  // Process detection
+  CLAUDE_PROCESS_NAMES: ['claude'], // Process names to detect
+};
+
+/**
+ * Status enum for queue items
+ */
+export const QueueItemStatus = {
+  QUEUED: 'queued',
+  WAITING: 'waiting',
+  STARTING: 'starting',
+  STARTED: 'started',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+};
+
+/**
+ * Count running claude processes
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{count: number, processes: string[]}>}
+ */
+export async function getRunningClaudeProcesses(verbose = false) {
+  try {
+    const { stdout } = await execAsync('pgrep -l -x claude 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(' ') || 'claude',
+        };
+      })
+      .filter(p => p.pid);
+
+    if (verbose) {
+      console.log(`[VERBOSE] /solve-queue found ${processes.length} running claude 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 claude processes:', error.message);
+    }
+    return { count: 0, processes: [] };
+  }
+}
+
+/**
+ * Format a threshold as percentage for display
+ * @param {number} ratio - Ratio (0.0 - 1.0)
+ * @returns {string} Formatted percentage
+ */
+function formatThresholdPercent(ratio) {
+  return `${Math.round(ratio * 100)}%`;
+}
+
+/**
+ * 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
+ */
+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_session':
+      return `Claude session limit is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'claude_weekly':
+      return `Claude 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`;
+    default:
+      return `${metric} threshold exceeded`;
+  }
+}
+
+/**
+ * Queue item representing a /solve command request
+ */
+class SolveQueueItem {
+  constructor(options) {
+    this.id = `solve-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    this.url = options.url;
+    this.args = options.args;
+    this.ctx = options.ctx;
+    this.requester = options.requester;
+    this.infoBlock = options.infoBlock;
+    this.tool = options.tool || 'claude';
+    this.createdAt = new Date();
+    this.startedAt = null;
+    this.status = QueueItemStatus.QUEUED;
+    this.waitingReason = null;
+    this.error = null;
+    this.result = null;
+    this.sessionName = null;
+    // Message tracking - forget after STARTED
+    this.messageInfo = null; // { chatId, messageId }
+  }
+
+  /**
+   * Update status to waiting with reason
+   * @param {string} reason - Waiting reason
+   */
+  setWaiting(reason) {
+    this.status = QueueItemStatus.WAITING;
+    this.waitingReason = reason;
+  }
+
+  /**
+   * Update status to starting
+   */
+  setStarting() {
+    this.status = QueueItemStatus.STARTING;
+    this.startedAt = new Date();
+    this.waitingReason = null;
+  }
+
+  /**
+   * Update status to started and clear message tracking
+   * @param {string} sessionName - Session name for debugging
+   */
+  setStarted(sessionName) {
+    this.status = QueueItemStatus.STARTED;
+    this.sessionName = sessionName;
+    // Terminal status - forget message tracking
+    this.messageInfo = null;
+  }
+
+  /**
+   * Mark item as failed
+   * @param {Error|string} error - Error that occurred
+   */
+  setFailed(error) {
+    this.status = QueueItemStatus.FAILED;
+    this.error = error instanceof Error ? error.message : error;
+  }
+
+  /**
+   * Mark item as cancelled
+   */
+  setCancelled() {
+    this.status = QueueItemStatus.CANCELLED;
+  }
+
+  /**
+   * Get wait time in queue (ms)
+   */
+  getWaitTime() {
+    const endTime = this.startedAt || new Date();
+    return endTime - this.createdAt;
+  }
+
+  /**
+   * Format for display
+   * @returns {string}
+   */
+  toString() {
+    return `[${this.id}] ${this.url} (${this.status})`;
+  }
+}
+
+/**
+ * Solve Queue - Producer/Consumer queue for /solve commands
+ */
+export class SolveQueue {
+  constructor(options = {}) {
+    this.verbose = options.verbose || false;
+    this.executeCallback = options.executeCallback || null;
+    this.messageUpdateCallback = options.messageUpdateCallback || null;
+
+    // Queue state
+    this.queue = [];
+    this.processing = new Map();
+    this.completed = [];
+    this.failed = [];
+    this.isRunning = true;
+
+    // Timing
+    this.lastStartTime = null;
+
+    // Consumer task reference
+    this.consumerTask = null;
+
+    // Statistics
+    this.stats = {
+      totalEnqueued: 0,
+      totalStarted: 0,
+      totalCompleted: 0,
+      totalFailed: 0,
+      totalCancelled: 0,
+      throttleReasons: {},
+    };
+
+    this.log('SolveQueue initialized');
+  }
+
+  /**
+   * Log message if verbose mode is enabled
+   * @param {string} message
+   */
+  log(message) {
+    if (this.verbose) {
+      console.log(`[VERBOSE] /solve-queue: ${message}`);
+    }
+  }
+
+  /**
+   * Add a solve command to the queue
+   * @param {Object} options - Queue item options
+   * @returns {SolveQueueItem} The queued item
+   */
+  enqueue(options) {
+    const item = new SolveQueueItem(options);
+    this.queue.push(item);
+    this.stats.totalEnqueued++;
+
+    this.log(`Enqueued: ${item.toString()}, queue length: ${this.queue.length}`);
+
+    // Start consumer if not already running
+    this.ensureConsumerRunning();
+
+    return item;
+  }
+
+  /**
+   * Cancel a queued item by ID
+   * @param {string} id - Item ID
+   * @returns {boolean} True if cancelled
+   */
+  cancel(id) {
+    const queueIndex = this.queue.findIndex(item => item.id === id);
+    if (queueIndex !== -1) {
+      const item = this.queue.splice(queueIndex, 1)[0];
+      item.setCancelled();
+      this.stats.totalCancelled++;
+      this.log(`Cancelled queued item: ${item.toString()}`);
+      return true;
+    }
+
+    if (this.processing.has(id)) {
+      this.log(`Cannot cancel processing item: ${id}`);
+      return false;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get queue statistics
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      queued: this.queue.length,
+      processing: this.processing.size,
+      completed: this.completed.length,
+      failed: this.failed.length,
+      ...this.stats,
+      cacheStats: getLimitCache().getStats(),
+      lastStartTime: this.lastStartTime,
+      isRunning: this.isRunning,
+    };
+  }
+
+  /**
+   * Get queue items summary for display
+   * @returns {Object}
+   */
+  getQueueSummary() {
+    return {
+      pending: this.queue.map(item => ({
+        id: item.id,
+        url: item.url,
+        requester: item.requester,
+        waitTime: item.getWaitTime(),
+        createdAt: item.createdAt,
+        status: item.status,
+        waitingReason: item.waitingReason,
+      })),
+      processing: Array.from(this.processing.values()).map(item => ({
+        id: item.id,
+        url: item.url,
+        requester: item.requester,
+        startedAt: item.startedAt,
+        status: item.status,
+      })),
+    };
+  }
+
+  /**
+   * Check if a new command can start
+   * @returns {Promise<{canStart: boolean, reason?: string, reasons?: string[], oneAtATime?: boolean}>}
+   */
+  async canStartCommand() {
+    const reasons = [];
+    let oneAtATime = false;
+
+    // Check minimum interval since last start
+    if (this.lastStartTime) {
+      const timeSinceLastStart = Date.now() - this.lastStartTime;
+      if (timeSinceLastStart < QUEUE_CONFIG.MIN_START_INTERVAL_MS) {
+        const waitSeconds = Math.ceil((QUEUE_CONFIG.MIN_START_INTERVAL_MS - timeSinceLastStart) / 1000);
+        reasons.push(formatWaitingReason('min_interval', 0, 0) + ` (${waitSeconds}s remaining)`);
+        this.recordThrottle('min_interval');
+      }
+    }
+
+    // Check running claude processes
+    const claudeProcs = await getRunningClaudeProcesses(this.verbose);
+    if (claudeProcs.count > 0) {
+      reasons.push(formatWaitingReason('claude_running', claudeProcs.count, 0) + ` (${claudeProcs.count} processes)`);
+      this.recordThrottle('claude_running');
+    }
+
+    // Check system resources
+    const resourceCheck = await this.checkSystemResources();
+    if (!resourceCheck.ok) {
+      reasons.push(...resourceCheck.reasons);
+    }
+    if (resourceCheck.oneAtATime) {
+      oneAtATime = true;
+    }
+
+    // Check API limits
+    const limitCheck = await this.checkApiLimits(claudeProcs.count > 0);
+    if (!limitCheck.ok) {
+      reasons.push(...limitCheck.reasons);
+    }
+    if (limitCheck.oneAtATime) {
+      oneAtATime = true;
+    }
+
+    const canStart = reasons.length === 0;
+
+    if (!canStart && this.verbose) {
+      this.log(`Cannot start: ${reasons.join(', ')}`);
+    }
+
+    return {
+      canStart,
+      reason: reasons.length > 0 ? reasons.join('\n') : undefined,
+      reasons,
+      oneAtATime,
+      claudeProcesses: claudeProcs.count,
+    };
+  }
+
+  /**
+   * Check system resources (RAM, CPU, disk) using cached values
+   * @returns {Promise<{ok: boolean, reasons: string[], oneAtATime: boolean}>}
+   */
+  async checkSystemResources() {
+    const reasons = [];
+    let oneAtATime = false;
+
+    // Check RAM (using cached value)
+    const memResult = await getCachedMemoryInfo(this.verbose);
+    if (memResult.success) {
+      const usedRatio = memResult.memory.usedPercentage / 100;
+      if (usedRatio > QUEUE_CONFIG.RAM_THRESHOLD) {
+        reasons.push(formatWaitingReason('ram', memResult.memory.usedPercentage, QUEUE_CONFIG.RAM_THRESHOLD));
+        this.recordThrottle('ram_high');
+      }
+    }
+
+    // Check CPU (using cached value)
+    const cpuResult = await getCachedCpuInfo(this.verbose);
+    if (cpuResult.success) {
+      const usedRatio = cpuResult.cpuLoad.usagePercentage / 100;
+      if (usedRatio > QUEUE_CONFIG.CPU_THRESHOLD) {
+        reasons.push(formatWaitingReason('cpu', cpuResult.cpuLoad.usagePercentage, QUEUE_CONFIG.CPU_THRESHOLD));
+        this.recordThrottle('cpu_high');
+      }
+    }
+
+    // Check disk space (using cached value)
+    const diskResult = await getCachedDiskInfo(this.verbose);
+    if (diskResult.success) {
+      // Calculate usage from free percentage
+      const usedPercent = 100 - diskResult.diskSpace.freePercentage;
+      const usedRatio = usedPercent / 100;
+      if (usedRatio > QUEUE_CONFIG.DISK_THRESHOLD) {
+        oneAtATime = true;
+        this.recordThrottle('disk_high');
+        if (this.processing.size > 0) {
+          reasons.push(formatWaitingReason('disk', usedPercent, QUEUE_CONFIG.DISK_THRESHOLD) + ' (waiting for current command)');
+        }
+      }
+    }
+
+    return { ok: reasons.length === 0, reasons, oneAtATime };
+  }
+
+  /**
+   * Check API limits (Claude, GitHub) using cached values
+   * @param {boolean} hasRunningClaude - Whether claude processes are running
+   * @returns {Promise<{ok: boolean, reasons: string[], oneAtATime: boolean}>}
+   */
+  async checkApiLimits(hasRunningClaude = false) {
+    const reasons = [];
+    let oneAtATime = false;
+
+    // Check Claude limits (using cached value)
+    const claudeResult = await getCachedClaudeLimits(this.verbose);
+    if (claudeResult.success) {
+      const sessionPercent = claudeResult.usage.currentSession.percentage;
+      const weeklyPercent = claudeResult.usage.allModels.percentage;
+
+      // Session limit (5-hour)
+      if (sessionPercent !== null) {
+        const sessionRatio = sessionPercent / 100;
+        if (sessionRatio >= 1.0) {
+          reasons.push('Claude session limit is 100% (waiting for reset)');
+          this.recordThrottle('claude_session_100');
+        } else if (sessionRatio >= QUEUE_CONFIG.CLAUDE_SESSION_THRESHOLD) {
+          reasons.push(formatWaitingReason('claude_session', sessionPercent, QUEUE_CONFIG.CLAUDE_SESSION_THRESHOLD));
+          this.recordThrottle('claude_session_high');
+        }
+      }
+
+      // Weekly limit
+      if (weeklyPercent !== null) {
+        const weeklyRatio = weeklyPercent / 100;
+        if (weeklyRatio >= 1.0) {
+          oneAtATime = true;
+          this.recordThrottle('claude_weekly_100');
+          if (this.processing.size > 0) {
+            reasons.push('Claude weekly limit is 100% (waiting for current command)');
+          }
+        } else if (weeklyRatio >= QUEUE_CONFIG.CLAUDE_WEEKLY_THRESHOLD) {
+          oneAtATime = true;
+          this.recordThrottle('claude_weekly_high');
+          if (this.processing.size > 0) {
+            reasons.push(formatWaitingReason('claude_weekly', weeklyPercent, QUEUE_CONFIG.CLAUDE_WEEKLY_THRESHOLD) + ' (waiting for current command)');
+          }
+        }
+      }
+    }
+
+    // Check GitHub limits (only relevant if claude processes running)
+    if (hasRunningClaude) {
+      const githubResult = await getCachedGitHubLimits(this.verbose);
+      if (githubResult.success) {
+        const usedPercent = githubResult.githubRateLimit.usedPercentage;
+        const usedRatio = usedPercent / 100;
+        if (usedRatio >= 1.0) {
+          reasons.push('GitHub API limit is 100% (waiting for reset)');
+          this.recordThrottle('github_100');
+        } else if (usedRatio >= QUEUE_CONFIG.GITHUB_API_THRESHOLD) {
+          reasons.push(formatWaitingReason('github', usedPercent, QUEUE_CONFIG.GITHUB_API_THRESHOLD));
+          this.recordThrottle('github_high');
+        }
+      }
+    }
+
+    return { ok: reasons.length === 0, reasons, oneAtATime };
+  }
+
+  /**
+   * Record a throttle event for statistics
+   * @param {string} reason
+   */
+  recordThrottle(reason) {
+    this.stats.throttleReasons[reason] = (this.stats.throttleReasons[reason] || 0) + 1;
+  }
+
+  /**
+   * Ensure consumer task is running
+   */
+  ensureConsumerRunning() {
+    if (this.consumerTask) return;
+
+    this.consumerTask = this.runConsumer();
+    this.consumerTask.catch(error => {
+      console.error('[solve-queue] Consumer error:', error);
+      this.consumerTask = null;
+    });
+  }
+
+  /**
+   * Update item message in Telegram
+   * @param {SolveQueueItem} item
+   * @param {string} text
+   */
+  async updateItemMessage(item, text) {
+    if (!item.messageInfo || !item.ctx) return;
+
+    try {
+      const { chatId, messageId } = item.messageInfo;
+      await item.ctx.telegram.editMessageText(chatId, messageId, undefined, text, { parse_mode: 'Markdown' });
+    } catch (error) {
+      this.log(`Failed to update message: ${error.message}`);
+    }
+  }
+
+  /**
+   * Consumer loop - processes items from the queue
+   */
+  async runConsumer() {
+    this.log('Consumer started');
+
+    while (this.isRunning) {
+      if (this.queue.length === 0) {
+        await this.sleep(QUEUE_CONFIG.CONSUMER_POLL_INTERVAL_MS);
+        continue;
+      }
+
+      const check = await this.canStartCommand();
+
+      if (!check.canStart) {
+        // Update all queued items to waiting status with reason
+        for (const item of this.queue) {
+          if (item.status === QueueItemStatus.QUEUED || item.status === QueueItemStatus.WAITING) {
+            const previousStatus = item.status;
+            const previousReason = item.waitingReason;
+            item.setWaiting(check.reason);
+
+            // Update message if status or reason changed
+            if (previousStatus !== item.status || previousReason !== item.waitingReason) {
+              const position = this.queue.indexOf(item) + 1;
+              await this.updateItemMessage(item, `⏳ Waiting (position #${position})\n\n${item.infoBlock}\n\n*Reason:*\n${check.reason}`);
+            }
+          }
+        }
+
+        this.log(`Throttled: ${check.reason}`);
+        await this.sleep(QUEUE_CONFIG.CONSUMER_POLL_INTERVAL_MS);
+        continue;
+      }
+
+      // Check one-at-a-time mode
+      if (check.oneAtATime && this.processing.size > 0) {
+        this.log('One-at-a-time mode: waiting for current command to finish');
+        await this.sleep(QUEUE_CONFIG.CONSUMER_POLL_INTERVAL_MS);
+        continue;
+      }
+
+      // Get next item from queue
+      const item = this.queue.shift();
+      if (!item) continue;
+
+      // Check if this item uses claude tool and claude is running
+      if (item.tool === 'claude' && check.claudeProcesses > 0) {
+        this.queue.unshift(item);
+        this.log(`Claude tool item queued but claude running, waiting...`);
+        await this.sleep(QUEUE_CONFIG.CONSUMER_POLL_INTERVAL_MS);
+        continue;
+      }
+
+      // Update status to Starting
+      item.setStarting();
+      this.processing.set(item.id, item);
+      this.lastStartTime = Date.now();
+      this.stats.totalStarted++;
+
+      // Update message to show Starting status
+      await this.updateItemMessage(item, `🚀 Starting solve command...\n\n${item.infoBlock}`);
+
+      this.log(`Starting: ${item.toString()}`);
+
+      // Execute in background
+      this.executeItem(item).catch(error => {
+        console.error(`[solve-queue] Execution error for ${item.id}:`, error);
+      });
+    }
+
+    this.log('Consumer stopped');
+    this.consumerTask = null;
+  }
+
+  /**
+   * Execute a queue item
+   * @param {SolveQueueItem} item
+   */
+  async executeItem(item) {
+    try {
+      if (this.executeCallback) {
+        const result = await this.executeCallback(item);
+
+        // Extract session name from result
+        let sessionName = 'unknown';
+        if (result && result.output) {
+          const sessionMatch = result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -r\s+(\S+)/);
+          if (sessionMatch) sessionName = sessionMatch[1];
+        }
+
+        // Update to Started status (terminal - forgets message tracking)
+        item.setStarted(sessionName);
+        this.stats.totalCompleted++;
+
+        // Final message update before forgetting
+        if (item.ctx && result) {
+          const { chatId, messageId } = item.messageInfo || {};
+          if (chatId && messageId) {
+            try {
+              if (result.warning) {
+                await item.ctx.telegram.editMessageText(chatId, messageId, undefined, `⚠️ ${result.warning}`, { parse_mode: 'Markdown' });
+              } else if (result.success) {
+                const response = `✅ Solve command started successfully!\n\n📊 Session: \`${sessionName}\`\n\n${item.infoBlock}`;
+                await item.ctx.telegram.editMessageText(chatId, messageId, undefined, response, { parse_mode: 'Markdown' });
+              } else {
+                const response = `❌ Error executing solve command:\n\n\`\`\`\n${result.error || result.output}\n\`\`\``;
+                await item.ctx.telegram.editMessageText(chatId, messageId, undefined, response, { parse_mode: 'Markdown' });
+              }
+            } catch {
+              // Ignore message edit failures
+            }
+          }
+        }
+      } else {
+        item.setStarted('no-callback');
+        this.stats.totalCompleted++;
+      }
+    } catch (error) {
+      item.setFailed(error);
+      this.stats.totalFailed++;
+      console.error(`[solve-queue] Item failed: ${item.id}`, error);
+
+      // Try to update message with error
+      const { chatId, messageId } = item.messageInfo || {};
+      if (chatId && messageId && item.ctx) {
+        try {
+          await item.ctx.telegram.editMessageText(chatId, messageId, undefined, `❌ Error: ${error.message}`, { parse_mode: 'Markdown' });
+        } catch {
+          // Ignore
+        }
+      }
+    } finally {
+      this.processing.delete(item.id);
+
+      if (item.status === QueueItemStatus.STARTED) {
+        this.completed.push(item);
+      } else if (item.status === QueueItemStatus.FAILED) {
+        this.failed.push(item);
+      }
+
+      this.log(`Finished: ${item.toString()}`);
+
+      // Limit history size
+      while (this.completed.length > 100) this.completed.shift();
+      while (this.failed.length > 100) this.failed.shift();
+    }
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * @param {number} ms
+   * @returns {Promise<void>}
+   */
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Stop the queue
+   */
+  stop() {
+    this.log('Stopping queue...');
+    this.isRunning = false;
+  }
+
+  /**
+   * Clear the limit cache
+   */
+  clearCache() {
+    getLimitCache().clear();
+    this.log('Limit cache cleared');
+  }
+
+  /**
+   * Format queue status for display
+   * @returns {string}
+   */
+  formatStatus() {
+    const stats = this.getStats();
+    if (stats.queued > 0 || stats.processing > 0) {
+      return `Solve Queue: ${stats.queued} pending, ${stats.processing} processing\n`;
+    }
+    return 'Solve Queue: empty\n';
+  }
+
+  /**
+   * Format detailed queue status for Telegram message
+   * @returns {string}
+   */
+  formatDetailedStatus() {
+    const stats = this.getStats();
+    const summary = this.getQueueSummary();
+
+    let message = '📋 *Solve Queue Status*\n\n';
+    message += `Pending: ${stats.queued}\n`;
+    message += `Processing: ${stats.processing}\n`;
+    message += `Completed: ${stats.completed}\n`;
+    message += `Failed: ${stats.failed}\n\n`;
+
+    if (summary.processing.length > 0) {
+      message += '*Currently Processing:*\n';
+      for (const item of summary.processing) {
+        message += `• ${item.url}\n`;
+      }
+      message += '\n';
+    }
+
+    if (summary.pending.length > 0) {
+      message += '*Waiting in Queue:*\n';
+      for (const item of summary.pending.slice(0, 5)) {
+        const waitSeconds = Math.floor(item.waitTime / 1000);
+        message += `• ${item.url} (${item.status}, ${waitSeconds}s)\n`;
+        if (item.waitingReason) {
+          message += `  └ ${item.waitingReason}\n`;
+        }
+      }
+      if (summary.pending.length > 5) {
+        message += `  ... and ${summary.pending.length - 5} more\n`;
+      }
+    }
+
+    return message;
+  }
+}
+
+/**
+ * Global queue instance (singleton)
+ */
+let globalQueue = null;
+
+/**
+ * Get or create the global solve queue instance
+ * @param {Object} options - Queue options
+ * @returns {SolveQueue}
+ */
+export function getSolveQueue(options = {}) {
+  if (!globalQueue) {
+    globalQueue = new SolveQueue(options);
+  } else if (options.verbose !== undefined) {
+    globalQueue.verbose = options.verbose;
+  }
+  return globalQueue;
+}
+
+/**
+ * Reset the global queue (useful for testing)
+ */
+export function resetSolveQueue() {
+  if (globalQueue) {
+    globalQueue.stop();
+    globalQueue = null;
+  }
+}
+
+/**
+ * Create an execute callback for the queue
+ * @param {Function} executeStartScreen - Function to execute start-screen command
+ * @returns {Function} Execute callback for queue items
+ */
+export function createQueueExecuteCallback(executeStartScreen) {
+  return async item => {
+    return await executeStartScreen('solve', item.args);
+  };
+}
+
+export default {
+  SolveQueue,
+  SolveQueueItem,
+  getSolveQueue,
+  resetSolveQueue,
+  getRunningClaudeProcesses,
+  createQueueExecuteCallback,
+  QUEUE_CONFIG,
+  QueueItemStatus,
+};