@link-assistant/hive-mind 1.14.2 → 1.15.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @link-assistant/hive-mind
 
+## 1.15.1
+
+### Patch Changes
+
+- docs: Expand auto-cleanup case study with 9 additional solutions (Issue #912)
+
+  Expanded the case study analysis from 6 to 15 solutions covering:
+  - OOM protection (earlyoom, systemd-oomd, OOM score tuning)
+  - Resource isolation (cgroups via systemd)
+  - Log management (logrotate)
+  - Process monitoring (Monit, Supervisord)
+  - Event-driven cleanup (incron)
+  - Resource watchdog scripts
+  - Kubernetes liveness probes and resource limits
+
+  Added tiered recommendation system (Essential, Recommended, Advanced) and updated implementation guide with steps for earlyoom, OOM score tuning, cgroup limits, and logrotate configuration.
+
+  Extract message filter functions to testable module with 34 unit tests for message recognition pipeline (issue #1207)
+
+## 1.15.0
+
+### Minor Changes
+
+- c5dad3c: feat: add --auto-restart-on-non-updated-pull-request-description option (Issue #1162)
+
+  When using `--tool agent` mode, the pull request title and description could remain
+  in their initial WIP placeholder state. This adds an opt-in `--auto-restart-on-non-updated-pull-request-description`
+  flag that detects placeholder content after agent execution and auto-restarts with a
+  short factual hint. Also adds gentle checklist suggestions to agent/opencode/codex prompts
+  (excluding Claude, which handles PR updates naturally).
+
 ## 1.14.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.14.2",
+  "version": "1.15.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -13,7 +13,7 @@
     "hive-telegram-bot": "./src/telegram-bot.mjs"
   },
   "scripts": {
-    "test": "node tests/solve-queue.test.mjs && node tests/limits-display.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 && node tests/test-telegram-message-filters.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",

package/src/agent.prompts.lib.mjs

@@ -184,6 +184,7 @@ Preparing pull request.
    - When there is a package with version and GitHub Actions workflows for automatic release, update the version in your pull request to prepare for next release.
    - When you update existing pr ${prNumber}, use gh pr edit to modify title and description.
    - When you finalize the pull request:
+      check that pull request title and description are updated (the PR may start with a [WIP] prefix and placeholder description that should be replaced with actual title and description of the changes),
       follow style from merged prs for code, title, and description,
       make sure no uncommitted changes corresponding to the original requirements are left behind,
       make sure the default branch is merged to the pull request's branch,

package/src/codex.prompts.lib.mjs

@@ -194,6 +194,7 @@ Preparing pull request.
    - When you update existing pr ${prNumber}, use gh pr edit to modify title and description.
    - When you are about to commit or push code, ALWAYS run local CI checks first if they are available in contributing guidelines (like ruff check, mypy, eslint, etc.) to catch errors before pushing.
    - When you finalize the pull request:
+      check that pull request title and description are updated (the PR may start with a [WIP] prefix and placeholder description that should be replaced with actual title and description of the changes),
       follow style from merged prs for code, title, and description,
       make sure no uncommitted changes corresponding to the original requirements are left behind,
       make sure the default branch is merged to the pull request's branch,

package/src/opencode.prompts.lib.mjs

@@ -187,6 +187,7 @@ Preparing pull request.
    - When there is a package with version and GitHub Actions workflows for automatic release, update the version in your pull request to prepare for next release.
    - When you update existing pr ${prNumber}, use gh pr edit to modify title and description.
    - When you finalize the pull request:
+      check that pull request title and description are updated (the PR may start with a [WIP] prefix and placeholder description that should be replaced with actual title and description of the changes),
       follow style from merged prs for code, title, and description,
       make sure no uncommitted changes corresponding to the original requirements are left behind,
       make sure the default branch is merged to the pull request's branch,

package/src/solve.config.lib.mjs

@@ -210,6 +210,11 @@ export const createYargsConfig = yargsInstance => {
         description: 'Auto-restart until PR becomes mergeable (no iteration limit). Restarts on new comments from non-bot users, CI failures, merge conflicts, or other issues. Does NOT auto-merge.',
         default: false,
       })
+      .option('auto-restart-on-non-updated-pull-request-description', {
+        type: 'boolean',
+        description: 'Automatically restart if PR title or description still contains auto-generated placeholder text after agent execution. Restarts with a hint about what was not updated.',
+        default: false,
+      })
       .option('continue-only-on-feedback', {
         type: 'boolean',
         description: 'Only continue if feedback is detected (works only with pull request link or issue link with --auto-continue)',

package/src/solve.mjs

@@ -1192,6 +1192,57 @@ try {
   const verifyResult = await verifyResults(owner, repo, branchName, issueNumber, prNumber, prUrl, referenceTime, argv, shouldAttachLogs, shouldRestart, sessionId, tempDir, anthropicTotalCostUSD, publicPricingEstimate, pricingInfo, errorDuringExecution, sessionType);
   const logsAlreadyUploaded = verifyResult?.logUploadSuccess || false;
 
+  // Issue #1162: Auto-restart when PR title/description still has placeholder content
+  if (argv.autoRestartOnNonUpdatedPullRequestDescription && (verifyResult?.prTitleHasPlaceholder || verifyResult?.prBodyHasPlaceholder)) {
+    const { buildPRNotUpdatedHint } = results;
+    const hintLines = buildPRNotUpdatedHint(verifyResult.prTitleHasPlaceholder, verifyResult.prBodyHasPlaceholder);
+
+    await log('');
+    await log('🔄 AUTO-RESTART: PR title/description not updated by agent');
+    hintLines.forEach(async line => await log(`   ${line}`));
+    await log('   Restarting tool to give agent another chance to update...');
+    await log('');
+
+    // Import executeToolIteration for re-execution
+    const { executeToolIteration } = await import('./solve.restart-shared.lib.mjs');
+
+    // Re-execute tool with hint as feedback lines
+    const restartResult = await executeToolIteration({
+      issueUrl,
+      owner,
+      repo,
+      issueNumber,
+      prNumber,
+      branchName,
+      tempDir,
+      mergeStateStatus,
+      feedbackLines: hintLines,
+      argv: {
+        ...argv,
+        // Disable auto-restart for this iteration to prevent infinite loops
+        autoRestartOnNonUpdatedPullRequestDescription: false,
+      },
+    });
+
+    // Update session data from restart
+    if (restartResult) {
+      if (restartResult.sessionId) sessionId = restartResult.sessionId;
+      if (restartResult.anthropicTotalCostUSD) anthropicTotalCostUSD = restartResult.anthropicTotalCostUSD;
+      if (restartResult.publicPricingEstimate) publicPricingEstimate = restartResult.publicPricingEstimate;
+      if (restartResult.pricingInfo) pricingInfo = restartResult.pricingInfo;
+    }
+
+    // Clean up CLAUDE.md/.gitkeep again after restart
+    await cleanupClaudeFile(tempDir, branchName, null, argv);
+
+    // Re-verify results after restart (without auto-restart flag to prevent recursion)
+    const reVerifyResult = await verifyResults(owner, repo, branchName, issueNumber, prNumber, prUrl, referenceTime, { ...argv, autoRestartOnNonUpdatedPullRequestDescription: false }, shouldAttachLogs, false, sessionId, tempDir, anthropicTotalCostUSD, publicPricingEstimate, pricingInfo, errorDuringExecution, sessionType);
+
+    if (reVerifyResult?.prTitleHasPlaceholder || reVerifyResult?.prBodyHasPlaceholder) {
+      await log('⚠️  PR title/description still not updated after restart');
+    }
+  }
+
   // Start watch mode if enabled OR if we need to handle uncommitted changes
   if (argv.verbose) {
     await log('');

package/src/solve.results.lib.mjs

@@ -47,6 +47,51 @@ const { reportError } = sentryLib;
 const githubLinking = await import('./github-linking.lib.mjs');
 const { hasGitHubLinkingKeyword } = githubLinking;
 
+/**
+ * Placeholder patterns used to detect auto-generated PR content that was not updated by the agent.
+ * These patterns match the initial WIP PR created by solve.auto-pr.lib.mjs.
+ */
+export const PR_TITLE_PLACEHOLDER_PREFIX = '[WIP]';
+
+export const PR_BODY_PLACEHOLDER_PATTERNS = ['_Details will be added as the solution draft is developed..._', '**Work in Progress** - The AI assistant is currently analyzing and implementing the solution draft.', '### 🚧 Status'];
+
+/**
+ * Check if PR title still contains auto-generated placeholder content
+ * @param {string} title - PR title
+ * @returns {boolean} - true if title has placeholder content
+ */
+export const hasPRTitlePlaceholder = title => {
+  return title && title.startsWith(PR_TITLE_PLACEHOLDER_PREFIX);
+};
+
+/**
+ * Check if PR body still contains auto-generated placeholder content
+ * @param {string} body - PR body
+ * @returns {boolean} - true if body has placeholder content
+ */
+export const hasPRBodyPlaceholder = body => {
+  return body && PR_BODY_PLACEHOLDER_PATTERNS.some(pattern => body.includes(pattern));
+};
+
+/**
+ * Build a short factual hint for auto-restart when PR title/description was not updated.
+ * Uses neutral, fact-stating language (no forcing words).
+ * @param {boolean} titleNotUpdated - Whether the PR title still has placeholder
+ * @param {boolean} descriptionNotUpdated - Whether the PR description still has placeholder
+ * @returns {string[]} - Array of feedback lines to pass as hint to the restarted session
+ */
+export const buildPRNotUpdatedHint = (titleNotUpdated, descriptionNotUpdated) => {
+  const lines = [];
+  if (titleNotUpdated && descriptionNotUpdated) {
+    lines.push('Pull request title and description were not updated.');
+  } else if (titleNotUpdated) {
+    lines.push('Pull request title was not updated.');
+  } else if (descriptionNotUpdated) {
+    lines.push('Pull request description was not updated.');
+  }
+  return lines;
+};
+
 /**
  * Detect the CLAUDE.md or .gitkeep commit hash from branch structure when not available in session
  * This handles continue mode where the commit hash was lost between sessions
@@ -465,12 +510,17 @@ export const verifyResults = async (owner, repo, branchName, issueNumber, prNumb
           await log(`  ℹ️  PR #${pr.number} was merged during the session`);
         }
 
+        // Declare placeholder detection variables outside block scopes for use in return value
+        let prTitleHasPlaceholder = false;
+        let prBodyHasPlaceholder = false;
+
         // Skip PR body update and ready conversion for merged PRs (they can't be edited)
         if (!isPrMerged) {
           // Check if PR body has proper issue linking keywords
+          let prBody = '';
           const prBodyResult = await $`gh pr view ${pr.number} --repo ${owner}/${repo} --json body --jq .body`;
           if (prBodyResult.code === 0) {
-            const prBody = prBodyResult.stdout.toString();
+            prBody = prBodyResult.stdout.toString();
             const issueRef = argv.fork ? `${owner}/${repo}#${issueNumber}` : `#${issueNumber}`;
 
             // Use the new GitHub linking detection library to check for valid keywords
@@ -513,6 +563,80 @@ export const verifyResults = async (owner, repo, branchName, issueNumber, prNumb
             }
           }
 
+          // Issue #1162: Detect if PR title/description still have auto-generated placeholder content
+          // Track this before cleanup for --auto-restart-on-non-updated-pull-request-description
+          prTitleHasPlaceholder = hasPRTitlePlaceholder(pr.title);
+          prBodyHasPlaceholder = hasPRBodyPlaceholder(prBody);
+
+          // Issue #1162: Remove [WIP] prefix from title if still present
+          // Skip cleanup if auto-restart-on-non-updated-pull-request-description is enabled
+          // (let the agent handle it on restart instead)
+          if (prTitleHasPlaceholder && !argv.autoRestartOnNonUpdatedPullRequestDescription) {
+            const updatedTitle = pr.title.replace(/^\[WIP\]\s*/, '');
+            await log(`  📝 Removing [WIP] prefix from PR title...`);
+            const titleResult = await $`gh pr edit ${pr.number} --repo ${owner}/${repo} --title "${updatedTitle}"`;
+            if (titleResult.code === 0) {
+              await log(`  ✅ Updated PR title to: "${updatedTitle}"`);
+            } else {
+              await log(`  ⚠️  Could not update PR title: ${titleResult.stderr ? titleResult.stderr.toString().trim() : 'Unknown error'}`);
+            }
+          }
+
+          // Issue #1162: Update PR description if still contains placeholder text
+          // Skip cleanup if auto-restart-on-non-updated-pull-request-description is enabled
+          const hasPlaceholder = prBodyHasPlaceholder;
+          if (hasPlaceholder && !argv.autoRestartOnNonUpdatedPullRequestDescription) {
+            await log(`  📝 Updating PR description to remove placeholder text...`);
+
+            // Build a summary of the changes from the PR diff
+            const diffResult = await $`gh pr diff ${pr.number} --repo ${owner}/${repo} 2>&1`;
+            const diffOutput = diffResult.code === 0 ? diffResult.stdout.toString() : '';
+
+            // Count files changed
+            const filesChanged = (diffOutput.match(/^diff --git/gm) || []).length;
+            const additions = (diffOutput.match(/^\+[^+]/gm) || []).length;
+            const deletions = (diffOutput.match(/^-[^-]/gm) || []).length;
+
+            // Get the issue title for context
+            const issueTitleResult = await $`gh issue view ${issueNumber} --repo ${owner}/${repo} --json title --jq .title 2>&1`;
+            const issueTitle = issueTitleResult.code === 0 ? issueTitleResult.stdout.toString().trim() : 'the issue';
+
+            // Build new description
+            const fs = (await use('fs')).promises;
+            const issueRef = argv.fork ? `${owner}/${repo}#${issueNumber}` : `#${issueNumber}`;
+            const newDescription = `## Summary
+
+This pull request implements a solution for ${issueRef}: ${issueTitle}
+
+### Changes
+- ${filesChanged} file(s) modified
+- ${additions} line(s) added
+- ${deletions} line(s) removed
+
+### Issue Reference
+Fixes ${issueRef}
+
+---
+*This PR was created automatically by the AI issue solver*`;
+
+            const tempBodyFile = `/tmp/pr-body-finalize-${pr.number}-${Date.now()}.md`;
+            await fs.writeFile(tempBodyFile, newDescription);
+
+            try {
+              const descResult = await $`gh pr edit ${pr.number} --repo ${owner}/${repo} --body-file "${tempBodyFile}"`;
+              await fs.unlink(tempBodyFile).catch(() => {});
+
+              if (descResult.code === 0) {
+                await log(`  ✅ Updated PR description with solution summary`);
+              } else {
+                await log(`  ⚠️  Could not update PR description: ${descResult.stderr ? descResult.stderr.toString().trim() : 'Unknown error'}`);
+              }
+            } catch (descError) {
+              await fs.unlink(tempBodyFile).catch(() => {});
+              await log(`  ⚠️  Error updating PR description: ${descError.message}`);
+            }
+          }
+
           // Check if PR is ready for review (convert from draft if necessary)
           if (pr.isDraft) {
             await log('  🔄 Converting PR from draft to ready for review...');
@@ -563,11 +687,17 @@ export const verifyResults = async (owner, repo, branchName, issueNumber, prNumb
         }
         await log('\n✨ Please review the pull request for the proposed solution draft.');
         // Don't exit if watch mode is enabled OR if auto-restart is needed for uncommitted changes
-        if (!argv.watch && !shouldRestart) {
+        // Also don't exit if auto-restart-on-non-updated-pull-request-description detected placeholders
+        const shouldAutoRestartForPlaceholder = argv.autoRestartOnNonUpdatedPullRequestDescription && (prTitleHasPlaceholder || prBodyHasPlaceholder);
+        if (shouldAutoRestartForPlaceholder) {
+          await log('\n🔄 Placeholder detected in PR title/description - auto-restart will be triggered');
+        }
+        if (!argv.watch && !shouldRestart && !shouldAutoRestartForPlaceholder) {
           await safeExit(0, 'Process completed successfully');
         }
         // Issue #1154: Return logUploadSuccess to prevent duplicate log uploads
-        return { logUploadSuccess }; // Return for watch mode or auto-restart
+        // Issue #1162: Return placeholder detection status for auto-restart
+        return { logUploadSuccess, prTitleHasPlaceholder, prBodyHasPlaceholder }; // Return for watch mode or auto-restart
       } else {
         await log(`  ℹ️  Found pull request #${pr.number} but it appears to be from a different session`);
       }

package/src/telegram-bot.mjs

@@ -43,6 +43,8 @@ const { formatUsageMessage, getAllCachedLimits } = await import('./limits.lib.mj
 const { getVersionInfo, formatVersionMessage } = await import('./version-info.lib.mjs');
 const { escapeMarkdown, escapeMarkdownV2, cleanNonPrintableChars, makeSpecialCharsVisible } = await import('./telegram-markdown.lib.mjs');
 const { getSolveQueue, getRunningClaudeProcesses, createQueueExecuteCallback } = await import('./telegram-solve-queue.lib.mjs');
+// Import extracted message filter functions for testability (issue #1207)
+const { isOldMessage: _isOldMessage, isGroupChat: _isGroupChat, isChatAuthorized: _isChatAuthorized, isForwardedOrReply: _isForwardedOrReply, extractCommandFromText } = await import('./telegram-message-filters.lib.mjs');
 
 const config = yargs(hideBin(process.argv))
   .usage('Usage: hive-telegram-bot [options]')
@@ -291,100 +293,22 @@ const bot = new Telegraf(BOT_TOKEN, {
 // Using Unix timestamp (seconds since epoch) to match Telegram's message.date format
 const BOT_START_TIME = Math.floor(Date.now() / 1000);
 
+// Wrapper functions that bind extracted filter functions to bot-specific state
+// The actual logic is in telegram-message-filters.lib.mjs for testability (issue #1207)
 function isChatAuthorized(chatId) {
-  if (!allowedChats) {
-    return true;
-  }
-  return allowedChats.includes(chatId);
+  return _isChatAuthorized(chatId, allowedChats);
 }
 
 function isOldMessage(ctx) {
-  // Ignore messages sent before the bot started
-  // This prevents processing old/pending messages from before current bot instance startup
-  const messageDate = ctx.message?.date;
-  if (!messageDate) {
-    return false;
-  }
-  return messageDate < BOT_START_TIME;
+  return _isOldMessage(ctx, BOT_START_TIME, { verbose: VERBOSE });
 }
 
 function isGroupChat(ctx) {
-  const chatType = ctx.chat?.type;
-  return chatType === 'group' || chatType === 'supergroup';
+  return _isGroupChat(ctx);
 }
 
 function isForwardedOrReply(ctx) {
-  const message = ctx.message;
-  if (!message) {
-    if (VERBOSE) {
-      console.log('[VERBOSE] isForwardedOrReply: No message object');
-    }
-    return false;
-  }
-
-  if (VERBOSE) {
-    console.log('[VERBOSE] isForwardedOrReply: Checking message fields...');
-    console.log('[VERBOSE]   message.forward_origin:', JSON.stringify(message.forward_origin));
-    console.log('[VERBOSE]   message.forward_origin?.type:', message.forward_origin?.type);
-    console.log('[VERBOSE]   message.forward_from:', JSON.stringify(message.forward_from));
-    console.log('[VERBOSE]   message.forward_from_chat:', JSON.stringify(message.forward_from_chat));
-    console.log('[VERBOSE]   message.forward_from_message_id:', message.forward_from_message_id);
-    console.log('[VERBOSE]   message.forward_signature:', message.forward_signature);
-    console.log('[VERBOSE]   message.forward_sender_name:', message.forward_sender_name);
-    console.log('[VERBOSE]   message.forward_date:', message.forward_date);
-    console.log('[VERBOSE]   message.reply_to_message:', JSON.stringify(message.reply_to_message));
-    console.log('[VERBOSE]   message.reply_to_message?.message_id:', message.reply_to_message?.message_id);
-  }
-
-  // Check if message is forwarded (has forward_origin field with actual content)
-  // Note: We check for .type because Telegram might send empty objects {}
-  // which are truthy in JavaScript but don't indicate a forwarded message
-  if (message.forward_origin && message.forward_origin.type) {
-    if (VERBOSE) {
-      console.log('[VERBOSE] isForwardedOrReply: TRUE - forward_origin.type exists:', message.forward_origin.type);
-    }
-    return true;
-  }
-  // Also check old forwarding API fields for backward compatibility
-  if (message.forward_from || message.forward_from_chat || message.forward_from_message_id || message.forward_signature || message.forward_sender_name || message.forward_date) {
-    if (VERBOSE) {
-      console.log('[VERBOSE] isForwardedOrReply: TRUE - old forwarding API field detected');
-      if (message.forward_from) console.log('[VERBOSE]     Triggered by: forward_from');
-      if (message.forward_from_chat) console.log('[VERBOSE]     Triggered by: forward_from_chat');
-      if (message.forward_from_message_id) console.log('[VERBOSE]     Triggered by: forward_from_message_id');
-      if (message.forward_signature) console.log('[VERBOSE]     Triggered by: forward_signature');
-      if (message.forward_sender_name) console.log('[VERBOSE]     Triggered by: forward_sender_name');
-      if (message.forward_date) console.log('[VERBOSE]     Triggered by: forward_date');
-    }
-    return true;
-  }
-  // Check if message is a reply (has reply_to_message field with actual content)
-  // Note: We check for .message_id because Telegram might send empty objects {}
-  // IMPORTANT: In forum groups, messages in topics have reply_to_message pointing to the topic's
-  // first message (with forum_topic_created). These are NOT user replies, just part of the thread.
-  // We must exclude these to allow commands in forum topics.
-  if (message.reply_to_message && message.reply_to_message.message_id) {
-    // If the reply_to_message is a forum topic creation message, this is NOT a user reply
-    if (message.reply_to_message.forum_topic_created) {
-      if (VERBOSE) {
-        console.log('[VERBOSE] isForwardedOrReply: FALSE - reply is to forum topic creation, not user reply');
-        console.log('[VERBOSE]   Forum topic:', message.reply_to_message.forum_topic_created);
-      }
-      // This is just a message in a forum topic, not a reply to another user
-      // Allow the message to proceed
-    } else {
-      // This is an actual reply to another user's message
-      if (VERBOSE) {
-        console.log('[VERBOSE] isForwardedOrReply: TRUE - reply_to_message.message_id exists:', message.reply_to_message.message_id);
-      }
-      return true;
-    }
-  }
-
-  if (VERBOSE) {
-    console.log('[VERBOSE] isForwardedOrReply: FALSE - no forwarding or reply detected');
-  }
-  return false;
+  return _isForwardedOrReply(ctx, { verbose: VERBOSE });
 }
 
 async function findStartScreenCommand() {
@@ -915,7 +839,8 @@ registerMergeCommand(bot, {
   addBreadcrumb,
 });
 
-bot.command(/^solve$/i, async ctx => {
+// Named handler for /solve command - extracted for reuse by text-based fallback (issue #1207)
+async function handleSolveCommand(ctx) {
   if (VERBOSE) {
     console.log('[VERBOSE] /solve command received');
   }
@@ -1115,9 +1040,12 @@ bot.command(/^solve$/i, async ctx => {
     queueItem.messageInfo = { chatId: queuedMessage.chat.id, messageId: queuedMessage.message_id };
     if (!solveQueue.executeCallback) solveQueue.executeCallback = createQueueExecuteCallback(executeStartScreen);
   }
-});
+}
+
+bot.command(/^solve$/i, handleSolveCommand);
 
-bot.command(/^hive$/i, async ctx => {
+// Named handler for /hive command - extracted for reuse by text-based fallback (issue #1207)
+async function handleHiveCommand(ctx) {
   if (VERBOSE) {
     console.log('[VERBOSE] /hive command received');
   }
@@ -1252,7 +1180,9 @@ bot.command(/^hive$/i, async ctx => {
 
   const startingMessage = await ctx.reply(`🚀 Starting hive command...\n\n${infoBlock}`, { parse_mode: 'Markdown', reply_to_message_id: ctx.message.message_id });
   await executeAndUpdateMessage(ctx, startingMessage, 'hive', args, infoBlock);
-});
+}
+
+bot.command(/^hive$/i, handleHiveCommand);
 
 // Register /top command from separate module
 // This keeps telegram-bot.mjs under the 1500 line limit
@@ -1285,6 +1215,10 @@ if (VERBOSE) {
     });
     if (msg) {
       console.log('[VERBOSE] Msg fields:', Object.keys(msg));
+      // Log entities for command matching diagnostics (issue #1207)
+      if (msg.entities) {
+        console.log('[VERBOSE] Entities:', JSON.stringify(msg.entities));
+      }
       console.log('[VERBOSE] Forward/reply:', {
         forward_origin: msg.forward_origin,
         forward_from: msg.forward_from,
@@ -1299,6 +1233,45 @@ if (VERBOSE) {
   });
 }
 
+// Text-based fallback for command matching (issue #1207)
+// Telegraf's bot.command() relies on Telegram's bot_command entities. In rare cases,
+// messages may not have the expected entity at offset 0 (e.g., certain clients, edge cases
+// with message formatting, or entity ordering), causing bot.command() to silently skip
+// the message. This fallback uses text pattern matching to catch those missed commands.
+// It runs AFTER bot.command() handlers, so it only fires when entity-based matching fails.
+bot.on('message', async (ctx, next) => {
+  const text = ctx.message?.text;
+  if (!text) return next();
+
+  // Extract command from text using the testable filter function
+  // Note: We pass null for botUsername here and check it separately with ctx.me
+  // which is set by Telegraf after bot initialization
+  const extracted = extractCommandFromText(text);
+  if (!extracted) return next();
+
+  // If command mentions a specific bot, verify it's us
+  if (extracted.botMention) {
+    const myUsername = ctx.me; // Telegraf sets this from getMe()
+    if (!myUsername || extracted.botMention.toLowerCase() !== myUsername.toLowerCase()) {
+      return next(); // Command is for a different bot or we can't verify
+    }
+  }
+
+  // Check if this is a command we handle
+  const handlers = {
+    solve: handleSolveCommand,
+    hive: handleHiveCommand,
+  };
+
+  const handler = handlers[extracted.command];
+  if (!handler) return next();
+
+  // Log that fallback was triggered - this indicates bot.command() entity matching failed
+  console.warn(`[WARNING] Command /${extracted.command} matched by text fallback, not by entity-based bot.command(). ` + `Entities: ${JSON.stringify(ctx.message.entities || [])}. ` + `User: ${ctx.from?.username || ctx.from?.id}. ` + `This may indicate a Telegram client entity issue (issue #1207).`);
+
+  await handler(ctx);
+});
+
 // Add global error handler for uncaught errors in middleware
 bot.catch((error, ctx) => {
   console.error('Unhandled error while processing update', ctx.update.update_id);

package/src/telegram-message-filters.lib.mjs

@@ -0,0 +1,173 @@
+/**
+ * Message filtering functions for Telegram bot.
+ * Extracted from telegram-bot.mjs for testability and reuse.
+ *
+ * These filters determine whether incoming messages should be processed
+ * or silently ignored by the bot's command handlers.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/1207
+ * @see https://core.telegram.org/bots/features#privacy-mode
+ */
+
+/**
+ * Check if a message was sent before the bot started.
+ * Prevents processing old/pending messages from before the current bot instance startup.
+ *
+ * @param {Object} ctx - Telegraf context object
+ * @param {number} botStartTime - Unix timestamp (seconds) of when bot started
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.verbose] - Enable verbose logging
+ * @returns {boolean} true if message is old and should be ignored
+ */
+export function isOldMessage(ctx, botStartTime, options = {}) {
+  const messageDate = ctx.message?.date;
+  if (!messageDate) {
+    return false;
+  }
+  const isOld = messageDate < botStartTime;
+  if (options.verbose && isOld) {
+    console.log(`[VERBOSE] isOldMessage: TRUE - message date ${messageDate} < bot start ${botStartTime}`);
+  }
+  return isOld;
+}
+
+/**
+ * Check if the chat is a group or supergroup.
+ *
+ * @param {Object} ctx - Telegraf context object
+ * @returns {boolean} true if chat is a group or supergroup
+ */
+export function isGroupChat(ctx) {
+  const chatType = ctx.chat?.type;
+  return chatType === 'group' || chatType === 'supergroup';
+}
+
+/**
+ * Check if a chat ID is in the allowed chats whitelist.
+ *
+ * @param {number} chatId - The chat ID to check
+ * @param {number[]|null} allowedChats - Array of allowed chat IDs, or null for no restrictions
+ * @returns {boolean} true if chat is authorized
+ */
+export function isChatAuthorized(chatId, allowedChats) {
+  if (!allowedChats) {
+    return true;
+  }
+  return allowedChats.includes(chatId);
+}
+
+/**
+ * Check if a message is forwarded or a reply to another user's message.
+ *
+ * This function distinguishes between:
+ * 1. Forwarded messages (should be ignored)
+ * 2. User replies to other messages (should be ignored, except for /solve reply feature)
+ * 3. Forum topic messages (should NOT be ignored - they have reply_to_message pointing
+ *    to the topic's first message with forum_topic_created)
+ * 4. Normal messages (should NOT be ignored)
+ *
+ * @param {Object} ctx - Telegraf context object
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.verbose] - Enable verbose logging
+ * @returns {boolean} true if message is forwarded or a reply (and should be filtered)
+ */
+export function isForwardedOrReply(ctx, options = {}) {
+  const message = ctx.message;
+  if (!message) {
+    if (options.verbose) {
+      console.log('[VERBOSE] isForwardedOrReply: No message object');
+    }
+    return false;
+  }
+
+  if (options.verbose) {
+    console.log('[VERBOSE] isForwardedOrReply: Checking message fields...');
+    console.log('[VERBOSE]   message.forward_origin:', JSON.stringify(message.forward_origin));
+    console.log('[VERBOSE]   message.forward_origin?.type:', message.forward_origin?.type);
+    console.log('[VERBOSE]   message.forward_from:', JSON.stringify(message.forward_from));
+    console.log('[VERBOSE]   message.forward_from_chat:', JSON.stringify(message.forward_from_chat));
+    console.log('[VERBOSE]   message.forward_from_message_id:', message.forward_from_message_id);
+    console.log('[VERBOSE]   message.forward_signature:', message.forward_signature);
+    console.log('[VERBOSE]   message.forward_sender_name:', message.forward_sender_name);
+    console.log('[VERBOSE]   message.forward_date:', message.forward_date);
+    console.log('[VERBOSE]   message.reply_to_message:', JSON.stringify(message.reply_to_message));
+    console.log('[VERBOSE]   message.reply_to_message?.message_id:', message.reply_to_message?.message_id);
+  }
+
+  // Check if message is forwarded (has forward_origin field with actual content)
+  // Note: We check for .type because Telegram might send empty objects {}
+  // which are truthy in JavaScript but don't indicate a forwarded message
+  if (message.forward_origin && message.forward_origin.type) {
+    if (options.verbose) {
+      console.log('[VERBOSE] isForwardedOrReply: TRUE - forward_origin.type exists:', message.forward_origin.type);
+    }
+    return true;
+  }
+  // Also check old forwarding API fields for backward compatibility
+  if (message.forward_from || message.forward_from_chat || message.forward_from_message_id || message.forward_signature || message.forward_sender_name || message.forward_date) {
+    if (options.verbose) {
+      console.log('[VERBOSE] isForwardedOrReply: TRUE - old forwarding API field detected');
+    }
+    return true;
+  }
+  // Check if message is a reply (has reply_to_message field with actual content)
+  // Note: We check for .message_id because Telegram might send empty objects {}
+  // IMPORTANT: In forum groups, messages in topics have reply_to_message pointing to the topic's
+  // first message (with forum_topic_created). These are NOT user replies, just part of the thread.
+  // We must exclude these to allow commands in forum topics.
+  if (message.reply_to_message && message.reply_to_message.message_id) {
+    // If the reply_to_message is a forum topic creation message, this is NOT a user reply
+    if (message.reply_to_message.forum_topic_created) {
+      if (options.verbose) {
+        console.log('[VERBOSE] isForwardedOrReply: FALSE - reply is to forum topic creation, not user reply');
+        console.log('[VERBOSE]   Forum topic:', message.reply_to_message.forum_topic_created);
+      }
+      // This is just a message in a forum topic, not a reply to another user
+      // Allow the message to proceed
+    } else {
+      // This is an actual reply to another user's message
+      if (options.verbose) {
+        console.log('[VERBOSE] isForwardedOrReply: TRUE - reply_to_message.message_id exists:', message.reply_to_message.message_id);
+      }
+      return true;
+    }
+  }
+
+  if (options.verbose) {
+    console.log('[VERBOSE] isForwardedOrReply: FALSE - no forwarding or reply detected');
+  }
+  return false;
+}
+
+/**
+ * Extract a bot command from message text using text-based pattern matching.
+ * This is a fallback for when Telegraf's entity-based bot.command() fails
+ * to match due to missing or malformed bot_command entities.
+ *
+ * @param {string} text - Message text
+ * @param {string|null} [botUsername] - Bot's username for @mention validation (case-insensitive)
+ * @returns {{ command: string, botMention: string|null } | null} Extracted command info, or null if no command found
+ * @see https://github.com/link-assistant/hive-mind/issues/1207
+ */
+export function extractCommandFromText(text, botUsername = null) {
+  if (!text || typeof text !== 'string') {
+    return null;
+  }
+
+  const match = text.match(/^\/(\w+)(?:@(\S+))?\s*/);
+  if (!match) {
+    return null;
+  }
+
+  const command = match[1].toLowerCase();
+  const botMention = match[2] || null;
+
+  // If command mentions a specific bot, verify it matches ours
+  if (botMention && botUsername) {
+    if (botMention.toLowerCase() !== botUsername.toLowerCase()) {
+      return null; // Command is for a different bot
+    }
+  }
+
+  return { command, botMention };
+}