@link-assistant/hive-mind 1.68.0 → 1.69.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 1.69.0
+
+### Minor Changes
+
+- 8939a2a: Add experimental `--show-limits` virtual option to hive-telegram-bot's `/solve` and `/hive` commands. When set, the bot embeds a Claude (or Codex) usage snapshot in the executing message and a delta block (start → end, with a parallel-sessions disclaimer) in the completion message. Limits are fetched via the existing 20-minute cached helpers so the upstream usage API isn't rate-limited. The flag is stripped before the args reach `/solve` or `/hive`, and bot administrators can disable it with `TELEGRAM_SHOW_LIMITS=false`. Refs: #594.
+
 ## 1.68.0
 
 ### Minor Changes

package/package.json

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

package/src/session-monitor.lib.mjs

@@ -281,6 +281,36 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
           }
         }
 
+        // Issue #594: when --show-limits was used at command time, capture an
+        //   end-of-task limits snapshot and append a delta block to the
+        //   completion message. The cached helpers respect a 20-min TTL so
+        //   parallel sessions don't stampede the upstream API.
+        const limitsExtraSections = [];
+        if (sessionInfo?.showLimits) {
+          try {
+            const showLimitsLib = await import('./telegram-show-limits.lib.mjs');
+            const limitsLib = await import('./limits.lib.mjs');
+            const endSnapshot = await showLimitsLib.captureLimitsSnapshot({
+              tool: sessionInfo.tool || 'claude',
+              verbose,
+              limitsLib,
+            });
+            sessionInfo.limitsAtEnd = endSnapshot;
+            const deltaBlock = showLimitsLib.formatLimitsDeltaBlock(sessionInfo.limitsAtStart || null, endSnapshot);
+            if (deltaBlock) limitsExtraSections.push(deltaBlock);
+            else {
+              // Either start snapshot was missing or tool changed — fall back
+              // to a plain end-of-task snapshot so the user still sees current state.
+              const endBlock = showLimitsLib.formatLimitsSnapshotBlock(endSnapshot, { title: '📊 Limits at end' });
+              if (endBlock) limitsExtraSections.push(endBlock);
+            }
+          } catch (limitsError) {
+            if (verbose) {
+              console.log(`[VERBOSE] Could not capture end-of-task limits for ${sessionName}: ${limitsError?.message || limitsError}`);
+            }
+          }
+        }
+
         const message = formatSessionCompletionMessage({
           sessionName,
           sessionInfo,
@@ -289,6 +319,7 @@ export async function monitorSessions(bot, verbose = false, options = {}) {
           exitCode: finalExitCode,
           infoBlock: sessionInfo?.infoBlock || '',
           pullRequestUrl,
+          extraSections: limitsExtraSections,
         });
 
         // Update the original reply message if messageId is available, otherwise send new message

package/src/telegram-bot.mjs

@@ -30,12 +30,14 @@ const { parseGitHubUrl, validateGitHubEntityExistence } = await import('./github
 const { validateModelName, buildModelOptionDescription } = await import('./models/index.mjs');
 const { validateBranchInArgs } = await import('./solve.branch.lib.mjs');
 const { extractIsolationFromArgs, isValidPerCommandIsolation, resolveIsolation, createIsolationAwareQueueCallback } = await import('./telegram-isolation.lib.mjs');
-const { formatUsageMessage, formatCodexLimitsSection, getAllCachedLimits } = await import('./limits.lib.mjs');
+const limitsLib = await import('./limits.lib.mjs');
+const { formatUsageMessage, formatCodexLimitsSection, getAllCachedLimits } = limitsLib;
+const { handleShowLimitsFlag, captureStartSnapshotAndAppend } = await import('./telegram-show-limits.lib.mjs'); // #594
 const { getVersionInfo, formatVersionMessage } = await import('./version-info.lib.mjs');
 const { escapeMarkdown, escapeMarkdownV2, cleanNonPrintableChars, makeSpecialCharsVisible } = await import('./telegram-markdown.lib.mjs');
 const { getSolveQueue, createQueueExecuteCallback } = await import('./telegram-solve-queue.lib.mjs');
 const { applySolveToolAlias, getFirstParsedPositionalArg, getSolveCommandNameFromText, getSolveToolAliasFromText, moveArgumentToFront, parseArgsWithYargs, parseCommandArgs, SOLVE_COMMAND_NAMES } = await import('./telegram-solve-command.lib.mjs');
-const { executeStartScreen: executeStartScreenCommand } = await import('./telegram-command-execution.lib.mjs');
+const { executeStartScreen: executeStartScreenCommand, buildExecuteAndUpdateMessage } = await import('./telegram-command-execution.lib.mjs');
 const { isChatStopped, getChatStopInfo, getStoppedChatRejectMessage, DEFAULT_STOP_REASON } = await import('./telegram-start-stop-command.lib.mjs');
 const { isOldMessage: _isOldMessage, isGroupChat: _isGroupChat, isChatAuthorized: _isChatAuthorized, isForwardedOrReply: _isForwardedOrReply, extractCommandFromText, extractGitHubUrl: _extractGitHubUrl } = await import('./telegram-message-filters.lib.mjs');
 const { safeReply } = await import('./telegram-safe-reply.lib.mjs');
@@ -110,6 +112,8 @@ const config = yargs(hideBin(process.argv))
     default: getenv('TELEGRAM_BOT_VERBOSE', 'false') === 'true',
   })
   .option('autoStartScreenWatchMessage', { type: 'boolean', description: 'Experimental: auto-start separate /terminal_watch messages for public /solve sessions', alias: 'auto-start-screen-watch-message', default: getenv('TELEGRAM_AUTO_START_SCREEN_WATCH_MESSAGE', getenv('TELEGRAM_AUTO_WATCH_MESSAGE', 'false')) === 'true' })
