@link-assistant/hive-mind 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @link-assistant/hive-mind
 
+## 1.6.2
+
+### Patch Changes
+
+- 4ccbbd7: Fix CLAUDE_WEEKLY_THRESHOLD not enforcing one-at-a-time mode when external Claude processes are running
+  - Fixed oneAtATime mode to also consider externally running Claude processes (detected via pgrep), not just queue-internal processing
+  - Standardized all threshold comparisons to use >= (inclusive) instead of mixed > and >= operators
+  - Updated documentation comments to accurately reflect inclusive threshold behavior
+  - Added README recommendation to capture bot logs using tee for post-incident analysis
+  - Added case study documentation for issue #1133
+
+## 1.6.1
+
+### Patch Changes
+
+- b07fa91: Improve /limits output format for better clarity and consistency: use 5m load average for CPU calculation (matching /solve queue), show CPU cores as "X.XX/Y CPU cores used" format consistent with RAM and Disk display
+
 ## 1.6.0
 
 ### Minor Changes
@@ -455,7 +472,7 @@
   - `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_5_HOUR_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

package/README.md

@@ -409,10 +409,26 @@ Want to see the Hive Mind in action? Join our Telegram channel where you can exe
    ```
 
 3. **Start the Bot**
+
    ```bash
    hive-telegram-bot
    ```
 
