@link-assistant/hive-mind 2.13.1 → 2.13.3

package/src/telegram-start-stop-command.lib.mjs

@@ -31,6 +31,9 @@
 import { extractSessionIdFromText } from './telegram-log-command.lib.mjs';
 import { parseGitHubUrl } from './github.lib.mjs';
 import { cleanNonPrintableChars } from './telegram-markdown.lib.mjs';
+// Issue #2166: every reply/edit in this module goes through the one send funnel
+// (validated, logged, plain-text fallback) even when a caller does not inject it.
+import { safeReply as defaultSafeReply, safeEditMessageText as defaultSafeEditMessageText } from './telegram-safe-reply.lib.mjs';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -146,7 +149,9 @@ function findFirstIssueOrPullUrl(text) {
     if (!word) continue;
     const parsed = parseGitHubUrl(word);
     if (parsed.valid && (parsed.type === 'issue' || parsed.type === 'pull')) {
-      return parsed.normalized;
+      // Issue #2166: match on what the bot interprets, not on the fragment the
+      // user happened to copy along with the link.
+      return parsed.canonical || parsed.normalized;
     }
   }
   return null;
@@ -203,14 +208,17 @@ export function extractStopTarget(text, repliedTo) {
  * @returns {Promise<boolean>} true when the card was edited
  * @see https://github.com/link-assistant/hive-mind/issues/1783
  */
-export async function updateQueueCardForCancellation(item, url, tool, stopperName) {
+export async function updateQueueCardForCancellation(item, url, tool, stopperName, { safeEditMessageText = defaultSafeEditMessageText, verbose = false } = {}) {
   if (!item || !item.messageInfo || !item.ctx) return false;
   const toolSuffix = tool ? ` from \`${tool}\` queue` : '';
   const stopperSuffix = stopperName ? ` by ${stopperName}` : '';
   const text = `🗑 *Cancelled*\n\n${url}\n\nRemoved${toolSuffix}${stopperSuffix} via /stop.`;
   try {
     const { chatId, messageId } = item.messageInfo;
-    await item.ctx.telegram.editMessageText(chatId, messageId, undefined, text, { parse_mode: 'Markdown' });
+    // Issue #2166: go through the shared safe funnel when the caller provides
+    // it, so a card whose URL contains Markdown-significant characters is
+    // still updated (as plain text) instead of failing silently.
+    await safeEditMessageText(item.ctx.telegram, chatId, messageId, undefined, text, { verbose });
     // Match the consumer's contract: once a card reaches a terminal state we
     // forget the message coordinates so nothing else tries to edit it.
     item.messageInfo = null;
@@ -270,7 +278,10 @@ export function isStopTargetRequester({ userId, queueItem = null, sessionInfo =
  *   See https://github.com/link-assistant/hive-mind/issues/1871.
  */
 export function registerStartStopCommands(bot, options) {
-  const { VERBOSE = false, isOldMessage, isForwarded, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, getSolveQueue } = options;
+  // Issue #2166: every reply goes through the shared safe-send funnel (pre-send
+  // validation, audit log, plain-text fallback). The defaults keep the module
+  // usable in isolation (tests) without a bot wired up.
+  const { VERBOSE = false, isOldMessage, isForwarded, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, getSolveQueue, safeReply = defaultSafeReply, safeEditMessageText = defaultSafeEditMessageText } = options;
   const stopIsolatedSessionImpl = options.stopIsolatedSession || (async (...args) => (await import('./isolation-runner.lib.mjs')).stopIsolatedSession(...args));
   // Issue #1783: look the UUID up in the session monitor so /stop can let the
   // user who started the task stop it (mirrors /terminal_watch from PR #1779).
@@ -344,25 +355,25 @@ export function registerStartStopCommands(bot, options) {
     if (!isGroupChat(ctx)) {
       if (opts.allowPrivate) return { valid: false, isPrivate: true };
       VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: not a group chat`);
-      await ctx.reply(`❌ The ${cmdName} command only works in group chats.`, { reply_to_message_id: ctx.message.message_id });
+      await safeReply(ctx, `❌ The ${cmdName} command only works in group chats.`, { reply_to_message_id: ctx.message.message_id });
       return { valid: false };
     }
     const chatId = ctx.chat.id;
     if (!isChatAuthorized(chatId)) {
       VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: chat not authorized`);
-      await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot.`, { reply_to_message_id: ctx.message.message_id });
+      await safeReply(ctx, `❌ This chat (ID: ${chatId}) is not authorized to use this bot.`, { reply_to_message_id: ctx.message.message_id });
       return { valid: false };
     }
     try {
       const chatMember = await ctx.telegram.getChatMember(chatId, ctx.from.id);
       if (chatMember.status !== 'creator') {
         VERBOSE && console.log(`[VERBOSE] ${cmdName} ignored: user is not chat owner`);
-        await ctx.reply('❌ This command is only available to the chat owner.', { reply_to_message_id: ctx.message.message_id });
+        await safeReply(ctx, '❌ This command is only available to the chat owner.', { reply_to_message_id: ctx.message.message_id });
         return { valid: false };
       }
     } catch (error) {
       console.error('[ERROR] Failed to check chat member status:', error);
-      await ctx.reply('❌ Failed to verify permissions.', { reply_to_message_id: ctx.message.message_id });
+      await safeReply(ctx, '❌ Failed to verify permissions.', { reply_to_message_id: ctx.message.message_id });
       return { valid: false };
     }
     VERBOSE && console.log(`[VERBOSE] ${cmdName} passed all checks`);
@@ -395,13 +406,13 @@ export function registerStartStopCommands(bot, options) {
     const chatType = ctx.chat?.type;
     if (chatType === 'private') return true;
     if (!isGroupChat(ctx)) {
-      await ctx.reply('❌ The /stop command only works in group chats or private chats with the bot.', { reply_to_message_id: message.message_id });
+      await safeReply(ctx, '❌ The /stop command only works in group chats or private chats with the bot.', { reply_to_message_id: message.message_id });
       return false;
     }
     if (!isChatAuthorized(chatId)) {
       if (!isTopicAuthorized || !isTopicAuthorized(ctx)) {
         const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${chatId}) is not authorized to use this bot.`;
-        await ctx.reply(errMsg, { reply_to_message_id: message.message_id });
+        await safeReply(ctx, errMsg, { reply_to_message_id: message.message_id });
         return false;
       }
     }
@@ -415,12 +426,12 @@ export function registerStartStopCommands(bot, options) {
       const member = await ctx.telegram.getChatMember(chatId, ctx.from.id);
       if (!member || member.status !== 'creator') {
         VERBOSE && console.log(`[VERBOSE] /stop <${label}> ignored: user is not chat owner or task requester`);
-        await ctx.reply(`❌ /stop <${label}> is only available to the chat owner or the user who started this task.`, { reply_to_message_id: message.message_id });
+        await safeReply(ctx, `❌ /stop <${label}> is only available to the chat owner or the user who started this task.`, { reply_to_message_id: message.message_id });
         return false;
       }
     } catch (error) {
       console.error(`[ERROR] /stop <${label}>: getChatMember failed:`, error);
-      await ctx.reply('❌ Failed to verify permissions for /stop.', { reply_to_message_id: message.message_id });
+      await safeReply(ctx, '❌ Failed to verify permissions for /stop.', { reply_to_message_id: message.message_id });
       return false;
     }
     return true;
@@ -438,7 +449,7 @@ export function registerStartStopCommands(bot, options) {
    */
   async function runStopIsolatedSessionFlow(ctx, sessionId) {
     const message = ctx.message;
-    const ack = await ctx.reply(`⏹️ Asking session \`${sessionId}\` to stop (sending CTRL+C via \`$ --stop\`)…`, {
+    const ack = await safeReply(ctx, `⏹️ Asking session \`${sessionId}\` to stop (sending CTRL+C via \`$ --stop\`)…`, {
       parse_mode: 'Markdown',
       reply_to_message_id: message.message_id,
     });
@@ -481,10 +492,10 @@ export function registerStartStopCommands(bot, options) {
     }
 
     try {
-      await ctx.telegram.editMessageText(ack.chat.id, ack.message_id, undefined, lines.join('\n'), { parse_mode: 'Markdown' });
+      await safeEditMessageText(ctx.telegram, ack.chat.id, ack.message_id, undefined, lines.join('\n'), { verbose: VERBOSE });
     } catch (error) {
       console.error('[ERROR] /stop: editMessageText failed, falling back to reply:', error);
-      await ctx.reply(lines.join('\n'), { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      await safeReply(ctx, lines.join('\n'), { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
     }
   }
 
@@ -621,13 +632,13 @@ export function registerStartStopCommands(bot, options) {
         // running-but-non-stoppable (non-isolation) session, say so; otherwise
         // fall back to the UUID hint.
         if (runningSession) {
-          await ctx.reply(`⚠️ Found a running task for ${url}, but it was not started with an isolation backend, so \`/stop\` cannot forward CTRL+C to it.\n\nNext time run it with the default isolation backend or pass \`--isolation docker\` to make this task interruptible via \`/stop\`.`, {
+          await safeReply(ctx, `⚠️ Found a running task for ${url}, but it was not started with an isolation backend, so \`/stop\` cannot forward CTRL+C to it.\n\nNext time run it with the default isolation backend or pass \`--isolation docker\` to make this task interruptible via \`/stop\`.`, {
             parse_mode: 'Markdown',
             reply_to_message_id: message.message_id,
           });
           return;
         }
-        await ctx.reply(`ℹ️ Cannot look up tasks by URL right now (the bot has no solve queue available in this context).\n\nIf you have the session UUID, you can use \`/stop <UUID>\` instead.`, {
+        await safeReply(ctx, `ℹ️ Cannot look up tasks by URL right now (the bot has no solve queue available in this context).\n\nIf you have the session UUID, you can use \`/stop <UUID>\` instead.`, {
           parse_mode: 'Markdown',
           reply_to_message_id: message.message_id,
         });
@@ -639,13 +650,13 @@ export function registerStartStopCommands(bot, options) {
         // have forwarded CTRL+C above). If it tracked a non-isolation session,
         // explain why it can't be stopped; otherwise report not found.
         if (runningSession) {
-          await ctx.reply(`⚠️ Found a running task for ${url}, but it was not started with an isolation backend, so \`/stop\` cannot forward CTRL+C to it.\n\nNext time run it with the default isolation backend or pass \`--isolation docker\` to make this task interruptible via \`/stop\`.`, {
+          await safeReply(ctx, `⚠️ Found a running task for ${url}, but it was not started with an isolation backend, so \`/stop\` cannot forward CTRL+C to it.\n\nNext time run it with the default isolation backend or pass \`--isolation docker\` to make this task interruptible via \`/stop\`.`, {
             parse_mode: 'Markdown',
             reply_to_message_id: message.message_id,
           });
           return;
         }
-        await ctx.reply(`ℹ️ No queued or running task found for ${url}.\n\nIf the task is running with an isolation backend, try \`/stop <UUID>\` (the UUID is shown in the bot's session-id message).`, {
+        await safeReply(ctx, `ℹ️ No queued or running task found for ${url}.\n\nIf the task is running with an isolation backend, try \`/stop <UUID>\` (the UUID is shown in the bot's session-id message).`, {
           parse_mode: 'Markdown',
           reply_to_message_id: message.message_id,
         });
@@ -661,9 +672,9 @@ export function registerStartStopCommands(bot, options) {
         // coordinates on the item itself when the card was first posted —
         // see telegram-bot.mjs where `item.messageInfo` is wired up.
         const stopperName = ctx.from?.username ? `@${ctx.from.username}` : ctx.from?.first_name || `user ${ctx.from?.id}`;
-        await updateQueueCardForCancellation(lookup.item, url, lookup.tool, stopperName);
+        await updateQueueCardForCancellation(lookup.item, url, lookup.tool, stopperName, { safeEditMessageText, verbose: VERBOSE });
 
-        await ctx.reply(`🗑 Removed queued task for ${url}${toolLabel}.`, {
+        await safeReply(ctx, `🗑 Removed queued task for ${url}${toolLabel}.`, {
           parse_mode: 'Markdown',
           reply_to_message_id: message.message_id,
         });
@@ -679,7 +690,7 @@ export function registerStartStopCommands(bot, options) {
       // running-not-isolated: a started, non-isolated screen session. We
       // could shell out to `screen -X -S <name> stuff $'\003'`, but that's
       // brittle and out of scope for #1780. Tell the user how to recover.
-      await ctx.reply(`⚠️ Found a running task for ${url}, but it was not started with an isolation backend, so \`/stop\` cannot forward CTRL+C to it.\n\nNext time run it with the default isolation backend or pass \`--isolation docker\` to make this task interruptible via \`/stop\`.`, {
+      await safeReply(ctx, `⚠️ Found a running task for ${url}, but it was not started with an isolation backend, so \`/stop\` cannot forward CTRL+C to it.\n\nNext time run it with the default isolation backend or pass \`--isolation docker\` to make this task interruptible via \`/stop\`.`, {
         parse_mode: 'Markdown',
         reply_to_message_id: message.message_id,
       });
@@ -707,7 +718,7 @@ export function registerStartStopCommands(bot, options) {
         alreadyStoppedMsg += `\nReason: ${stopInfo.reason}`;
       }
       alreadyStoppedMsg += '\n\nUse /start to resume accepting tasks.';
-      await ctx.reply(alreadyStoppedMsg, {
+      await safeReply(ctx, alreadyStoppedMsg, {
         reply_to_message_id: ctx.message.message_id,
       });
       return;
@@ -739,7 +750,7 @@ export function registerStartStopCommands(bot, options) {
     }
     stopMessage += '*Disabled commands:*\n' + '• /solve - No new issues will be accepted\n' + '• /hive - No new hive commands will be accepted\n' + '• /merge - No new merge operations will be accepted\n\n' + '*Still available:*\n' + '• /help - Show help\n' + '• /limits - Show usage limits\n' + '• /version - Show version info\n' + '• /start - Resume accepting tasks (owner only)\n\n' + '💡 Any tasks already in queue will continue to process.';
 
-    await ctx.reply(stopMessage, {
+    await safeReply(ctx, stopMessage, {
       parse_mode: 'Markdown',
       reply_to_message_id: ctx.message.message_id,
     });
@@ -755,7 +766,7 @@ export function registerStartStopCommands(bot, options) {
       // In private chats, show a welcome message instead
       if (check.isPrivate) {
         VERBOSE && console.log('[VERBOSE] /start in private chat: showing welcome');
-        await ctx.reply('👋 *Welcome to SwarmMindBot!*\n\n' + 'This bot helps solve GitHub issues using AI.\n\n' + 'To use this bot:\n' + '1. Add me to a group chat\n' + '2. Make me an admin\n' + '3. Use /solve to solve GitHub issues\n\n' + 'Use /help in a group chat for more information.', { parse_mode: 'Markdown' });
+        await safeReply(ctx, '👋 *Welcome to SwarmMindBot!*\n\n' + 'This bot helps solve GitHub issues using AI.\n\n' + 'To use this bot:\n' + '1. Add me to a group chat\n' + '2. Make me an admin\n' + '3. Use /solve to solve GitHub issues\n\n' + 'Use /help in a group chat for more information.', { parse_mode: 'Markdown' });
       }
       return;
     }
@@ -763,7 +774,7 @@ export function registerStartStopCommands(bot, options) {
 
     // Check if already running (not stopped)
     if (!isChatStopped(chatId)) {
-      await ctx.reply('ℹ️ Bot is already accepting tasks in this chat.\n\nUse /help to see available commands.', {
+      await safeReply(ctx, 'ℹ️ Bot is already accepting tasks in this chat.\n\nUse /help to see available commands.', {
         reply_to_message_id: ctx.message.message_id,
       });
       return;
@@ -791,7 +802,7 @@ export function registerStartStopCommands(bot, options) {
       }
     }
 
-    await ctx.reply('✅ *Bot Started*\n\n' + 'This bot is now accepting tasks in this chat.\n\n' + (durationStr ? `Bot was stopped for ${durationStr}.\n\n` : '') + 'Use /help to see available commands.', {
+    await safeReply(ctx, '✅ *Bot Started*\n\n' + 'This bot is now accepting tasks in this chat.\n\n' + (durationStr ? `Bot was stopped for ${durationStr}.\n\n` : '') + 'Use /help to see available commands.', {
       parse_mode: 'Markdown',
       reply_to_message_id: ctx.message.message_id,
     });

package/src/telegram-subscribers.lib.mjs

@@ -14,6 +14,8 @@
  * @see https://github.com/link-assistant/hive-mind/issues/1688
  */
 
+import { safeReply } from './telegram-safe-reply.lib.mjs';
+
 // Map<userId, { username, firstName, subscribedAt, sourceChatId }>
 const subscribers = new Map();
 
@@ -196,9 +198,9 @@ export function registerSubscribeCommands(bot, options = {}) {
       message = 'ℹ️ You are already subscribed.\n\nUse /unsubscribe to stop receiving private notifications when /solve commands finish.';
     }
 
-    await ctx.reply(message, {
-      parse_mode: 'Markdown',
+    await safeReply(ctx, message, {
       reply_to_message_id: ctx.message?.message_id,
+      verbose: VERBOSE,
     });
 
     VERBOSE && console.log(`[VERBOSE] Subscriber ${userId} (${ctx.from.username || ctx.from.first_name || 'unknown'}) added (new=${wasNew}); total=${getSubscriberCount()}`);
@@ -210,9 +212,9 @@ export function registerSubscribeCommands(bot, options = {}) {
     const userId = ctx.from.id;
     const wasRemoved = removeSubscriber(userId);
 
-    await ctx.reply(wasRemoved ? UNSUBSCRIBE_CONFIRMATION : NOT_SUBSCRIBED_MESSAGE, {
-      parse_mode: 'Markdown',
+    await safeReply(ctx, wasRemoved ? UNSUBSCRIBE_CONFIRMATION : NOT_SUBSCRIBED_MESSAGE, {
       reply_to_message_id: ctx.message?.message_id,
+      verbose: VERBOSE,
     });
 
     VERBOSE && console.log(`[VERBOSE] Subscriber ${userId} (${ctx.from.username || ctx.from.first_name || 'unknown'}) removed=${wasRemoved}; total=${getSubscriberCount()}`);

package/src/telegram-terminal-watch-command.lib.mjs

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import { extractSessionIdFromText, decideLogDestination, resolveLogPath } from './telegram-log-command.lib.mjs';
 import { parseSessionExitFooter } from './isolation-runner.lib.mjs';
+import { safeReply, safeSendMessage, safeEditMessageText } from './telegram-safe-reply.lib.mjs';
 import { classifyExitStatus, isFailureSessionStatus } from './session-status.lib.mjs';
 
 const DEFAULT_WIDTH = 120;
@@ -248,7 +249,7 @@ export function watchTerminalLogSession({ bot, chatId, messageId, sessionId, log
       const message = formatTerminalWatchMessage({ sessionId, statusResult, logText, options, updateCount, completed, repoDescription });
       const shouldEdit = !lastMessage || snapshotChanged || (completed && message !== lastMessage);
       if (shouldEdit && message !== lastMessage) {
-        await bot.telegram.editMessageText(chatId, messageId, undefined, message, { parse_mode: 'Markdown' });
+        await safeEditMessageText(bot.telegram, chatId, messageId, undefined, message, { verbose });
         lastMessage = message;
       }
       lastSnapshot = snapshot;
@@ -281,9 +282,9 @@ function buildUsage() {
 
 async function createWatchMessage({ ctx, targetChatId, replyToMessageId, text }) {
   if (targetChatId === ctx.chat.id) {
-    return await ctx.reply(text, { parse_mode: 'Markdown', reply_to_message_id: replyToMessageId });
+    return await safeReply(ctx, text, { reply_to_message_id: replyToMessageId });
   }
-  return await ctx.telegram.sendMessage(targetChatId, text, replyToMessageId ? { parse_mode: 'Markdown', reply_to_message_id: replyToMessageId } : { parse_mode: 'Markdown' });
+  return await safeSendMessage(ctx.telegram, targetChatId, text, replyToMessageId ? { reply_to_message_id: replyToMessageId } : {});
 }
 
 async function forwardOrCopyToDm(ctx, sourceMessage) {
@@ -324,7 +325,7 @@ async function startWatchFromResolvedSession({ bot, ctx, sessionId, statusResult
   watchTerminalLogSession({ bot, chatId: targetChatId, messageId: watchMessage.message_id, sessionId, logPath, querySessionStatus, isTerminalSessionStatus, options: watchOptions, repoDescription, verbose, initialStatusResult: statusResult, initialLogText, initialMessage: initialText });
 
   if (!auto && decision.destination === 'dm' && ctx.chat.type !== 'private') {
-    await ctx.reply(`📬 Started terminal watch for \`${sessionId}\` in your direct messages.`, { parse_mode: 'Markdown', reply_to_message_id: ctx.message.message_id });
+    await safeReply(ctx, `📬 Started terminal watch for \`${sessionId}\` in your direct messages.`, { reply_to_message_id: ctx.message.message_id, verbose });
   }
   return { started: true, messageId: watchMessage.message_id, sessionInfo };
 }
@@ -371,13 +372,13 @@ export async function registerTerminalWatchCommand(bot, options) {
 
     const parsedArgs = parseTerminalWatchArgs(message.text || '');
     if (parsedArgs.errors.length > 0) {
-      await ctx.reply(`❌ Invalid /terminal_watch options:\n${parsedArgs.errors.map(e => `• ${e}`).join('\n')}\n\n${buildUsage()}`, { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      await safeReply(ctx, `❌ Invalid /terminal_watch options:\n${parsedArgs.errors.map(e => `• ${e}`).join('\n')}\n\n${buildUsage()}`, { reply_to_message_id: message.message_id, verbose: VERBOSE });
       return;
     }
 
     const sessionId = parsedArgs.sessionId || extractSessionIdFromText(message.reply_to_message?.text || message.reply_to_message?.caption || '');
     if (!sessionId) {
-      await ctx.reply(`❌ /terminal_watch requires a session id.\n\n${buildUsage()}`, { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      await safeReply(ctx, `❌ /terminal_watch requires a session id.\n\n${buildUsage()}`, { reply_to_message_id: message.message_id, verbose: VERBOSE });
       return;
     }
 
@@ -417,7 +418,7 @@ export async function registerTerminalWatchCommand(bot, options) {
     }
 
     if (!statusResult?.exists) {
-      await ctx.reply(`❌ Session \`${sessionId}\` is not known to start-command.`, { parse_mode: 'Markdown', reply_to_message_id: message.message_id });
+      await safeReply(ctx, `❌ Session \`${sessionId}\` is not known to start-command.`, { reply_to_message_id: message.message_id, verbose: VERBOSE });
       return;
     }
 

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

@@ -24,6 +24,7 @@
 
 import { getAllKnownLocalTokens } from './token-sanitization.lib.mjs';
 import { maskToken } from './lib.mjs';
+import { safeReply } from './telegram-safe-reply.lib.mjs';
 
 /**
  * Resolve allowed chat IDs into an array of numeric IDs the user could own.
@@ -146,7 +147,7 @@ export const registerTokensCommand = (bot, options = {}) => {
     }
 
     const message = formatTokenList(tokens);
-    await ctx.reply(message, { parse_mode: 'Markdown' });
+    await safeReply(ctx, message);
   });
 };
 

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

@@ -16,6 +16,7 @@
 
 import { promisify } from 'util';
 import { exec as execCallback } from 'child_process';
+import { safeReply, safeEditMessageText } from './telegram-safe-reply.lib.mjs';
 
 const exec = promisify(execCallback);
 
@@ -128,9 +129,9 @@ export function registerTopCommand(bot, options) {
     }
 
     // Show experimental feature warning
-    await ctx.reply('🧪 *EXPERIMENTAL FEATURE*\n\nThis command is experimental and may have issues. Use with caution.', {
-      parse_mode: 'Markdown',
+    await safeReply(ctx, '🧪 *EXPERIMENTAL FEATURE*\n\nThis command is experimental and may have issues. Use with caution.', {
       reply_to_message_id: ctx.message.message_id,
+      verbose: VERBOSE,
     });
 
     // Check if there's already an active top session for this chat
@@ -188,11 +189,11 @@ export function registerTopCommand(bot, options) {
     const firstOutput = await captureTopOutput(chatId);
     if (firstOutput) {
       try {
-        await ctx.telegram.editMessageText(chatId, initialMessage.message_id, undefined, `\`\`\`\n${firstOutput}\n\`\`\``, {
-          parse_mode: 'Markdown',
+        await safeEditMessageText(ctx.telegram, chatId, initialMessage.message_id, undefined, `\`\`\`\n${firstOutput}\n\`\`\``, {
           reply_markup: {
             inline_keyboard: [[{ text: '🛑 Stop', callback_data: `stop_top_${chatId}` }]],
           },
+          verbose: VERBOSE,
         });
       } catch (error) {
         console.error('[ERROR] Failed to update message:', error);
@@ -204,11 +205,11 @@ export function registerTopCommand(bot, options) {
       const output = await captureTopOutput(chatId);
       if (output) {
         try {
-          await ctx.telegram.editMessageText(chatId, initialMessage.message_id, undefined, `\`\`\`\n${output}\n\`\`\``, {
-            parse_mode: 'Markdown',
+          await safeEditMessageText(ctx.telegram, chatId, initialMessage.message_id, undefined, `\`\`\`\n${output}\n\`\`\``, {
             reply_markup: {
               inline_keyboard: [[{ text: '🛑 Stop', callback_data: `stop_top_${chatId}` }]],
             },
+            verbose: VERBOSE,
           });
         } catch (error) {
           // Ignore "message is not modified" errors
@@ -290,9 +291,7 @@ export function registerTopCommand(bot, options) {
 
     // Update the message to show it's stopped
     try {
-      await ctx.editMessageText('🛑 Top session stopped.', {
-        parse_mode: 'Markdown',
-      });
+      await safeEditMessageText(ctx.telegram, chatId, ctx.callbackQuery?.message?.message_id, undefined, '🛑 Top session stopped.', { verbose: VERBOSE });
     } catch (error) {
       console.error('[ERROR] Failed to edit message:', error);
     }

package/src/tool-retry.lib.mjs

@@ -24,6 +24,22 @@ const normalizeModelKey = value => {
     .trim();
 };
 
+// Issue #2169: HTTP status codes are only meaningful as errors when they appear in an
+// HTTP-status context. A bare number in prose ("PR #524", "issue #523", "line 502") is
+// not an error — matching it wrongly sent an entire successful session into a multi-hour
+// retry loop (see docs/case-studies/issue-2169). `matchesHttpStatus` accepts:
+//   "API Error: 502", "error code: 522", "status 504", "HTTP/1.1 520", "code=524"
+//   "502 Bad Gateway", "524 A Timeout Occurred" (status followed by its canonical phrase)
+const GATEWAY_STATUS_PHRASES = ['bad gateway', 'gateway timeout', 'gateway time-out', 'unknown error', 'web server is down', 'connection timed out', 'origin is unreachable', 'a timeout occurred'];
+const HTTP_STATUS_PREFIX = String.raw`(?:http(?:s|/\d(?:\.\d)?)?\s*)?(?:api\s+)?(?:error|status(?:\s*code)?|code|response|returned|got)\s*(?:code\s*)?[:=#]?\s*`;
+export const matchesHttpStatus = (lowerText, codePattern, phrases = []) => {
+  if (!lowerText) return false;
+  if (new RegExp(`${HTTP_STATUS_PREFIX}(?:${codePattern})\\b`).test(lowerText)) return true;
+  if (new RegExp(`\\bhttp\\s*(?:status\\s*)?(?:${codePattern})\\b`).test(lowerText)) return true;
+  if (phrases.length > 0 && new RegExp(`\\b(?:${codePattern})\\b[\\s,:;-]*(?:${phrases.join('|')})`).test(lowerText)) return true;
+  return false;
+};
+
 export const classifyRetryableError = value => {
   const message = normalizeMessage(value);
   const lower = message.toLowerCase();
@@ -163,7 +179,12 @@ export const classifyRetryableError = value => {
   // These come from an intermediary (CDN/proxy/load balancer), not from a request the
   // client got wrong, and clear on their own — OpenAI/Anthropic/GitHub all front their
   // APIs with such proxies. Safe to retry the same request after a backoff.
-  if (lower.includes('502 bad gateway') || lower.includes('bad gateway') || lower.includes('504 gateway timeout') || lower.includes('gateway time-out') || lower.includes('gateway timeout') || lower.includes('api error: 502') || lower.includes('api error: 504') || /\b52[0-4]\b/.test(lower)) {
+  // Issue #2169: the bare `/\b52[0-4]\b/` test used here before matched ANY standalone
+  // 520-524 in the text, so an agent's own success summary — "PR #524", "issue #523",
+  // "(`463c5ca`, PR #522)" — was classified as a gateway error and retried for hours.
+  // The number now has to appear in an HTTP-status context ("error code: 522",
+  // "API Error: 502", "HTTP 504") or next to the status' canonical phrase.
+  if (lower.includes('502 bad gateway') || lower.includes('bad gateway') || lower.includes('504 gateway timeout') || lower.includes('gateway time-out') || lower.includes('gateway timeout') || matchesHttpStatus(lower, '502|504|52[0-4]', GATEWAY_STATUS_PHRASES)) {
     return { message, isRetryable: true, isCapacity: false, label: 'Gateway error (502/504/52x)' };
   }
 
@@ -201,7 +222,9 @@ export const classifyRetryableError = value => {
   // Issue #1955: broadened to also catch the bare "503 Service Unavailable" that
   // GitHub/OpenAI/Anthropic return when a backend is briefly saturated — a
   // transient, self-clearing condition, safe to retry with the same request.
-  if (lower.includes('api error: 503') || lower.includes('503 service unavailable') || lower.includes('service unavailable') || (lower.includes('503') && (lower.includes('upstream connect error') || lower.includes('remote connection failure')))) {
+  // Issue #2169: `matchesHttpStatus` accepts the status only next to an error-ish prefix
+  // ("api error: 503", "status code: 503"), never a bare number in prose.
+  if (lower.includes('api error: 503') || lower.includes('503 service unavailable') || lower.includes('service unavailable') || matchesHttpStatus(lower, '503') || (lower.includes('503') && (lower.includes('upstream connect error') || lower.includes('remote connection failure')))) {
     return { message, isRetryable: true, isCapacity: false, label: '503 network error' };
   }
 
@@ -212,8 +235,92 @@ export const classifyRetryableError = value => {
   return { message, isRetryable: false, isCapacity: false, label: null };
 };
 
-export const getRetryDelayMs = ({ retryCount, initialDelayMs = retryLimits.initialTransientErrorDelayMs, maxDelayMs = retryLimits.maxTransientErrorDelayMs } = {}) => {
-  return Math.min(initialDelayMs * Math.pow(retryLimits.retryBackoffMultiplier, retryCount), maxDelayMs);
+// Issue #2169: `minDelayMs` is the floor for the transient-API-error paths ("with minimum of
+// 3 minutes"). It defaults to 0 so the deliberately fast paths — capacity retries (15s), a
+// model switch (5s), stream startup/activity timeouts (30s) — keep their short delays.
+export const getRetryDelayMs = ({ retryCount, initialDelayMs = retryLimits.initialTransientErrorDelayMs, maxDelayMs = retryLimits.maxTransientErrorDelayMs, minDelayMs = 0 } = {}) => {
+  const backoff = Math.min(initialDelayMs * Math.pow(retryLimits.retryBackoffMultiplier, retryCount), maxDelayMs);
+  return Math.max(backoff, Math.min(minDelayMs, maxDelayMs));
+};
+
+// Issue #2169: diagnosing a *mis*classification from the log used to be impossible — the retry
+// line printed only the first 200 characters of the message, while the token that actually made
+// the classifier fire ("PR #524", 1.6 KB later) was never shown. This renders the evidence for a
+// classification: how long the message was and the ±40-character context around every HTTP-status
+// -looking token in it, so the next false positive is diagnosable from a single verbose log line.
+export const describeClassificationEvidence = (message, label = null, { maxMatches = 3, contextChars = 40 } = {}) => {
+  const text = String(message ?? '');
+  const parts = [`label=${JSON.stringify(label)}`, `messageChars=${text.length}`];
+  const matches = [];
+  for (const match of text.matchAll(/\b(?:4\d{2}|5\d{2})\b/g)) {
+    const start = Math.max(0, match.index - contextChars);
+    const end = Math.min(text.length, match.index + match[0].length + contextChars);
+    matches.push(`@${match.index} ${JSON.stringify(text.slice(start, end).replace(/\s+/g, ' '))}`);
+    if (matches.length >= maxMatches) break;
+  }
+  parts.push(matches.length > 0 ? `statusTokens=[${matches.join(', ')}]` : 'statusTokens=[]');
+  return parts.join(' ');
+};
+
+// Issue #2169: human-readable duration for retry logs — "45s", "12 min", "3h 15m", "12h".
+export const formatRetryDuration = ms => {
+  if (!Number.isFinite(ms)) return 'unlimited';
+  if (ms < 60000) return `${Math.max(0, Math.round(ms / 1000))}s`;
+  const totalMinutes = Math.round(ms / 60000);
+  if (totalMinutes < 60) return `${totalMinutes} min`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+};
+
+// Issue #2169: a provider outage can last many hours. The retry loops used to stop after a
+// fixed number of attempts (10), which — with the old 2 min → 30 min backoff — gave up after
+// ~3.5 hours. The budget below turns "how long do we keep trying" into the primary knob: retries
+// continue while the *next* backoff still fits inside `budgetMs` (default 12 h), measured from
+// the first retry of the run. The per-tool retry counts stay as runaway-loop backstops.
+//
+// Usage inside a tool's retry loop (the budget object lives outside `executeWithRetry` so it
+// survives the recursive calls):
+//   const budget = createTransientRetryBudget();
+//   const decision = budget.evaluate({ retryCount, maxRetries, initialDelayMs, maxDelayMs, minDelayMs });
+//   if (decision.allowed) { budget.grant(); ...wait decision.delayMs... } else { fail(decision) }
+export const createTransientRetryBudget = ({ budgetMs = retryLimits.transientErrorRetryBudgetMs, now = () => Date.now() } = {}) => {
+  let startedAt = null;
+  let retriesGranted = 0;
+  const elapsedMs = () => (startedAt === null ? 0 : Math.max(0, now() - startedAt));
+  const remainingMs = () => (budgetMs > 0 ? Math.max(0, budgetMs - elapsedMs()) : Infinity);
+  return {
+    budgetMs,
+    elapsedMs,
+    remainingMs,
+    get retriesGranted() {
+      return retriesGranted;
+    },
+    // Starts the clock on the first granted retry and counts it.
+    grant() {
+      if (startedAt === null) startedAt = now();
+      retriesGranted += 1;
+    },
+    evaluate({ retryCount = 0, maxRetries = retryLimits.maxTransientErrorRetries, initialDelayMs, maxDelayMs, minDelayMs = 0 } = {}) {
+      const delayMs = getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs, minDelayMs });
+      const base = { delayMs, elapsedMs: elapsedMs(), remainingMs: remainingMs(), budgetMs, retryCount, maxRetries };
+      if (retryCount >= maxRetries) return { ...base, allowed: false, reason: 'count' };
+      // Never start a wait that would run past the budget window.
+      if (budgetMs > 0 && delayMs > remainingMs()) return { ...base, allowed: false, reason: 'budget' };
+      return { ...base, allowed: true, reason: null };
+    },
+    // One-line explanation for the "giving up" log, e.g.
+    // "retry budget of 12h exhausted after 26 retries over 11h 45m".
+    describeExhaustion(decision) {
+      const spent = formatRetryDuration(decision?.elapsedMs ?? elapsedMs());
+      if (decision?.reason === 'count') return `retry limit of ${decision.maxRetries} attempts reached after ${spent} (budget ${formatRetryDuration(budgetMs)})`;
+      return `retry budget of ${formatRetryDuration(budgetMs)} exhausted after ${decision?.retryCount ?? retriesGranted} retries over ${spent}`;
+    },
+    // Progress suffix for each retry log line, e.g. "budget 25 min/12h used".
+    describeProgress() {
+      return budgetMs > 0 ? `budget ${formatRetryDuration(elapsedMs())}/${formatRetryDuration(budgetMs)} used` : 'budget disabled';
+    },
+  };
 };
 
 export const waitWithCountdown = async (delayMs, log) => {
@@ -352,7 +459,7 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
 // survives the recursive executeWithRetry calls without each tool tracking extra
 // state. It resets to 0 whenever we actually switch models, so every model in the
 // fallback chain gets its own batch of same-model retries before stepping down.
-export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, retryCount, initialDelayMs, maxDelayMs } = {}) => {
+export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, retryCount, initialDelayMs, maxDelayMs, minDelayMs = 0 } = {}) => {
   const classification = classifyRetryableError(errorMessage);
   const isCapacity = classification.isCapacity === true && !!argv?.model;
   const capacityRetryCount = argv?._capacityRetryCount || 0;
@@ -373,13 +480,17 @@ export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, re
   const switchResult = await maybeSwitchToFallbackModel({ tool, argv, log, errorMessage });
   // A model switch starts a fresh batch of same-model retries for the new model.
   if (switchResult?.switched && argv) argv._capacityRetryCount = 0;
-  const delay = switchResult?.switched ? retryLimits.modelSwitchRetryDelayMs : getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs });
+  const delay = switchResult?.switched ? retryLimits.modelSwitchRetryDelayMs : getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs, minDelayMs });
   return { delay, switched: switchResult?.switched === true };
 };
 
 export default {
   classifyRetryableError,
+  matchesHttpStatus,
   getRetryDelayMs,
+  describeClassificationEvidence,
+  formatRetryDuration,
+  createTransientRetryBudget,
   waitWithCountdown,
   resolveConfiguredFallbackModel,
   maybeSwitchToFallbackModel,