@link-assistant/hive-mind 1.43.0 → 1.45.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @link-assistant/hive-mind
 
+## 1.45.0
+
+### Minor Changes
+
+- c308660: Add experimental live progress monitoring for work sessions
+  - Implement `--working-session-live-progress [comment|pr]` CLI flag for both solve and hive commands
+    - `comment` mode (default): Creates a per-session PR comment with updatable progress section
+    - `pr` mode: Updates PR description with live progress section
+    - Plain `--working-session-live-progress` defaults to `comment` mode
+  - Create progress monitoring module (`solve.progress-monitoring.lib.mjs`) with:
+    - Live TODO list tracking from TodoWrite tool calls
+    - Progress bar visualization (percentage complete)
+    - Comment mode: creates/edits a dedicated PR comment per work session
+    - PR mode: updates PR description with progress section
+    - Task list is always shown expanded (never collapsible)
+    - Rate limiting to avoid GitHub API throttling
+  - Integrate progress monitoring into claude.lib.mjs event stream processing
+    - Detects TodoWrite tool_use events (assistant) and tool_use_result events (user)
+    - Updates progress when TodoWrite tool is invoked
+    - Displays task completion stats and progress bar
+    - Supports work session identification
+  - Works with or without `--interactive-mode` (independent feature)
+  - Auto-registered in hive via SOLVE_OPTION_DEFINITIONS (no manual forwarding needed)
+  - Add comprehensive test suite (89 tests) covering:
+    - Progress calculation and formatting
+    - Display mode normalization
+    - CLI configuration in solve and hive
+    - Auto-registration and forwarding via getSolvePassthroughOptionNames
+    - Claude integration for TodoWrite detection
+    - Comment and PR display modes
+  - Feature is experimental, opt-in via `--working-session-live-progress`
+  - Implements issue #936
+
+## 1.44.0
+
+### Minor Changes
+
+- e7ce2dd: Add TELEGRAM_ALLOWED_TOPICS for forum topic filtering (issue #1100)
+
 ## 1.43.0
 
 ### Minor Changes

package/package.json

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

package/src/claude.lib.mjs

@@ -11,6 +11,7 @@ import { reportError } from './sentry.lib.mjs';
 import { timeouts, retryLimits, claudeCode, getClaudeEnv, getThinkingLevelToTokens, getTokensToThinkingLevel, supportsThinkingBudget, DEFAULT_MAX_THINKING_BUDGET, getMaxOutputTokensForModel } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 import { createInteractiveHandler } from './interactive-mode.lib.mjs';
+import { initProgressMonitoring } from './solve.progress-monitoring.lib.mjs';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { displayBudgetStats, createEmptySubSessionUsage, accumulateModelUsage, displayModelUsage, displayCostComparison, mergeResultModelUsage } from './claude.budget-stats.lib.mjs';
 import { buildClaudeResumeCommand } from './claude.command-builder.lib.mjs';
@@ -668,10 +669,8 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
 export const isStderrError = message => {
   const trimmed = message.trim();
   if (!trimmed) return false;
-
   // Detection 1: Emoji-prefixed warnings (Issue #477)
   let isWarning = trimmed.startsWith('⚠️') || trimmed.startsWith('⚠');
-
   // Detection 2: JSON-structured log messages (Issue #1337)
   if (!isWarning && trimmed.startsWith('{')) {
     try {
@@ -687,13 +686,11 @@ export const isStderrError = message => {
       // Not valid JSON — fall through to keyword matching
     }
   }
-
   if (!isWarning && (trimmed.includes('Error:') || trimmed.includes('error') || trimmed.includes('failed') || trimmed.includes('not found'))) {
     return true;
   }
   return false;
 };
-
 export const executeClaudeCommand = async params => {
   const {
     tempDir,
@@ -796,6 +793,7 @@ export const executeClaudeCommand = async params => {
     } else if (argv.interactiveMode) {
       await log('⚠️ Interactive mode: Disabled - missing PR info (owner/repo/prNumber)', { verbose: true });
     }
+    const progressMonitor = await initProgressMonitoring(argv, { owner, repo, prNumber, $, log }); // works with or without --interactive-mode
     let execCommand;
     const mappedModel = mapModelToId(argv.model);
     const resolvedPlanModel = argv.planModel ? mapModelToId(argv.planModel) : undefined; // Issue #1223
@@ -962,6 +960,7 @@ export const executeClaudeCommand = async params => {
               }
               if (data.type === 'message') messageCount++;
               else if (data.type === 'tool_use') toolUseCount++;
+              if (progressMonitor) await progressMonitor.processStreamEvent(data).catch(e => log(`⚠️ Progress: ${e.message}`, { verbose: true }));
               if (data.type === 'result') {
                 if (!resultEventReceived) {
                   resultEventReceived = true;
@@ -1121,6 +1120,7 @@ export const executeClaudeCommand = async params => {
               await log(`⚠️ Interactive mode error (remaining buffer): ${interactiveError.message}`, { verbose: true });
             }
           }
+          if (progressMonitor) await progressMonitor.processStreamEvent(data, true).catch(e => log(`⚠️ Progress: ${e.message}`, { verbose: true }));
         } catch {
           if (!stdoutLineBuffer.includes('node:internal')) await log(stdoutLineBuffer, { stream: 'raw' });
         }

package/src/lino.lib.mjs

@@ -96,6 +96,48 @@ export class LinksNotationManager {
     return [];
   }
 
+  parseLinks(input) {
+    if (!input) return [];
+
+    const parsed = this.parser.parse(input);
+    if (!parsed || parsed.length === 0) return [];
+
+    const link = parsed[0];
+    const pairs = [];
+
+    if (link.values && link.values.length > 0) {
+      const flatNumbers = [];
+
+      for (const value of link.values) {
+        if (value.id === null && value.values && value.values.length >= 2) {
+          const source = parseInt(value.values[0]?.id || value.values[0], 10);
+          const target = parseInt(value.values[1]?.id || value.values[1], 10);
+          if (!isNaN(source) && !isNaN(target)) {
+            pairs.push({ source, target });
+          }
+        } else if (value.id) {
+          const num = parseInt(value.id, 10);
+          if (!isNaN(num)) {
+            flatNumbers.push(num);
+          }
+        }
+      }
+
+      for (let i = 0; i < flatNumbers.length - 1; i += 2) {
+        pairs.push({ source: flatNumbers[i], target: flatNumbers[i + 1] });
+      }
+    }
+
+    return pairs;
+  }
+
+  formatLinks(pairs) {
+    if (!pairs || pairs.length === 0) return '()';
+
+    const formattedValues = pairs.map(pair => `  ${pair.source} ${pair.target}`).join('\n');
+    return `(\n${formattedValues}\n)`;
+  }
+
   format(values) {
     if (!values || values.length === 0) return '()';
 

package/src/solve.config.lib.mjs

@@ -429,6 +429,11 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: '[EXPERIMENTAL] Model to use for --finalize iterations. Defaults to the same model as --model.',
     default: undefined,
   },
+  'working-session-live-progress': {
+    type: 'string',
+    description: '[EXPERIMENTAL] Enable live progress monitoring. Accepts "comment" (default, updates a per-session PR comment) or "pr" (updates PR description). Plain --working-session-live-progress means "comment". Works with or without --interactive-mode.',
+    default: false,
+  },
 };
 
 // Function to create yargs configuration - avoids duplication
@@ -607,6 +612,20 @@ export const parseArguments = async (yargs, hideBin) => {
     }
   }
 
+  // --working-session-live-progress normalization
+  // When passed as --working-session-live-progress (no value), yargs gives true for string type
+  // Normalize: true → "comment", validate known values
+  if (argv && argv.workingSessionLiveProgress) {
+    const val = argv.workingSessionLiveProgress;
+    if (val === true || val === 'true') {
+      argv.workingSessionLiveProgress = 'comment';
+    } else if (typeof val === 'string' && !['comment', 'pr'].includes(val.toLowerCase())) {
+      throw new Error(`Invalid --working-session-live-progress value: "${val}". Expected "comment" or "pr".`);
+    } else if (typeof val === 'string') {
+      argv.workingSessionLiveProgress = val.toLowerCase();
+    }
+  }
+
   // Validate --base-branch value (issue #1482: reject URLs and invalid git branch names)
   if (argv.baseBranch) {
     const branchValidation = validateBranchName(argv.baseBranch);

package/src/solve.progress-monitoring.lib.mjs

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+/**
+ * Progress Monitoring Library
+ *
+ * [EXPERIMENTAL] This module provides live progress monitoring for work sessions
+ * by tracking TODO list updates and reflecting them in PR comments or descriptions.
+ *
+ * Display modes:
+ * - "comment" (default): Creates a per-session PR comment with updatable progress section
+ * - "pr": Updates the PR description with a live progress section
+ *
+ * Features:
+ * - Tracks TODO list state from TodoWrite tool calls
+ * - Calculates progress percentage (completed/total)
+ * - Generates progress bar visualization
+ * - Task list is always shown expanded (never collapsible)
+ *
+ * Usage:
+ *   const { createProgressMonitor } = await import('./solve.progress-monitoring.lib.mjs');
+ *   const monitor = createProgressMonitor({ owner, repo, prNumber, $, log, displayMode: 'comment' });
+ *   await monitor.updateProgress(todos);
+ *
+ * @module solve.progress-monitoring.lib.mjs
+ * @experimental
+ */
+
+/**
+ * Configuration constants for progress monitoring
+ */
+const CONFIG = {
+  // Progress bar width in characters
+  PROGRESS_BAR_WIDTH: 30,
+  // Progress bar characters
+  PROGRESS_CHAR_FILLED: '█',
+  PROGRESS_CHAR_EMPTY: '░',
+  // Marker comments for identifying the progress section
+  PROGRESS_SECTION_START: '<!-- LIVE-PROGRESS-START -->',
+  PROGRESS_SECTION_END: '<!-- LIVE-PROGRESS-END -->',
+  // Minimum interval between PR description updates (in ms)
+  MIN_UPDATE_INTERVAL: 10000, // 10 seconds to avoid rate limiting
+  // Valid display modes
+  DISPLAY_MODES: ['comment', 'pr'],
+  // Default display mode when enabled without explicit value
+  DEFAULT_DISPLAY_MODE: 'comment',
+};
+
+/**
+ * Generate a progress bar visualization
+ *
+ * @param {number} percentage - Progress percentage (0-100)
+ * @param {number} width - Width of the progress bar in characters
+ * @returns {string} Progress bar string
+ */
+const generateProgressBar = (percentage, width = CONFIG.PROGRESS_BAR_WIDTH) => {
+  const clamped = Math.max(0, Math.min(100, percentage));
+  const filled = Math.round((clamped / 100) * width);
+  const empty = width - filled;
+  return CONFIG.PROGRESS_CHAR_FILLED.repeat(filled) + CONFIG.PROGRESS_CHAR_EMPTY.repeat(empty);
+};
+
+/**
+ * Calculate progress statistics from TODO list
+ *
+ * @param {Array<Object>} todos - Array of TODO items with status property
+ * @returns {Object} Progress statistics
+ */
+const calculateProgress = todos => {
+  if (!todos || !Array.isArray(todos) || todos.length === 0) {
+    return {
+      total: 0,
+      completed: 0,
+      inProgress: 0,
+      pending: 0,
+      percentage: 0,
+    };
+  }
+
+  const total = todos.length;
+  const completed = todos.filter(t => t.status === 'completed').length;
+  const inProgress = todos.filter(t => t.status === 'in_progress').length;
+  const pending = todos.filter(t => t.status === 'pending').length;
+  const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+  return { total, completed, inProgress, pending, percentage };
+};
+
+/**
+ * Format TODO list for display
+ *
+ * @param {Array<Object>} todos - Array of TODO items
+ * @param {number} maxDisplay - Maximum number of TODOs to show (0 for all)
+ * @returns {string} Formatted TODO list
+ */
+const formatTodoList = (todos, maxDisplay = 0) => {
+  if (!todos || todos.length === 0) {
+    return '_No tasks yet_';
+  }
+
+  const getStatusIcon = status => {
+    switch (status) {
+      case 'completed':
+        return '[x]';
+      case 'in_progress':
+        return '[~]';
+      case 'pending':
+        return '[ ]';
+      default:
+        return '[ ]';
+    }
+  };
+
+  let todosToShow = todos;
+  if (maxDisplay > 0 && todos.length > maxDisplay) {
+    const half = Math.floor(maxDisplay / 2);
+    const firstHalf = todos.slice(0, half);
+    const secondHalf = todos.slice(-half);
+    const skipped = todos.length - maxDisplay;
+
+    todosToShow = [...firstHalf, { content: `_...and ${skipped} more tasks_`, status: 'info' }, ...secondHalf];
+  }
+
+  return todosToShow
+    .map(todo => {
+      if (todo.status === 'info') {
+        return `- ${todo.content}`;
+      }
+      return `- ${getStatusIcon(todo.status)} ${todo.content}`;
+    })
+    .join('\n');
+};
+
+/**
+ * Generate the progress section markdown (never collapsible)
+ *
+ * @param {Array<Object>} todos - Array of TODO items
+ * @param {string} sessionId - Work session identifier (optional)
+ * @returns {string} Progress section markdown
+ */
+const generateProgressSection = (todos, sessionId = null) => {
+  const stats = calculateProgress(todos);
+  const progressBar = generateProgressBar(stats.percentage);
+  const timestamp = new Date().toISOString();
+
+  return `${CONFIG.PROGRESS_SECTION_START}
+## 📊 Live Progress Monitor
+
+**Session:** ${sessionId || 'Current'}
+**Last Updated:** ${timestamp}
+
+### Progress: ${stats.percentage}% Complete
+
+\`\`\`
+${progressBar} ${stats.percentage}%
+\`\`\`
+
+**Tasks:** ${stats.completed}/${stats.total} completed · ${stats.inProgress} in progress · ${stats.pending} pending
+
+📋 **Task List** (${stats.total} total)
+
+${formatTodoList(todos)}
+
+${CONFIG.PROGRESS_SECTION_END}`;
+};
+
+/**
+ * Normalize the display mode value.
+ * - false/falsy → null (disabled)
+ * - true or "true" → default mode ("comment")
+ * - "comment" or "pr" → that mode
+ *
+ * @param {*} value - Raw option value
+ * @returns {string|null} Normalized display mode or null if disabled
+ */
+export const normalizeDisplayMode = value => {
+  if (!value || value === 'false') return null;
+  if (value === true || value === 'true') return CONFIG.DEFAULT_DISPLAY_MODE;
+  const mode = String(value).toLowerCase();
+  if (CONFIG.DISPLAY_MODES.includes(mode)) return mode;
+  // Unknown value falls back to default
+  return CONFIG.DEFAULT_DISPLAY_MODE;
+};
+
+/**
+ * Create a progress monitor instance
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.owner - Repository owner
+ * @param {string} options.repo - Repository name
+ * @param {number} options.prNumber - Pull request number
+ * @param {Function} options.$ - Zx executor function
+ * @param {Function} options.log - Logging function
+ * @param {boolean} options.verbose - Enable verbose logging
+ * @param {string} options.sessionId - Work session identifier
+ * @param {string} options.displayMode - Display mode: "comment" or "pr"
+ * @returns {Object} Progress monitor instance
+ */
+export const createProgressMonitor = ({ owner, repo, prNumber, $, log, verbose = false, sessionId = null, displayMode = 'comment' }) => {
+  const state = {
+    lastUpdate: 0,
+    currentTodos: null,
+    sessionId: sessionId || `session-${Date.now()}`,
+    commentId: null, // For comment mode: the ID of the progress comment to update
+    displayMode: displayMode || CONFIG.DEFAULT_DISPLAY_MODE,
+  };
+
+  /**
+   * Update progress via PR comment (comment mode)
+   * Creates a new comment on first call, then edits it on subsequent calls.
+   *
+   * @param {Array<Object>} todos - Array of TODO items
+   * @returns {Promise<boolean>} True if update was successful
+   */
+  const updateProgressComment = async todos => {
+    try {
+      state.currentTodos = todos;
+      const progressSection = generateProgressSection(todos, state.sessionId);
+
+      if (state.commentId) {
+        // Edit existing comment
+        const fs = (await import('fs')).promises;
+        const tempFile = `/tmp/pr-progress-comment-${prNumber}-${Date.now()}.md`;
+        await fs.writeFile(tempFile, progressSection);
+        await $`gh api repos/${owner}/${repo}/issues/comments/${state.commentId} --method PATCH --field body=@${tempFile}`;
+        await fs.unlink(tempFile).catch(() => {});
+      } else {
+        // Create new comment
+        const fs = (await import('fs')).promises;
+        const tempFile = `/tmp/pr-progress-comment-${prNumber}-${Date.now()}.md`;
+        await fs.writeFile(tempFile, progressSection);
+        const result = await $`gh pr comment ${prNumber} --repo ${owner}/${repo} --body-file ${tempFile}`;
+        await fs.unlink(tempFile).catch(() => {});
+
+        // Extract comment ID from the created comment URL for future edits
+        // gh pr comment outputs the URL of the created comment
+        const output = result.stdout?.toString?.() || '';
+        const urlMatch = output.match(/\/comments\/(\d+)/);
+        if (urlMatch) {
+          state.commentId = urlMatch[1];
+        } else {
+          // Fallback: find the comment we just created by looking for our marker
+          const commentsResult = await $`gh api repos/${owner}/${repo}/issues/${prNumber}/comments --jq ${`[.[] | select(.body | contains("${CONFIG.PROGRESS_SECTION_START}")) | .id] | last`}`;
+          const commentId = commentsResult.stdout?.toString?.().trim();
+          if (commentId && commentId !== 'null') {
+            state.commentId = commentId;
+          }
+        }
+      }
+
+      const stats = calculateProgress(todos);
+      await log(`📊 Updated progress comment: ${stats.percentage}% (${stats.completed}/${stats.total} tasks completed)`);
+      return true;
+    } catch (error) {
+      await log(`⚠️  Failed to update progress comment: ${error.message}`);
+      return false;
+    }
+  };
+
+  /**
+   * Update progress via PR description (pr mode)
+   *
+   * @param {Array<Object>} todos - Array of TODO items
+   * @returns {Promise<boolean>} True if update was successful
+   */
+  const updateProgressPrDescription = async todos => {
+    try {
+      state.currentTodos = todos;
+
+      // Fetch current PR description
+      const prData = await $`gh pr view ${prNumber} --repo ${owner}/${repo} --json body`;
+      const prInfo = JSON.parse(prData.stdout);
+      let currentBody = prInfo.body || '';
+
+      // Generate new progress section
+      const progressSection = generateProgressSection(todos, state.sessionId);
+
+      // Check if progress section already exists
+      const hasProgressSection = currentBody.includes(CONFIG.PROGRESS_SECTION_START);
+
+      let updatedBody;
+      if (hasProgressSection) {
+        // Replace existing progress section
+        const startIdx = currentBody.indexOf(CONFIG.PROGRESS_SECTION_START);
+        const endIdx = currentBody.indexOf(CONFIG.PROGRESS_SECTION_END);
+
+        if (startIdx !== -1 && endIdx !== -1) {
+          updatedBody = currentBody.substring(0, startIdx) + progressSection + currentBody.substring(endIdx + CONFIG.PROGRESS_SECTION_END.length);
+        } else {
+          updatedBody = currentBody + '\n\n' + progressSection;
+        }
+      } else {
+        updatedBody = currentBody + '\n\n' + progressSection;
+      }
+
+      // Write to temp file and update PR
+      const fs = (await import('fs')).promises;
+      const tempBodyFile = `/tmp/pr-progress-${prNumber}-${Date.now()}.md`;
+      await fs.writeFile(tempBodyFile, updatedBody);
+      await $`gh pr edit ${prNumber} --repo ${owner}/${repo} --body-file ${tempBodyFile}`;
+      await fs.unlink(tempBodyFile).catch(() => {});
+
+      const stats = calculateProgress(todos);
+      await log(`📊 Updated PR progress: ${stats.percentage}% (${stats.completed}/${stats.total} tasks completed)`);
+      return true;
+    } catch (error) {
+      await log(`⚠️  Failed to update PR progress: ${error.message}`);
+      return false;
+    }
+  };
+
+  /**
+   * Update progress using the configured display mode
+   *
+   * @param {Array<Object>} todos - Array of TODO items
+   * @param {boolean} force - Force update even if within rate limit interval
+   * @returns {Promise<boolean>} True if update was successful
+   */
+  const updateProgress = async (todos, force = false) => {
+    const now = Date.now();
+
+    // Rate limiting: don't update too frequently unless forced
+    if (!force && now - state.lastUpdate < CONFIG.MIN_UPDATE_INTERVAL) {
+      if (verbose) {
+        await log(`⏭️  Skipping progress update (rate limited, ${Math.round((CONFIG.MIN_UPDATE_INTERVAL - (now - state.lastUpdate)) / 1000)}s remaining)`, { verbose: true });
+      }
+      return false;
+    }
+
+    let result;
+    if (state.displayMode === 'pr') {
+      result = await updateProgressPrDescription(todos);
+    } else {
+      result = await updateProgressComment(todos);
+    }
+
+    if (result) {
+      state.lastUpdate = now;
+    }
+    return result;
+  };
+
+  /**
+   * Get current progress statistics
+   *
+   * @returns {Object} Current progress statistics
+   */
+  const getStats = () => {
+    return calculateProgress(state.currentTodos);
+  };
+
+  /**
+   * Generate progress section without updating
+   *
+   * @param {Array<Object>} todos - Array of TODO items
+   * @returns {string} Progress section markdown
+   */
+  const generateSection = todos => {
+    return generateProgressSection(todos, state.sessionId);
+  };
+
+  /**
+   * Process a Claude CLI stream event, detecting TodoWrite tool calls
+   * and updating progress automatically. Call this for each parsed NDJSON event.
+   *
+   * @param {Object} data - Parsed JSON event from Claude CLI stream
+   * @param {boolean} force - Force update even if within rate limit interval
+   * @returns {Promise<boolean>} True if a progress update was triggered
+   */
+  const processStreamEvent = async (data, force = false) => {
+    if (!data || typeof data !== 'object') return false;
+    let updated = false;
+    // Pattern 1: assistant event with tool_use containing TodoWrite input
+    if (data.type === 'assistant' && data.message?.content) {
+      const contentItems = Array.isArray(data.message.content) ? data.message.content : [data.message.content];
+      for (const item of contentItems) {
+        if (item.type === 'tool_use' && item.name === 'TodoWrite' && item.input?.todos) {
+          updated = await updateProgress(item.input.todos, force);
+        }
+      }
+    }
+    // Pattern 2: user event with tool_use_result containing newTodos (confirmation)
+    if (data.type === 'user' && data.tool_use_result?.newTodos) {
+      updated = await updateProgress(data.tool_use_result.newTodos, force);
+    }
+    return updated;
+  };
+
+  return {
+    updateProgress,
+    processStreamEvent,
+    getStats,
+    generateSection,
+    get currentTodos() {
+      return state.currentTodos;
+    },
+    get sessionId() {
+      return state.sessionId;
+    },
+    get displayMode() {
+      return state.displayMode;
+    },
+    get commentId() {
+      return state.commentId;
+    },
+  };
+};
+
+/**
+ * Initialize progress monitoring if enabled. Returns null if disabled or missing PR info.
+ * Logs status to the provided log function. Designed to minimize integration lines in claude.lib.mjs.
+ *
+ * @param {Object} argv - Parsed CLI arguments (needs workingSessionLiveProgress)
+ * @param {Object} context - { owner, repo, prNumber, $, log }
+ * @returns {Promise<Object|null>} Progress monitor instance or null
+ */
+export const initProgressMonitoring = async (argv, { owner, repo, prNumber, $, log }) => {
+  const displayMode = normalizeDisplayMode(argv.workingSessionLiveProgress);
+  if (!displayMode) return null;
+  if (!owner || !repo || !prNumber) {
+    await log('⚠️ Live progress monitoring: Disabled - missing PR info', { verbose: true });
+    return null;
+  }
+  const monitor = createProgressMonitor({ owner, repo, prNumber, $, log, verbose: argv.verbose, sessionId: `session-${Date.now()}`, displayMode });
+  await log(`📊 Live progress monitoring: ENABLED (mode: ${displayMode}, session: ${monitor.sessionId})`, { verbose: true });
+  return monitor;
+};
+
+/**
+ * Export utility functions for testing and standalone use
+ */
+export const utils = {
+  generateProgressBar,
+  calculateProgress,
+  formatTodoList,
+  generateProgressSection,
+  CONFIG,
+};

package/src/telegram-accept-invitations.lib.mjs

@@ -116,10 +116,12 @@ function buildProgressMessage(state) {
  * @param {Function} options.isForwardedOrReply - Function to check if message is forwarded/reply
  * @param {Function} options.isGroupChat - Function to check if chat is a group
  * @param {Function} options.isChatAuthorized - Function to check if chat is authorized
+ * @param {Function} [options.isTopicAuthorized] - Function to check if topic is authorized (issue #1100)
+ * @param {Function} [options.buildAuthErrorMessage] - Function to build authorization error message
  * @param {Function} options.addBreadcrumb - Function to add breadcrumbs for monitoring
  */
 export function registerAcceptInvitesCommand(bot, options) {
-  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, addBreadcrumb } = options;
+  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb } = options;
 
   bot.command(/^accept[_-]?invites$/i, async ctx => {
     VERBOSE && console.log('[VERBOSE] /accept_invites command received');
@@ -134,11 +136,11 @@ export function registerAcceptInvitesCommand(bot, options) {
       return await ctx.reply('❌ The /accept_invites command only works in group chats. Please add this bot to a group and make it an admin.', {
         reply_to_message_id: ctx.message.message_id,
       });
-    const chatId = ctx.chat.id;
-    if (!isChatAuthorized(chatId))
-      return await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, {
-        reply_to_message_id: ctx.message.message_id,
-      });
+    const authorize = isTopicAuthorized || (ctx => isChatAuthorized(ctx.chat.id));
+    if (!authorize(ctx)) {
+      const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${ctx.chat.id}) is not authorized.`;
+      return await ctx.reply(errMsg, { reply_to_message_id: ctx.message.message_id });
+    }
 
     const fetchingMessage = await ctx.reply('🔄 Fetching pending GitHub invitations\\.\\.\\.', {
       reply_to_message_id: ctx.message.message_id,

package/src/telegram-bot.mjs

@@ -78,6 +78,12 @@ const config = yargs(hideBin(process.argv))
     alias: 'allowed-chats',
     default: getenv('TELEGRAM_ALLOWED_CHATS', ''),
   })
+  .option('allowedTopics', {
+    type: 'string',
+    description: 'Allowed topic IDs in Links Notation format "chatId topicId" pairs',
+    alias: 'allowed-topics',
+    default: getenv('TELEGRAM_ALLOWED_TOPICS', ''),
+  })
   .option('solveOverrides', {
     type: 'string',
     description: 'Override options for /solve command in lino notation, e.g., "(\n  --auto-continue\n  --attach-logs\n)"',
@@ -154,6 +160,10 @@ if (!BOT_TOKEN) {
 const resolvedAllowedChats = config.allowedChats || getenv('TELEGRAM_ALLOWED_CHATS', '');
 const allowedChats = resolvedAllowedChats ? lino.parseNumericIds(resolvedAllowedChats) : null;
 
+// Parse allowed topics (chatId:topicId pairs in Links Notation)
+const resolvedAllowedTopics = config.allowedTopics || getenv('TELEGRAM_ALLOWED_TOPICS', '');
+const allowedTopics = resolvedAllowedTopics ? lino.parseLinks(resolvedAllowedTopics) : null;
+
 // Parse override options
 const resolvedSolveOverrides = config.solveOverrides || getenv('TELEGRAM_SOLVE_OVERRIDES', '');
 const solveOverrides = resolvedSolveOverrides
@@ -277,6 +287,9 @@ if (config.dryRun) {
   } else {
     console.log('  Allowed chats: All (no restrictions)');
   }
+  if (allowedTopics && allowedTopics.length > 0) {
+    console.log('  Allowed topics:', lino.formatLinks(allowedTopics));
+  }
   console.log('  Commands enabled:', { solve: solveEnabled, hive: hiveEnabled });
   if (solveOverrides.length > 0) {
     console.log('  Solve overrides:', lino.format(solveOverrides));
@@ -319,6 +332,22 @@ function isChatAuthorized(chatId) {
   return _isChatAuthorized(chatId, allowedChats);
 }
 
+// Topic-level authorization (issue #1100): chat-level auth overrides topic-level
+function isTopicAuthorized(ctx) {
+  if (isChatAuthorized(ctx.chat?.id)) return true;
+  if (!allowedTopics || allowedTopics.length === 0) return false;
+  const chatId = ctx.chat?.id;
+  const topicId = ctx.message?.message_thread_id;
+  return allowedTopics.some(pair => pair.source === chatId && pair.target === topicId);
+}
+function buildAuthErrorMessage(ctx) {
+  const chatId = ctx.chat?.id;
+  const topicId = ctx.message?.message_thread_id;
+  let msg = `❌ This chat (ID: ${chatId})`;
+  if (topicId) msg += ` and topic (ID: ${topicId})`;
+  return msg + ' is not authorized.\n\nUse /help to see your chat and topic IDs.';
+}
+
 function isOldMessage(ctx) {
   return _isOldMessage(ctx, BOT_START_TIME, { verbose: VERBOSE });
 }
@@ -621,7 +650,7 @@ bot.command('help', async ctx => {
   const chatId = ctx.chat.id;
   const chatType = ctx.chat.type;
   const chatTitle = ctx.chat.title || 'Private Chat';
-
+  const topicId = ctx.message?.message_thread_id; // Forum topic ID (issue #1100)
   let message = '🤖 *SwarmMindBot Help*\n\n';
 
   // Show stopped status if chat is stopped (issue #1081)
@@ -638,6 +667,7 @@ bot.command('help', async ctx => {
 
   message += '📋 *Diagnostic Information:*\n';
   message += `• Chat ID: \`${chatId}\`\n`;
+  if (topicId) message += `• Topic ID: \`${topicId}\`\n`;
   message += `• Chat Type: ${chatType}\n`;
   message += `• Chat Title: ${chatTitle}\n\n`;
   message += '📝 *Available Commands:*\n\n';
@@ -685,9 +715,10 @@ bot.command('help', async ctx => {
   message += '• `--verbose` or `-v` - Verbose output | `--attach-logs` - Attach logs to PR\n';
   message += '\n💡 *Tip:* Many more options available. See full documentation for complete list.\n';
 
-  if (allowedChats) {
-    message += '\n🔒 *Restricted Mode:* This bot only accepts commands from authorized chats.\n';
-    message += `Authorized: ${isChatAuthorized(chatId) ? '✅ Yes' : '❌ No'}`;
+  if (allowedChats || allowedTopics) {
+    const authorized = isTopicAuthorized(ctx);
+    message += `\n🔒 *Restricted Mode:* Authorized: ${authorized ? '✅ Yes' : '❌ No'}`;
+    if (!authorized && topicId) message += `\n💡 To allow this topic: \`TELEGRAM_ALLOWED_TOPICS="(${chatId} ${topicId})"\``;
   }
 
   message += '\n\n🔧 *Troubleshooting:*\n';
@@ -728,10 +759,11 @@ bot.command('limits', async ctx => {
     return;
   }
 
-  const chatId = ctx.chat.id;
-  if (!isChatAuthorized(chatId)) {
-    VERBOSE && console.log('[VERBOSE] /limits ignored: chat not authorized');
-    await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, { reply_to_message_id: ctx.message.message_id });
+  if (!isTopicAuthorized(ctx)) {
+    if (VERBOSE) {
+      console.log('[VERBOSE] /limits ignored: not authorized');
+    }
+    await ctx.reply(buildAuthErrorMessage(ctx), { reply_to_message_id: ctx.message.message_id });
     return;
   }
 
@@ -768,8 +800,7 @@ bot.command('version', async ctx => {
   });
   if (isOldMessage(ctx) || isForwardedOrReply(ctx)) return;
   if (!_isGroupChat(ctx)) return await ctx.reply('❌ The /version command only works in group chats. Please add this bot to a group and make it an admin.', { reply_to_message_id: ctx.message.message_id });
-  const chatId = ctx.chat.id;
-  if (!isChatAuthorized(chatId)) return await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, { reply_to_message_id: ctx.message.message_id });
+  if (!isTopicAuthorized(ctx)) return await ctx.reply(buildAuthErrorMessage(ctx), { reply_to_message_id: ctx.message.message_id });
   const fetchingMessage = await ctx.reply('🔄 Gathering version information...', {
     reply_to_message_id: ctx.message.message_id,
   });
@@ -778,48 +809,18 @@ bot.command('version', async ctx => {
   await ctx.telegram.editMessageText(fetchingMessage.chat.id, fetchingMessage.message_id, undefined, '🤖 *Version Information*\n\n' + formatVersionMessage(result.versions), { parse_mode: 'Markdown' });
 });
 
-// Register /accept_invites command from separate module
-// This keeps telegram-bot.mjs under the 1500 line limit
+// Register external command modules (keeps telegram-bot.mjs under line limit)
 const { registerAcceptInvitesCommand } = await import('./telegram-accept-invitations.lib.mjs');
-registerAcceptInvitesCommand(bot, {
-  VERBOSE,
-  isOldMessage,
-  isForwardedOrReply,
-  isGroupChat: _isGroupChat,
-  isChatAuthorized,
-  addBreadcrumb,
-});
-
-// Register /merge command from separate module (experimental, see issue #1143)
+const sharedCommandOpts = { VERBOSE, isOldMessage, isForwardedOrReply, isGroupChat: _isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, isChatStopped, getStoppedChatRejectMessage };
+registerAcceptInvitesCommand(bot, sharedCommandOpts);
 const { registerMergeCommand } = await import('./telegram-merge-command.lib.mjs');
-registerMergeCommand(bot, {
-  VERBOSE,
-  isOldMessage,
-  isForwardedOrReply,
-  isGroupChat: _isGroupChat,
-  isChatAuthorized,
-  addBreadcrumb,
-  isChatStopped,
-  getStoppedChatRejectMessage,
-});
-
-// Register /solve_queue command from separate module (issue #1232)
+registerMergeCommand(bot, sharedCommandOpts);
 const { registerSolveQueueCommand } = await import('./telegram-solve-queue-command.lib.mjs');
-const { handleSolveQueueCommand } = registerSolveQueueCommand(bot, {
-  VERBOSE,
-  isOldMessage,
-  isForwardedOrReply,
-  isGroupChat: _isGroupChat,
-  isChatAuthorized,
-  addBreadcrumb,
-  getSolveQueue,
-});
+const { handleSolveQueueCommand } = registerSolveQueueCommand(bot, { ...sharedCommandOpts, getSolveQueue });
 
 // 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');
-  }
+  VERBOSE && console.log('[VERBOSE] /solve command received');
 
   // Add breadcrumb for error tracking
   await addBreadcrumb({
@@ -871,16 +872,16 @@ async function handleSolveCommand(ctx) {
     return;
   }
 
-  const chatId = ctx.chat.id;
-  if (!isChatAuthorized(chatId)) {
+  if (!isTopicAuthorized(ctx)) {
     if (VERBOSE) {
-      console.log('[VERBOSE] /solve ignored: chat not authorized');
+      console.log('[VERBOSE] /solve ignored: not authorized');
     }
-    await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, { reply_to_message_id: ctx.message.message_id });
+    await ctx.reply(buildAuthErrorMessage(ctx), { reply_to_message_id: ctx.message.message_id });
     return;
   }
 
   // Check if chat is stopped (issue #1081) - reject with same style as queue rejected mode
+  const chatId = ctx.chat.id;
   if (isChatStopped(chatId)) {
     VERBOSE && console.log('[VERBOSE] /solve rejected: chat is stopped');
     await safeReply(ctx, getStoppedChatRejectMessage(chatId, 'Solve'), { reply_to_message_id: ctx.message.message_id });
@@ -1017,7 +1018,7 @@ async function handleSolveCommand(ctx) {
   const existingItem = solveQueue.findByUrl(normalizedUrl);
   if (existingItem) {
     const statusText = existingItem.status === 'starting' || existingItem.status === 'started' ? 'being processed' : 'already in the queue';
-    await safeReply(ctx, `❌ This URL is ${statusText}.\n\nURL: ${escapeMarkdown(normalizedUrl)}\nStatus: ${existingItem.status}\n\n💡 Use /solve\\_queue to check the queue status.`, { reply_to_message_id: ctx.message.message_id });
+    await safeReply(ctx, `❌ This URL is ${statusText}.\n\nURL: ${escapeMarkdown(normalizedUrl)}\nStatus: ${existingItem.status}\n\n💡 Use /solve_queue to check the queue status.`, { reply_to_message_id: ctx.message.message_id });
     return;
   }
 
@@ -1099,16 +1100,16 @@ async function handleHiveCommand(ctx) {
     return;
   }
 
-  const chatId = ctx.chat.id;
-  if (!isChatAuthorized(chatId)) {
+  if (!isTopicAuthorized(ctx)) {
     if (VERBOSE) {
-      console.log('[VERBOSE] /hive ignored: chat not authorized');
+      console.log('[VERBOSE] /hive ignored: not authorized');
     }
-    await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, { reply_to_message_id: ctx.message.message_id });
+    await ctx.reply(buildAuthErrorMessage(ctx), { reply_to_message_id: ctx.message.message_id });
     return;
   }
 
   // Check if chat is stopped (issue #1081) - reject with same style as queue rejected mode
+  const chatId = ctx.chat.id;
   if (isChatStopped(chatId)) {
     VERBOSE && console.log('[VERBOSE] /hive rejected: chat is stopped');
     await safeReply(ctx, getStoppedChatRejectMessage(chatId, 'Hive'), { reply_to_message_id: ctx.message.message_id });
@@ -1201,12 +1202,10 @@ async function handleHiveCommand(ctx) {
 
 bot.command(/^hive$/i, handleHiveCommand);
 
-// Register commands from separate modules (keeps telegram-bot.mjs under line limit)
 const { registerTopCommand } = await import('./telegram-top-command.lib.mjs');
 const { registerStartStopCommands } = await import('./telegram-start-stop-command.lib.mjs');
-const commandOptions = { VERBOSE, isOldMessage, isForwardedOrReply, isGroupChat: _isGroupChat, isChatAuthorized };
-registerTopCommand(bot, commandOptions);
-registerStartStopCommands(bot, commandOptions); // issue #1081
+registerTopCommand(bot, sharedCommandOpts);
+registerStartStopCommands(bot, sharedCommandOpts);
 
 // Add message listener for verbose debugging
 if (VERBOSE) {
@@ -1389,6 +1388,9 @@ if (allowedChats && allowedChats.length > 0) {
 } else {
   console.log('Allowed chats: All (no restrictions)');
 }
+if (allowedTopics && allowedTopics.length > 0) {
+  console.log('Allowed topics (lino):', lino.formatLinks(allowedTopics));
+}
 console.log('Commands enabled:', { solve: solveEnabled, hive: hiveEnabled });
 if (solveOverrides.length > 0) console.log('Solve overrides (lino):', lino.format(solveOverrides));
 if (hiveOverrides.length > 0) console.log('Hive overrides (lino):', lino.format(hiveOverrides));

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

@@ -130,10 +130,14 @@ function formatUserError(error, verbose) {
  * @param {Function} options.isForwardedOrReply - Function to check if message is forwarded/reply
  * @param {Function} options.isGroupChat - Function to check if chat is a group
  * @param {Function} options.isChatAuthorized - Function to check if chat is authorized
+ * @param {Function} [options.isTopicAuthorized] - Function to check if topic is authorized (issue #1100)
+ * @param {Function} [options.buildAuthErrorMessage] - Function to build authorization error message
  * @param {Function} options.addBreadcrumb - Function to add breadcrumbs for monitoring
+ * @param {Function} [options.isChatStopped] - Function to check if chat is stopped (issue #1081)
+ * @param {Function} [options.getStoppedChatRejectMessage] - Function to get stopped chat rejection message
  */
 export function registerMergeCommand(bot, options) {
-  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, addBreadcrumb, isChatStopped, getStoppedChatRejectMessage } = options;
+  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, isChatStopped, getStoppedChatRejectMessage } = options;
 
   bot.command(/^merge$/i, async ctx => {
     VERBOSE && console.log('[VERBOSE] /merge command received');
@@ -154,13 +158,14 @@ export function registerMergeCommand(bot, options) {
       });
     }
 
-    const chatId = ctx.chat.id;
-    if (!isChatAuthorized(chatId)) {
-      return await ctx.reply(`This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, {
-        reply_to_message_id: ctx.message.message_id,
-      });
+    const authorize = isTopicAuthorized || (ctx => isChatAuthorized(ctx.chat.id));
+    if (!authorize(ctx)) {
+      const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `This chat (ID: ${ctx.chat.id}) is not authorized.`;
+      return await ctx.reply(errMsg, { reply_to_message_id: ctx.message.message_id });
     }
 
+    const chatId = ctx.chat.id;
+
     // Check if chat is stopped (issue #1081) - reject with same style as queue rejected mode
     if (isChatStopped && isChatStopped(chatId)) {
       VERBOSE && console.log('[VERBOSE] /merge rejected: chat is stopped');

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

@@ -22,12 +22,14 @@
  * @param {Function} options.isForwardedOrReply - Function to check if message is forwarded/reply
  * @param {Function} options.isGroupChat - Function to check if chat is a group
  * @param {Function} options.isChatAuthorized - Function to check if chat is authorized
+ * @param {Function} [options.isTopicAuthorized] - Function to check if topic is authorized (issue #1100)
+ * @param {Function} [options.buildAuthErrorMessage] - Function to build authorization error message
  * @param {Function} options.addBreadcrumb - Function to add breadcrumbs for monitoring
  * @param {Function} options.getSolveQueue - Function to get the solve queue instance
  * @returns {{ handleSolveQueueCommand: Function }} The command handler for use in text fallback
  */
 export function registerSolveQueueCommand(bot, options) {
-  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, addBreadcrumb, getSolveQueue } = options;
+  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, getSolveQueue } = options;
 
   async function handleSolveQueueCommand(ctx) {
     VERBOSE && console.log('[VERBOSE] /solve_queue command received');
@@ -59,12 +61,11 @@ export function registerSolveQueueCommand(bot, options) {
       return;
     }
 
-    const chatId = ctx.chat.id;
-    if (!isChatAuthorized(chatId)) {
-      VERBOSE && console.log('[VERBOSE] /solve_queue ignored: chat not authorized');
-      await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot. Please contact the bot administrator.`, {
-        reply_to_message_id: ctx.message.message_id,
-      });
+    const authorize = isTopicAuthorized || (ctx => isChatAuthorized(ctx.chat.id));
+    if (!authorize(ctx)) {
+      VERBOSE && console.log('[VERBOSE] /solve_queue ignored: not authorized');
+      const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${ctx.chat.id}) is not authorized.`;
+      await ctx.reply(errMsg, { reply_to_message_id: ctx.message.message_id });
       return;
     }
 

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

@@ -51,9 +51,11 @@ async function captureTopOutput(chatId) {
  * @param {Function} options.isForwardedOrReply - Function to check if message is forwarded/reply
  * @param {Function} options.isGroupChat - Function to check if chat is a group
  * @param {Function} options.isChatAuthorized - Function to check if chat is authorized
+ * @param {Function} [options.isTopicAuthorized] - Function to check if topic is authorized (issue #1100)
+ * @param {Function} [options.buildAuthErrorMessage] - Function to build authorization error message
  */
 export function registerTopCommand(bot, options) {
-  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized } = options;
+  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage } = options;
 
   // /top command - show system top output in an auto-updating message (EXPERIMENTAL)
   // Only accessible by chat owner
@@ -89,17 +91,20 @@ export function registerTopCommand(bot, options) {
       return;
     }
 
-    const chatId = ctx.chat.id;
-    if (!isChatAuthorized(chatId)) {
+    const authorize = isTopicAuthorized || (ctx => isChatAuthorized(ctx.chat.id));
+    if (!authorize(ctx)) {
       if (VERBOSE) {
-        console.log('[VERBOSE] /top ignored: chat not authorized');
+        console.log('[VERBOSE] /top ignored: not authorized');
       }
-      await ctx.reply(`❌ This chat (ID: ${chatId}) is not authorized to use this bot.`, {
+      const errMsg = buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${ctx.chat.id}) is not authorized.`;
+      await ctx.reply(errMsg, {
         reply_to_message_id: ctx.message.message_id,
       });
       return;
     }
 
+    const chatId = ctx.chat.id;
+
     // Check if user is chat owner
     try {
       const chatMember = await ctx.telegram.getChatMember(chatId, ctx.from.id);