+   **Recommended: Capture logs with tee**
+
+   When running the bot for extended periods, it's recommended to capture logs to a file using `tee`. This ensures you can review logs later even if the terminal buffer overflows:
+
+   ```bash
+   hive-telegram-bot 2>&1 | tee -a logs/bot-$(date +%Y%m%d).log
+   ```
+
+   Or create a logs directory and start with automatic log rotation:
+
+   ```bash
+   mkdir -p logs
+   hive-telegram-bot 2>&1 | tee -a "logs/bot-$(date +%Y%m%d-%H%M%S).log"
+   ```
+
 ### Bot Commands
 
 All commands work in **group chats only** (not in private messages with the bot):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -13,8 +13,9 @@
     "hive-telegram-bot": "./src/telegram-bot.mjs"
   },
   "scripts": {
-    "test": "node tests/solve-queue.test.mjs && node tests/test-usage-limit.mjs",
+    "test": "node tests/solve-queue.test.mjs && node tests/limits-display.test.mjs && node tests/test-usage-limit.mjs",
     "test:queue": "node tests/solve-queue.test.mjs",
+    "test:limits-display": "node tests/limits-display.test.mjs",
     "test:usage-limit": "node tests/test-usage-limit.mjs",
     "lint": "eslint 'src/**/*.{js,mjs,cjs}'",
     "lint:fix": "eslint 'src/**/*.{js,mjs,cjs}' --fix",

package/src/limits.lib.mjs

@@ -139,6 +139,25 @@ function formatBytes(bytes) {
   return `${value.toFixed(decimals)} ${sizes[i]}`;
 }
 
+/**
+ * Format two byte values into a combined "used/total UNIT used" format
+ * @param {number} usedBytes - Used size in bytes
+ * @param {number} totalBytes - Total size in bytes
+ * @returns {string} Formatted string (e.g., "2.8/11.7 GB used")
+ */
+function formatBytesRange(usedBytes, totalBytes) {
+  if (totalBytes === 0) return '0/0 B used';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  // Determine unit based on total (larger value)
+  const i = Math.floor(Math.log(totalBytes) / Math.log(k));
+  const usedValue = usedBytes / Math.pow(k, i);
+  const totalValue = totalBytes / Math.pow(k, i);
+  // Use 1 decimal place for GB and above, none for smaller units
+  const decimals = i >= 3 ? 1 : 0;
+  return `${usedValue.toFixed(decimals)}/${totalValue.toFixed(decimals)} ${sizes[i]} used`;
+}
+
 /**
  * Get GitHub API rate limits by calling gh api rate_limit
  * Returns rate limit info for core, search, graphql, and other resources
@@ -266,9 +285,10 @@ export async function getCpuLoadInfo(verbose = false) {
       };
     }
 
-    // Calculate usage percentage based on load average vs CPU count
+    // Calculate usage percentage based on 5-minute load average vs CPU count
     // Load average of 1.0 per CPU = 100% utilization
-    const usagePercentage = Math.min(100, Math.round((loadAvg1 / cpuCount) * 100));
+    // Using 5m average for consistency with solve queue (see issue #1137)
+    const usagePercentage = Math.min(100, Math.round((loadAvg5 / cpuCount) * 100));
 
     if (verbose) {
       console.log(`[VERBOSE] /limits CPU load: ${loadAvg1.toFixed(2)} (1m), ${loadAvg5.toFixed(2)} (5m), ${loadAvg15.toFixed(2)} (15m), ${cpuCount} CPUs, ${usagePercentage}% used`);
@@ -663,8 +683,9 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     message += 'CPU\n';
     const usedBar = getProgressBar(cpuLoad.usagePercentage);
     message += `${usedBar} ${cpuLoad.usagePercentage}% used\n`;
-    message += `Load avg: ${cpuLoad.loadAvg1.toFixed(2)} (1m) ${cpuLoad.loadAvg5.toFixed(2)} (5m) ${cpuLoad.loadAvg15.toFixed(2)} (15m)\n`;
-    message += `${cpuLoad.cpuCount} CPU core${cpuLoad.cpuCount > 1 ? 's' : ''}\n\n`;
+    // Show cores used based on 5m load average (e.g., "0.04/6 CPU cores used" or "3/6 CPU cores used")
+    // Use parseFloat to strip unnecessary trailing zeros (3.00 -> 3, 0.10 -> 0.1, 0.04 -> 0.04)
+    message += `${parseFloat(cpuLoad.loadAvg5.toFixed(2))}/${cpuLoad.cpuCount} CPU cores used\n\n`;
   }
 
   // Memory section (if provided)
@@ -672,7 +693,7 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     message += 'RAM\n';
     const usedBar = getProgressBar(memory.usedPercentage);
     message += `${usedBar} ${memory.usedPercentage}% used\n`;
-    message += `${memory.usedFormatted} used of ${memory.totalFormatted}\n\n`;
+    message += `${formatBytesRange(memory.usedBytes, memory.totalBytes)}\n\n`;
   }
 
   // Disk space section (if provided)
@@ -681,7 +702,7 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     // Show used percentage with progress bar
     const usedBar = getProgressBar(diskSpace.usedPercentage);
     message += `${usedBar} ${diskSpace.usedPercentage}% used\n`;
-    message += `${diskSpace.usedFormatted} used of ${diskSpace.totalFormatted}\n\n`;
+    message += `${formatBytesRange(diskSpace.usedBytes, diskSpace.totalBytes)}\n\n`;
   }
 
   // GitHub API rate limits section (if provided)
@@ -699,8 +720,8 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     message += '\n';
   }
 
-  // Current session (five_hour)
-  message += 'Current session\n';
+  // Claude 5 hour session (five_hour)
+  message += 'Claude 5 hour session\n';
   if (usage.currentSession.percentage !== null) {
     // Add time passed progress bar first
     const timePassed = calculateTimePassedPercentage(usage.currentSession.resetsAt, 5);
@@ -710,7 +731,9 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     }
 
     // Add usage progress bar second
-    const pct = usage.currentSession.percentage;
+    // Use Math.floor so 100% only appears when usage is exactly 100%
+    // See: https://github.com/link-assistant/hive-mind/issues/1133
+    const pct = Math.floor(usage.currentSession.percentage);
     const bar = getProgressBar(pct);
     message += `${bar} ${pct}% used\n`;
 
@@ -738,7 +761,9 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     }
 
     // Add usage progress bar second
-    const pct = usage.allModels.percentage;
+    // Use Math.floor so 100% only appears when usage is exactly 100%
+    // See: https://github.com/link-assistant/hive-mind/issues/1133
+    const pct = Math.floor(usage.allModels.percentage);
     const bar = getProgressBar(pct);
     message += `${bar} ${pct}% used\n`;
 
@@ -766,7 +791,9 @@ export function formatUsageMessage(usage, diskSpace = null, githubRateLimit = nu
     }
 
     // Add usage progress bar second
-    const pct = usage.sonnetOnly.percentage;
+    // Use Math.floor so 100% only appears when usage is exactly 100%
+    // See: https://github.com/link-assistant/hive-mind/issues/1133
+    const pct = Math.floor(usage.sonnetOnly.percentage);
     const bar = getProgressBar(pct);
     message += `${bar} ${pct}% used\n`;
 

package/src/telegram-bot.mjs

@@ -858,9 +858,13 @@ bot.command('limits', async ctx => {
   const solveQueue = getSolveQueue({ verbose: VERBOSE });
   const queueStats = solveQueue.getStats();
   const claudeProcs = await getRunningClaudeProcesses(VERBOSE);
+  // Calculate total processing: queue-internal + external claude processes
+  // This provides a uniform view of all processing happening
+  // See: https://github.com/link-assistant/hive-mind/issues/1133
+  const totalProcessing = queueStats.processing + claudeProcs.count;
   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)';
+    const queueStatus = queueStats.queued > 0 || totalProcessing > 0 ? `Pending: ${queueStats.queued}, Processing: ${totalProcessing}` : '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' });

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

@@ -33,15 +33,17 @@ import { getCachedClaudeLimits, getCachedGitHubLimits, getCachedMemoryInfo, getC
  */
 export const QUEUE_CONFIG = {
   // Resource thresholds (usage ratios: 0.0 - 1.0)
-  RAM_THRESHOLD: 0.5, // Stop if RAM usage > 50%
+  // All thresholds use >= comparison (inclusive)
+  RAM_THRESHOLD: 0.5, // Stop if RAM usage >= 50%
   // CPU threshold uses 5-minute load average, not instantaneous CPU usage
-  CPU_THRESHOLD: 0.5, // Stop if 5-minute load average > 50% of CPU count
-  DISK_THRESHOLD: 0.95, // One-at-a-time if disk usage > 95%
+  CPU_THRESHOLD: 0.5, // Stop if 5-minute load average >= 50% of CPU count
+  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
+  // All thresholds use >= comparison (inclusive)
+  CLAUDE_5_HOUR_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: Time to allow solve command to start actual claude process
@@ -135,8 +137,8 @@ function formatWaitingReason(metric, currentValue, threshold) {
       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_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 'github':
@@ -394,22 +396,25 @@ export class SolveQueue {
     const claudeProcs = await getRunningClaudeProcesses(this.verbose);
     const hasRunningClaude = claudeProcs.count > 0;
 
+    // Calculate total processing count: queue-internal + external claude processes
+    // This is used for CLAUDE_5_HOUR_SESSION_THRESHOLD and CLAUDE_WEEKLY_THRESHOLD
+    // to allow exactly one command at a time when threshold is reached
+    // See: https://github.com/link-assistant/hive-mind/issues/1133
+    const totalProcessing = this.processing.size + claudeProcs.count;
+
     // Track claude_running as a metric (but don't add to reasons yet)
     if (hasRunningClaude) {
       this.recordThrottle('claude_running');
     }
 
-    // Check system resources
+    // Check system resources (ultimate restrictions - block unconditionally)
     const resourceCheck = await this.checkSystemResources();
     if (!resourceCheck.ok) {
       reasons.push(...resourceCheck.reasons);
     }
-    if (resourceCheck.oneAtATime) {
-      oneAtATime = true;
-    }
 
-    // Check API limits (pass hasRunningClaude to enable special handling)
-    const limitCheck = await this.checkApiLimits(hasRunningClaude);
+    // Check API limits (pass hasRunningClaude and totalProcessing for uniform checking)
+    const limitCheck = await this.checkApiLimits(hasRunningClaude, totalProcessing);
     if (!limitCheck.ok) {
       reasons.push(...limitCheck.reasons);
     }
@@ -438,6 +443,7 @@ export class SolveQueue {
       reasons,
       oneAtATime,
       claudeProcesses: claudeProcs.count,
+      totalProcessing,
     };
   }
 
@@ -448,17 +454,21 @@ export class SolveQueue {
    * This provides a more stable metric that isn't affected by brief spikes
    * during claude process startup.
    *
-   * @returns {Promise<{ok: boolean, reasons: string[], oneAtATime: boolean}>}
+   * Note: System resource thresholds are ultimate restrictions - they block unconditionally
+   * when triggered. Unlike Claude API thresholds which allow one command at a time via
+   * totalProcessing check, system resources block all new commands immediately.
+   * See: https://github.com/link-assistant/hive-mind/issues/1133
+   *
+   * @returns {Promise<{ok: boolean, reasons: string[]}>}
    */
   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) {
+      if (usedRatio >= QUEUE_CONFIG.RAM_THRESHOLD) {
         reasons.push(formatWaitingReason('ram', memResult.memory.usedPercentage, QUEUE_CONFIG.RAM_THRESHOLD));
         this.recordThrottle('ram_high');
       }
@@ -481,42 +491,45 @@ export class SolveQueue {
         this.log(`CPU 5m load avg: ${loadAvg5.toFixed(2)}, cpus: ${cpuCount}, usage: ${usagePercent}%`);
       }
 
-      if (usageRatio > QUEUE_CONFIG.CPU_THRESHOLD) {
+      if (usageRatio >= QUEUE_CONFIG.CPU_THRESHOLD) {
         reasons.push(formatWaitingReason('cpu', usagePercent, QUEUE_CONFIG.CPU_THRESHOLD));
         this.recordThrottle('cpu_high');
       }
     }
 
     // Check disk space (using cached value)
+    // Note: Disk threshold is an ultimate restriction - it blocks unconditionally when triggered
+    // Unlike CLAUDE_5_HOUR_SESSION_THRESHOLD and CLAUDE_WEEKLY_THRESHOLD which use totalProcessing
+    // to allow one command at a time, disk threshold blocks all new commands immediately
+    // See: https://github.com/link-assistant/hive-mind/issues/1133
     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;
+      if (usedRatio >= QUEUE_CONFIG.DISK_THRESHOLD) {
+        reasons.push(formatWaitingReason('disk', usedPercent, QUEUE_CONFIG.DISK_THRESHOLD));
         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 };
+    return { ok: reasons.length === 0, reasons };
   }
 
   /**
    * Check API limits (Claude, GitHub) using cached values
    *
-   * Simplified logic per issue #1061:
-   * - When any limit >= threshold, allow exactly one claude command to pass
-   * - Only block if there's already a command in progress
-   * - Running claude is the ultimate test of whether limits are really exhausted
+   * Logic per issue #1133:
+   * - CLAUDE_5_HOUR_SESSION_THRESHOLD and CLAUDE_WEEKLY_THRESHOLD use one-at-a-time mode:
+   *   when above threshold, allow exactly one command, block if totalProcessing > 0
+   * - GitHub threshold blocks unconditionally when exceeded (ultimate restriction)
+   * - totalProcessing = queue-internal count + external claude processes (pgrep)
    *
    * @param {boolean} hasRunningClaude - Whether claude processes are running
+   * @param {number} totalProcessing - Total processing count (queue + external claude processes)
    * @returns {Promise<{ok: boolean, reasons: string[], oneAtATime: boolean}>}
    */
-  async checkApiLimits(hasRunningClaude = false) {
+  async checkApiLimits(hasRunningClaude = false, totalProcessing = 0) {
     const reasons = [];
     let oneAtATime = false;
 
@@ -527,15 +540,18 @@ export class SolveQueue {
       const weeklyPercent = claudeResult.usage.allModels.percentage;
 
       // Session limit (5-hour)
-      // When above threshold: allow exactly one command, block if one is running
+      // When above threshold: allow exactly one command, block if any processing is happening
+      // Uses totalProcessing (queue + external claude) for uniform checking
+      // See: https://github.com/link-assistant/hive-mind/issues/1133
       if (sessionPercent !== null) {
         const sessionRatio = sessionPercent / 100;
-        if (sessionRatio >= QUEUE_CONFIG.CLAUDE_SESSION_THRESHOLD) {
-          // Only block if Claude is already running
-          if (hasRunningClaude) {
-            reasons.push(formatWaitingReason('claude_session', sessionPercent, QUEUE_CONFIG.CLAUDE_SESSION_THRESHOLD));
+        if (sessionRatio >= QUEUE_CONFIG.CLAUDE_5_HOUR_SESSION_THRESHOLD) {
+          oneAtATime = true;
+          this.recordThrottle(sessionRatio >= 1.0 ? 'claude_5_hour_session_100' : 'claude_5_hour_session_high');
+          // Use totalProcessing (queue + external claude) for uniform checking
+          if (totalProcessing > 0) {
+            reasons.push(formatWaitingReason('claude_5_hour_session', sessionPercent, QUEUE_CONFIG.CLAUDE_5_HOUR_SESSION_THRESHOLD) + ' (waiting for current command)');
           }
-          this.recordThrottle(sessionRatio >= 1.0 ? 'claude_session_100' : 'claude_session_high');
         }
       }
 
@@ -546,8 +562,9 @@ export class SolveQueue {
         if (weeklyRatio >= QUEUE_CONFIG.CLAUDE_WEEKLY_THRESHOLD) {
           oneAtATime = true;
           this.recordThrottle(weeklyRatio >= 1.0 ? 'claude_weekly_100' : 'claude_weekly_high');
-          // Only block if command is already in progress
-          if (this.processing.size > 0) {
+          // Use totalProcessing (queue + external claude) for uniform checking
+          // See: https://github.com/link-assistant/hive-mind/issues/1133
+          if (totalProcessing > 0) {
             reasons.push(formatWaitingReason('claude_weekly', weeklyPercent, QUEUE_CONFIG.CLAUDE_WEEKLY_THRESHOLD) + ' (waiting for current command)');
           }
         }
@@ -664,8 +681,13 @@ export class SolveQueue {
       }
 
       // 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');
+      // When oneAtATime is true (e.g., weekly limit >= 99%), block if any processing is happening
+      // totalProcessing = queue-internal (this.processing.size) + external claude processes (pgrep)
+      // This ensures uniform checking across all threshold conditions
+      // See: https://github.com/link-assistant/hive-mind/issues/1133
+      if (check.oneAtATime && check.totalProcessing > 0) {
+        const processInfo = check.claudeProcesses > 0 ? ` (${check.claudeProcesses} claude process${check.claudeProcesses > 1 ? 'es' : ''} running)` : '';
+        this.log(`One-at-a-time mode: waiting for current command to finish${processInfo}`);
         await this.sleep(QUEUE_CONFIG.CONSUMER_POLL_INTERVAL_MS);
         continue;
       }