+  // Issue #594: bot-owner toggle for --show-limits virtual option in /solve and /hive.
+  .option('showLimits', { type: 'boolean', description: 'Experimental: allow /solve and /hive callers to use --show-limits to embed Claude/Codex usage at start, end, and delta in the completion message', alias: 'show-limits', default: getenv('TELEGRAM_SHOW_LIMITS', 'true') !== 'false' })
   .option('isolation', { type: 'string', description: "Isolation backend (screen/tmux/docker). Defaults to 'screen' so Telegram-bot work sessions survive bot restarts; pass --isolation '' (or set TELEGRAM_ISOLATION='') to disable.", default: getenv('TELEGRAM_ISOLATION', 'screen') })
   .help('h')
   .alias('h', 'help')
@@ -128,6 +132,7 @@ if (config.configuration) {
 const BOT_TOKEN = config.token || getenv('TELEGRAM_BOT_TOKEN', '');
 const VERBOSE = config.verbose || getenv('TELEGRAM_BOT_VERBOSE', 'false') === 'true';
 const AUTO_WATCH_MESSAGE = config.autoStartScreenWatchMessage === true;
+const SHOW_LIMITS_ENABLED = config.showLimits === true;
 if (!BOT_TOKEN) {
   console.error('Error: TELEGRAM_BOT_TOKEN not set. Use --token or TELEGRAM_BOT_TOKEN env var.');
   process.exit(1);
@@ -460,48 +465,7 @@ async function validateGitHubUrl(args, options = {}) {
   return { valid: true, parsed, normalizedUrl: url };
 }
 
-async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude', urlContext = null) {
-  const { chat, message_id: msgId } = startingMessage;
-  const safeEdit = async text => {
-    try {
-      await ctx.telegram.editMessageText(chat.id, msgId, undefined, text, { parse_mode: 'Markdown' });
-    } catch (e) {
-      console.error(`[telegram-bot] Failed to update message for ${commandName}: ${e.message}`);
-    }
-  };
-  const requesterUserId = ctx.from?.id ?? null; // Issue #1688: suppress duplicate /subscribe DM
-  const iso = await resolveIsolation(perCommandIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE);
-  let result, session, sessionInfo;
-  if (iso) {
-    session = iso.runner.generateSessionId();
-    VERBOSE && console.log(`[VERBOSE] Using isolation (${iso.backend}), session: ${session}`);
-    result = await iso.runner.executeWithIsolation(commandName, args, { backend: iso.backend, sessionId: session, verbose: VERBOSE });
-    if (result.success) {
-      sessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, isolationBackend: iso.backend, sessionId: session, tool, infoBlock, urlContext, requesterUserId };
-      trackSession(session, sessionInfo, VERBOSE);
-    }
-  } else {
-    result = await executeStartScreen(commandName, args);
-    const match = result.success && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
-    session = match ? match[1] : 'unknown';
-    // Issue #1586: Non-isolation sessions auto-expire after 10 min — screen stays alive via `exec bash` so completion can't be detected reliably; this still blocks duplicate commands in the timeout window.
-    if (result.success && session !== 'unknown') {
-      sessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, tool, infoBlock, urlContext, requesterUserId };
-      trackSession(session, sessionInfo, VERBOSE);
-    }
-  }
-  if (result.warning) return safeEdit(`⚠️  ${result.warning}`);
-  if (result.success) {
-    await safeEdit(
-      formatExecutingWorkSessionMessage({
-        sessionName: session,
-        isolationBackend: iso?.backend || null,
-        infoBlock,
-      })
-    );
-    if (AUTO_WATCH_MESSAGE && commandName === 'solve' && sessionInfo?.isolationBackend) await startAutoTerminalWatchForSession({ bot, ctx, sessionId: session, sessionInfo, verbose: VERBOSE });
-  } else await safeEdit(`❌ Error executing ${commandName} command:\n\n\`\`\`\n${result.error || result.output}\n\`\`\`\n\n${infoBlock}`);
-}
+const executeAndUpdateMessage = buildExecuteAndUpdateMessage({ resolveIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE, executeStartScreen, trackSession, AUTO_WATCH_MESSAGE, startAutoTerminalWatchForSession, bot, formatExecutingWorkSessionMessage });
 
 bot.command('help', async ctx => {
   VERBOSE && console.log('[VERBOSE] /help command received');
@@ -603,6 +567,7 @@ bot.command('help', async ctx => {
   message += '• `--base-branch <branch>` or `-b` - Target branch for PR (default: repo default branch)\n';
   message += '• `--think <level>` - Thinking level (off/low/medium/high/xhigh/max) | `--thinking-budget <num>` - Token budget (0-63999)\n';
   message += '• `--verbose` or `-v` - Verbose output | `--attach-logs` - Attach logs to PR\n';
+  if (SHOW_LIMITS_ENABLED) message += '• `--show-limits` - Experimental: embed Claude/Codex usage at start, end and delta (#594)\n';
   message += '\n💡 *Tip:* Many more options available. See full documentation for complete list.\n';
 
   if (allowedChats || allowedTopics) {
@@ -788,6 +753,12 @@ async function handleSolveCommand(ctx) {
   const solveToolAlias = getSolveToolAliasFromText(ctx.message.text);
   let userArgs = parseCommandArgs(ctx.message.text);
 
+  // Issue #594: strip --show-limits from userArgs (hive-telegram-bot virtual option).
+  const solveSL = await handleShowLimitsFlag({ ctx, safeReply, args: userArgs, enabled: SHOW_LIMITS_ENABLED });
+  if (solveSL.handled) return;
+  const solveShowLimits = solveSL.showLimits;
+  userArgs = solveSL.args;
+
   // Check if this is a reply to a message and user didn't provide URL as first argument
   // In that case, try to extract GitHub URL from the replied message
   // Issue #1325: Support all options via /solve command when replying (e.g., "/solve --model opus")
@@ -958,11 +929,16 @@ async function handleSolveCommand(ctx) {
   const toolQueuedCount = queueStats.queuedByTool[solveTool] || 0; // tool-specific queue count (#1551)
   // Issue #378: propagate user's effective Telegram locale to the spawned solve session.
   const argsWithLocale = injectLanguageIfMissing(args, solveLocale);
+
+  // Issue #594: append "Limits at start" to infoBlock; thread snapshot via sessionInfo.
+  let solveLimitsAtStart = null;
+  if (solveShowLimits) ({ infoBlock, limitsAtStart: solveLimitsAtStart } = await captureStartSnapshotAndAppend({ infoBlock, tool: solveTool, verbose: VERBOSE, limitsLib, commandLabel: '/solve' }));
+
   if (check.canStart && toolQueuedCount === 0) {
     const startingMessage = await safeReply(ctx, formatStartingWorkSessionMessage({ infoBlock }), { reply_to_message_id: ctx.message.message_id });
-    await executeAndUpdateMessage(ctx, startingMessage, 'solve', argsWithLocale, infoBlock, effectiveSolveIsolation, solveTool, solveUrlContext);
+    await executeAndUpdateMessage(ctx, startingMessage, 'solve', argsWithLocale, infoBlock, effectiveSolveIsolation, solveTool, solveUrlContext, { showLimits: solveShowLimits, limitsAtStart: solveLimitsAtStart });
   } else {
-    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args: argsWithLocale, ctx, requester, infoBlock, tool: solveTool, perCommandIsolation: effectiveSolveIsolation, urlContext: solveUrlContext });
+    const queueItem = solveQueue.enqueue({ url: normalizedUrl, args: argsWithLocale, ctx, requester, infoBlock, tool: solveTool, perCommandIsolation: effectiveSolveIsolation, urlContext: solveUrlContext, showLimits: solveShowLimits, limitsAtStart: solveLimitsAtStart });
     let queueMessage = `📋 Solve command queued (${solveTool} queue position #${toolQueuedCount + 1})\n\n${infoBlock}`; // tool-specific position (#1551)
     if (check.reason) queueMessage += `\n\n⏳ Waiting: ${escapeMarkdown(check.reason)}`;
     const queuedMessage = await safeReply(ctx, queueMessage, { reply_to_message_id: ctx.message.message_id });
@@ -1049,7 +1025,13 @@ async function handleHiveCommand(ctx) {
 
   VERBOSE && console.log('[VERBOSE] /hive passed all checks, executing...');
 
-  const userArgs = parseCommandArgs(ctx.message.text);
+  let userArgs = parseCommandArgs(ctx.message.text);
+
+  // Issue #594: see /solve handler.
+  const hiveSL = await handleShowLimitsFlag({ ctx, safeReply, args: userArgs, enabled: SHOW_LIMITS_ENABLED });
+  if (hiveSL.handled) return;
+  const hiveShowLimits = hiveSL.showLimits;
+  userArgs = hiveSL.args;
 
   // Issue #1102: Allow issues_list/pulls_list URLs and normalize to repo URLs
   const validation = await validateGitHubUrl(userArgs, { allowedTypes: ['repo', 'organization', 'user', 'issues_list', 'pulls_list'], commandName: 'hive', createYargsConfig: createHiveYargsConfig, positionalNames: ['github-url'] });
@@ -1125,10 +1107,14 @@ async function handleHiveCommand(ctx) {
     infoBlock += `${userOptionsRaw ? '\n' : '\n\n'}🔒 Locked options: ${escapeMarkdown(hiveOverrides.join(' '))}`;
   }
 
+  // Issue #594: see /solve handler.
+  let hiveLimitsAtStart = null;
+  if (hiveShowLimits) ({ infoBlock, limitsAtStart: hiveLimitsAtStart } = await captureStartSnapshotAndAppend({ infoBlock, tool: hiveTool, verbose: VERBOSE, limitsLib, commandLabel: '/hive' }));
+
   const startingMessage = await safeReply(ctx, formatStartingWorkSessionMessage({ infoBlock }), { reply_to_message_id: ctx.message.message_id });
   // Issue #378: propagate user's effective Telegram locale to the spawned hive session.
   const hiveArgsWithLocale = injectLanguageIfMissing(args, hiveLocale);
-  await executeAndUpdateMessage(ctx, startingMessage, 'hive', hiveArgsWithLocale, infoBlock, effectiveHiveIsolation, hiveTool);
+  await executeAndUpdateMessage(ctx, startingMessage, 'hive', hiveArgsWithLocale, infoBlock, effectiveHiveIsolation, hiveTool, null, { showLimits: hiveShowLimits, limitsAtStart: hiveLimitsAtStart });
 }
 
 bot.command(/^hive$/i, handleHiveCommand);

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

@@ -73,6 +73,70 @@ function executeWithCommand(startScreenCmd, command, args, verbose = false) {
   });
 }
 
+/**
+ * Build the executeAndUpdateMessage function used by /solve and /hive in
+ * telegram-bot.mjs. The original function captures ~10 module-level closures
+ * (resolveIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE, executeStartScreen,
+ * trackSession, AUTO_WATCH_MESSAGE, startAutoTerminalWatchForSession, bot,
+ * formatExecutingWorkSessionMessage); the factory pattern lets us extract the
+ * function while still keeping all those handles available without making them
+ * module-global elsewhere. Splitting this out keeps telegram-bot.mjs under the
+ * 1500-line cap (issues #1141, #1730, #594).
+ *
+ * @param {Object} deps - Dependencies captured at bot startup time.
+ * @param {Function} deps.resolveIsolation
+ * @param {string|null} deps.ISOLATION_BACKEND
+ * @param {Object} deps.isolationRunner
+ * @param {boolean} deps.VERBOSE
+ * @param {Function} deps.executeStartScreen
+ * @param {Function} deps.trackSession
+ * @param {boolean} deps.AUTO_WATCH_MESSAGE
+ * @param {Function} deps.startAutoTerminalWatchForSession
+ * @param {Object} deps.bot
+ * @param {Function} deps.formatExecutingWorkSessionMessage
+ * @returns {Function} executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation, tool, urlContext, sessionExtras)
+ */
+export function buildExecuteAndUpdateMessage(deps) {
+  const { resolveIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE, executeStartScreen, trackSession, AUTO_WATCH_MESSAGE, startAutoTerminalWatchForSession, bot, formatExecutingWorkSessionMessage } = deps;
+  return async function executeAndUpdateMessage(ctx, startingMessage, commandName, args, infoBlock, perCommandIsolation = null, tool = 'claude', urlContext = null, { showLimits = false, limitsAtStart = null } = {}) {
+    const { chat, message_id: msgId } = startingMessage;
+    const safeEdit = async text => {
+      try {
+        await ctx.telegram.editMessageText(chat.id, msgId, undefined, text, { parse_mode: 'Markdown' });
+      } catch (e) {
+        console.error(`[telegram-bot] Failed to update message for ${commandName}: ${e.message}`);
+      }
+    };
+    const requesterUserId = ctx.from?.id ?? null; // Issue #1688: suppress duplicate /subscribe DM
+    const baseSessionInfo = { chatId: ctx.chat.id, messageId: msgId, startTime: new Date(), url: args[0], command: commandName, tool, infoBlock, urlContext, requesterUserId, showLimits, limitsAtStart }; // #594: showLimits/limitsAtStart
+    const iso = await resolveIsolation(perCommandIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE);
+    let result, session, sessionInfo;
+    if (iso) {
+      session = iso.runner.generateSessionId();
+      VERBOSE && console.log(`[VERBOSE] Using isolation (${iso.backend}), session: ${session}`);
+      result = await iso.runner.executeWithIsolation(commandName, args, { backend: iso.backend, sessionId: session, verbose: VERBOSE });
+      if (result.success) {
+        sessionInfo = { ...baseSessionInfo, isolationBackend: iso.backend, sessionId: session };
+        trackSession(session, sessionInfo, VERBOSE);
+      }
+    } else {
+      result = await executeStartScreen(commandName, args);
+      const match = result.success && (result.output.match(/session:\s*(\S+)/i) || result.output.match(/screen -R\s+(\S+)/));
+      session = match ? match[1] : 'unknown';
+      // Issue #1586: Non-isolation sessions auto-expire after 10 min — screen stays alive via `exec bash` so completion can't be detected reliably; this still blocks duplicate commands in the timeout window.
+      if (result.success && session !== 'unknown') {
+        sessionInfo = baseSessionInfo;
+        trackSession(session, sessionInfo, VERBOSE);
+      }
+    }
+    if (result.warning) return safeEdit(`⚠️  ${result.warning}`);
+    if (result.success) {
+      await safeEdit(formatExecutingWorkSessionMessage({ sessionName: session, isolationBackend: iso?.backend || null, infoBlock }));
+      if (AUTO_WATCH_MESSAGE && commandName === 'solve' && sessionInfo?.isolationBackend) await startAutoTerminalWatchForSession({ bot, ctx, sessionId: session, sessionInfo, verbose: VERBOSE });
+    } else await safeEdit(`❌ Error executing ${commandName} command:\n\n\`\`\`\n${result.error || result.output}\n\`\`\`\n\n${infoBlock}`);
+  };
+}
+
 export async function executeStartScreen(command, args, options = {}) {
   const { verbose = false } = options;
 

package/src/telegram-show-limits.lib.mjs

@@ -0,0 +1,281 @@
+/**
+ * Telegram bot virtual option: --show-limits (experimental).
+ *
+ * The --show-limits flag is intercepted by hive-telegram-bot and stripped from
+ * the args before they are forwarded to /solve, /hive (or /task --split). When
+ * set, the bot:
+ *   1. Fetches usage limits for the selected tool (Claude or Codex) using the
+ *      shared cached helpers in limits.lib.mjs (TTL: 20 minutes for the usage
+ *      API to avoid rate limiting).
+ *   2. Embeds a compact "Limits at start" snapshot below the infoBlock so the
+ *      starting/executing message shows the user how much budget they had at
+ *      the moment the command was queued.
+ *   3. Captures the snapshot in the per-session record so the completion
+ *      message can render an end-of-task snapshot plus a delta. The delta is
+ *      not exact — multiple parallel sessions all consume from the same
+ *      budget — and is reported as such.
+ *
+ * The flag is purely a Telegram bot concern; downstream commands never see it.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/594
+ */
+
+const SHOW_LIMITS_FLAG = '--show-limits';
+const NO_SHOW_LIMITS_FLAG = '--no-show-limits';
+
+/**
+ * Detect whether the user passed --show-limits (or --no-show-limits to opt out)
+ * and return a copy of the args without that flag.
+ *
+ * Last occurrence wins, matching how yargs resolves repeated boolean flags.
+ *
+ * @param {string[]} args
+ * @returns {{ showLimits: boolean|null, args: string[] }}
+ *   `showLimits` is `true`/`false` when explicitly set, or `null` when absent.
+ */
+export function extractShowLimitsFlag(args) {
+  if (!Array.isArray(args)) return { showLimits: null, args: args || [] };
+  let showLimits = null;
+  const filtered = [];
+  for (const arg of args) {
+    if (arg === SHOW_LIMITS_FLAG) {
+      showLimits = true;
+      continue;
+    }
+    if (arg === NO_SHOW_LIMITS_FLAG) {
+      showLimits = false;
+      continue;
+    }
+    if (arg === '--show-limits=true' || arg === '--show-limits=1') {
+      showLimits = true;
+      continue;
+    }
+    if (arg === '--show-limits=false' || arg === '--show-limits=0') {
+      showLimits = false;
+      continue;
+    }
+    filtered.push(arg);
+  }
+  return { showLimits, args: filtered };
+}
+
+/**
+ * Pick a tool key for limits selection. Codex-like tools route to Codex, the
+ * rest of the supported tools (claude, opencode, agent, gemini, qwen) route to
+ * Claude. This mirrors how solve.mjs selects which CLI to invoke.
+ *
+ * @param {string|null|undefined} tool
+ * @returns {'codex'|'claude'}
+ */
+export function pickLimitsToolKey(tool) {
+  return String(tool || '').toLowerCase() === 'codex' ? 'codex' : 'claude';
+}
+
+/**
+ * Fetch the cached limits snapshot for the given tool. Returns a normalized
+ * shape that captures both the raw `success/usage/error` payload and a
+ * `toolKey` so the renderers know which formatter to use.
+ *
+ * @param {Object} options
+ * @param {string} [options.tool='claude']
+ * @param {boolean} [options.verbose=false]
+ * @param {{ getCachedClaudeLimits: Function, getCachedCodexLimits: Function }} options.limitsLib
+ * @returns {Promise<{ toolKey: 'codex'|'claude', success: boolean, usage?: any, error?: string, capturedAt: Date, additionalRateLimits?: any[], credits?: any, planType?: any }>}
+ */
+export async function captureLimitsSnapshot({ tool = 'claude', verbose = false, limitsLib } = {}) {
+  if (!limitsLib) throw new Error('captureLimitsSnapshot requires limitsLib');
+  const toolKey = pickLimitsToolKey(tool);
+  const fetcher = toolKey === 'codex' ? limitsLib.getCachedCodexLimits : limitsLib.getCachedClaudeLimits;
+  const result = await fetcher(verbose);
+  return {
+    toolKey,
+    success: !!result?.success,
+    usage: result?.usage || null,
+    error: result?.success ? null : result?.error || 'Unknown error',
+    capturedAt: new Date(),
+    additionalRateLimits: result?.additionalRateLimits || null,
+    credits: result?.credits || null,
+    planType: result?.planType || null,
+  };
+}
+
+function pct(value) {
+  if (value === null || value === undefined) return null;
+  const num = Number(value);
+  if (!Number.isFinite(num)) return null;
+  return Math.floor(num);
+}
+
+function formatPercentage(value) {
+  const p = pct(value);
+  return p === null ? 'N/A' : `${p}%`;
+}
+
+/**
+ * Render a compact one-line-per-window summary of a Claude snapshot.
+ * The compact form is used inside a Markdown code block under the infoBlock.
+ *
+ * @param {Object} snapshot - Result of captureLimitsSnapshot for tool=claude
+ * @returns {string}
+ */
+function formatClaudeSnapshotCompact(snapshot) {
+  if (!snapshot) return 'Claude limits: N/A';
+  if (!snapshot.success) return `Claude limits: ${snapshot.error || 'unavailable'}`;
+  const usage = snapshot.usage || {};
+  const lines = [];
+  lines.push(`5h session: ${formatPercentage(usage.currentSession?.percentage)}`);
+  lines.push(`7d all models: ${formatPercentage(usage.allModels?.percentage)}`);
+  if (usage.sonnetOnly && usage.sonnetOnly.percentage !== null && usage.sonnetOnly.percentage !== undefined) {
+    lines.push(`7d Sonnet only: ${formatPercentage(usage.sonnetOnly.percentage)}`);
+  }
+  return lines.join('\n');
+}
+
+function formatCodexSnapshotCompact(snapshot) {
+  if (!snapshot) return 'Codex limits: N/A';
+  if (!snapshot.success) return `Codex limits: ${snapshot.error || 'unavailable'}`;
+  const usage = snapshot.usage || {};
+  const lines = [];
+  lines.push(`5h session: ${formatPercentage(usage.currentSession?.percentage)}`);
+  lines.push(`Weekly: ${formatPercentage(usage.allModels?.percentage)}`);
+  return lines.join('\n');
+}
+
+/**
+ * Format a snapshot as a fenced code block suitable for prepending/appending
+ * inside the info block of a Telegram message.
+ *
+ * @param {Object} snapshot
+ * @param {Object} [options]
+ * @param {string} [options.title='📊 Limits at start'] Block title
+ * @returns {string}
+ */
+export function formatLimitsSnapshotBlock(snapshot, { title = '📊 Limits at start' } = {}) {
+  if (!snapshot) return '';
+  const heading = snapshot.toolKey === 'codex' ? 'Codex' : 'Claude';
+  const body = snapshot.toolKey === 'codex' ? formatCodexSnapshotCompact(snapshot) : formatClaudeSnapshotCompact(snapshot);
+  return `${title} (${heading})\n\`\`\`\n${body}\n\`\`\``;
+}
+
+function deltaFor(startPct, endPct) {
+  const s = pct(startPct);
+  const e = pct(endPct);
+  if (s === null || e === null) return null;
+  return e - s;
+}
+
+function formatDeltaValue(delta) {
+  if (delta === null || delta === undefined) return 'N/A';
+  if (delta === 0) return '±0%';
+  const sign = delta > 0 ? '+' : '';
+  return `${sign}${delta}%`;
+}
+
+/**
+ * Format a "Limits change" block summarizing start, end, and delta for the
+ * configured windows. Includes a disclaimer about parallel sessions.
+ *
+ * @param {Object|null} startSnapshot
+ * @param {Object|null} endSnapshot
+ * @returns {string}
+ */
+export function formatLimitsDeltaBlock(startSnapshot, endSnapshot) {
+  if (!startSnapshot || !endSnapshot) return '';
+  if (startSnapshot.toolKey !== endSnapshot.toolKey) return '';
+  const heading = startSnapshot.toolKey === 'codex' ? 'Codex' : 'Claude';
+  const lines = [];
+
+  if (!startSnapshot.success && !endSnapshot.success) {
+    lines.push(`Start: ${startSnapshot.error || 'unavailable'}`);
+    lines.push(`End: ${endSnapshot.error || 'unavailable'}`);
+  } else {
+    const startUsage = startSnapshot.usage || {};
+    const endUsage = endSnapshot.usage || {};
+
+    const sessionLabel = '5h session';
+    lines.push(`${sessionLabel}: ${formatPercentage(startUsage.currentSession?.percentage)} → ${formatPercentage(endUsage.currentSession?.percentage)} (${formatDeltaValue(deltaFor(startUsage.currentSession?.percentage, endUsage.currentSession?.percentage))})`);
+
+    const allModelsLabel = startSnapshot.toolKey === 'codex' ? 'Weekly' : '7d all models';
+    lines.push(`${allModelsLabel}: ${formatPercentage(startUsage.allModels?.percentage)} → ${formatPercentage(endUsage.allModels?.percentage)} (${formatDeltaValue(deltaFor(startUsage.allModels?.percentage, endUsage.allModels?.percentage))})`);
+
+    if (startSnapshot.toolKey === 'claude' && ((startUsage.sonnetOnly && startUsage.sonnetOnly.percentage !== null && startUsage.sonnetOnly.percentage !== undefined) || (endUsage.sonnetOnly && endUsage.sonnetOnly.percentage !== null && endUsage.sonnetOnly.percentage !== undefined))) {
+      lines.push(`7d Sonnet only: ${formatPercentage(startUsage.sonnetOnly?.percentage)} → ${formatPercentage(endUsage.sonnetOnly?.percentage)} (${formatDeltaValue(deltaFor(startUsage.sonnetOnly?.percentage, endUsage.sonnetOnly?.percentage))})`);
+    }
+  }
+
+  // Note: delta is not precise because multiple parallel tasks may consume
+  // from the same Anthropic/OpenAI budget windows during the run.
+  lines.push('Note: delta is approximate (parallel sessions share the same budget).');
+
+  return `📊 Limits change (${heading})\n\`\`\`\n${lines.join('\n')}\n\`\`\``;
+}
+
+/**
+ * Append a free-form section (e.g. limits block) to an existing infoBlock,
+ * preserving Markdown structure. A blank line separates sections so the
+ * Telegram message stays readable.
+ *
+ * @param {string} infoBlock
+ * @param {string} addition
+ * @returns {string}
+ */
+export function appendInfoSection(infoBlock, addition) {
+  const base = infoBlock || '';
+  const extra = addition || '';
+  if (!extra) return base;
+  if (!base) return extra;
+  return `${base}\n\n${extra}`;
+}
+
+/**
+ * High-level helper used by /solve and /hive: parse `--show-limits` out of the
+ * raw user args, decide whether the flag is honored (subject to the bot
+ * administrator's TELEGRAM_SHOW_LIMITS toggle), and either reply with a
+ * rejection message (returning {handled:true}) or hand back the stripped args
+ * and a boolean for the caller to thread through.
+ *
+ * @param {Object} options
+ * @param {Object} options.ctx - Telegraf context (used to reply on rejection)
+ * @param {Function} options.safeReply - safeReply(ctx, text, opts)
+ * @param {string[]} options.args - Raw user args before stripping
+ * @param {boolean} options.enabled - Master switch (config.showLimits)
+ * @returns {Promise<{ handled: boolean, args: string[], showLimits: boolean }>}
+ */
+export async function handleShowLimitsFlag({ ctx, safeReply, args, enabled }) {
+  const { showLimits, args: stripped } = extractShowLimitsFlag(args);
+  if (showLimits === true && !enabled) {
+    await safeReply(ctx, '❌ `--show-limits` is disabled by the bot administrator.', { reply_to_message_id: ctx.message.message_id });
+    return { handled: true, args: stripped, showLimits: false };
+  }
+  return { handled: false, args: stripped, showLimits: showLimits === true && enabled };
+}
+
+/**
+ * Capture a "limits at start" snapshot for the given tool and append a
+ * formatted block to `infoBlock`. Errors are logged via the optional
+ * `verbose` flag and silently swallowed so a transient API failure does not
+ * abort the user's command.
+ *
+ * @param {Object} options
+ * @param {string} options.infoBlock - Existing infoBlock to append to
+ * @param {string} [options.tool='claude']
+ * @param {boolean} [options.verbose=false]
+ * @param {Object} options.limitsLib - { getCachedClaudeLimits, getCachedCodexLimits }
+ * @param {string} [options.commandLabel='command'] - For verbose logging
+ * @returns {Promise<{ infoBlock: string, limitsAtStart: Object|null }>}
+ */
+export async function captureStartSnapshotAndAppend({ infoBlock, tool = 'claude', verbose = false, limitsLib, commandLabel = 'command' } = {}) {
+  let limitsAtStart = null;
+  let nextInfoBlock = infoBlock || '';
+  try {
+    limitsAtStart = await captureLimitsSnapshot({ tool, verbose, limitsLib });
+    const block = formatLimitsSnapshotBlock(limitsAtStart, { title: '📊 Limits at start' });
+    if (block) nextInfoBlock = appendInfoSection(nextInfoBlock, block);
+  } catch (e) {
+    if (verbose) console.log(`[VERBOSE] ${commandLabel} --show-limits snapshot failed: ${e?.message || e}`);
+  }
+  return { infoBlock: nextInfoBlock, limitsAtStart };
+}
+
+export const SHOW_LIMITS_FLAG_NAME = SHOW_LIMITS_FLAG;
+export const NO_SHOW_LIMITS_FLAG_NAME = NO_SHOW_LIMITS_FLAG;

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

@@ -48,6 +48,9 @@ class SolveQueueItem {
     this.urlContext = options.urlContext || null;
     // Issue #1688: requester user ID for /subscribe duplicate-suppression.
     this.requesterUserId = options.ctx?.from?.id ?? null;
+    // Issue #594: --show-limits virtual option (hive-telegram-bot only).
+    this.showLimits = options.showLimits === true;
+    this.limitsAtStart = options.limitsAtStart || null;
     this.createdAt = new Date();
     this.startedAt = null;
     this.status = QueueItemStatus.QUEUED;
@@ -1407,6 +1410,11 @@ export function createQueueExecuteCallback(executeStartScreen, trackSessionFn) {
           //   notifying the requester twice via /subscribe.
           urlContext: item.urlContext || null,
           requesterUserId: item.requesterUserId ?? null,
+          // Issue #594: --show-limits virtual option carries the start-of-task
+          //   snapshot from the queueing point through to the completion
+          //   handler so it can render an end-of-task delta.
+          showLimits: item.showLimits === true,
+          limitsAtStart: item.limitsAtStart || null,
         });
       }
     }

package/src/work-session-formatting.lib.mjs

@@ -83,7 +83,7 @@ export function appendPullRequestLine(infoBlock, pullRequestUrl) {
   return [...before, prLine, ...after].join('\n');
 }
 
-export function formatSessionCompletionMessage({ sessionName, sessionInfo, statusResult = null, observedEndTime = new Date(), exitCode = null, infoBlock = '', pullRequestUrl = null } = {}) {
+export function formatSessionCompletionMessage({ sessionName, sessionInfo, statusResult = null, observedEndTime = new Date(), exitCode = null, infoBlock = '', pullRequestUrl = null, extraSections = [] } = {}) {
   const finalExitCode = getSessionCompletionExitCode({ exitCode, statusResult });
   const failed = finalExitCode !== null && finalExitCode !== 0;
   const statusEmoji = failed ? '❌' : '✅';
@@ -102,5 +102,12 @@ export function formatSessionCompletionMessage({ sessionName, sessionInfo, statu
   message += `⏱️ Duration: ${formatSessionDurationSeconds(durationSeconds)}\n`;
   message += `📊 Session: \`${sessionName || 'unknown'}\`${isolationInfo}${details}`;
 
+  // Issue #594: --show-limits virtual option appends snapshot/delta sections
+  // (Markdown code blocks) below the standard completion details.
+  const extras = (Array.isArray(extraSections) ? extraSections : []).filter(Boolean);
+  if (extras.length > 0) {
+    message += `\n\n${extras.join('\n\n')}`;
+  }
+
   return message;
 }