@link-assistant/hive-mind 1.44.0 → 1.45.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @link-assistant/hive-mind
 
+## 1.45.1
+
+### Patch Changes
+
+- 003c5ca: Fix premature finish signaling and leaked child processes (Issue #1516)
+  - Kill entire process group on stream timeout using negative PID, preventing leaked /bin/sh child processes from continuing to make commits after completion
+  - Move .gitkeep cleanup to after all completion signals (log upload, "Ready to merge" comment) so no new commits appear after the system reports "session ended"
+  - drainHandles now reports surviving child processes as errors instead of silently killing them, so root causes are investigated rather than hidden
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.44.0",
+  "version": "1.45.1",
   "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
@@ -854,22 +852,22 @@ export const executeClaudeCommand = async params => {
       let lastEventTime = null;
       let activityTimeoutId = null;
       let isActivityTimeout = false;
-      // Issue #1510: Separate SIGTERM (graceful) and SIGKILL (force) phases to allow
-      // capturing final output from the process during graceful shutdown
+      // Issue #1516: Kill process group (-pid) so leaked /bin/sh children don't survive
+      // prettier-ignore
+      const killProcessTree = signal => { try { const pid = execCommand.pid || execCommand._pid; if (pid) { process.kill(-pid, signal); return; } } catch { /* not group leader */ } execCommand.kill(signal); };
       const forceExitOnTimeout = async () => {
         if (forceExitTriggered) return;
         forceExitTriggered = true;
-        await log(`⚠️ Stream timeout — sending SIGTERM for graceful shutdown (Issue #1280, #1510)`, { verbose: true });
+        await log(`⚠️ Stream timeout — sending SIGTERM for graceful shutdown (Issue #1280, #1510, #1516)`, { verbose: true });
         try {
           if (execCommand.kill) {
-            execCommand.kill('SIGTERM');
+            killProcessTree('SIGTERM');
             // Issue #1346/#1510: Follow up with SIGKILL after 5s if still alive
-            // Increased from 2s to 5s to give more time for final output capture
             const t = setTimeout(() => {
               try {
                 if (!execCommand.result?.code) {
-                  log(`⚠️ Process did not exit after SIGTERM, sending SIGKILL`, { verbose: true });
-                  execCommand.kill('SIGKILL');
+                  log(`⚠️ Process tree did not exit after SIGTERM, sending SIGKILL (Issue #1516)`, { verbose: true });
+                  killProcessTree('SIGKILL');
                 }
               } catch {
                 /* exited */
@@ -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/exit-handler.lib.mjs

@@ -121,12 +121,30 @@ const drainHandles = async () => {
     // undici may not be available in all Node versions — safe to ignore
   }
 
-  // 3. Unref surviving child processes from command-stream.
-  //    These are typically already-exited but their OS handle entry lingers.
+  // 3. Detect surviving child processes from command-stream.
+  //    Issue #1516: Surviving ChildProcess handles indicate a bug — a leaked /bin/sh
+  //    child can continue executing (making commits, pushing to GitHub) after we've
+  //    declared completion. Instead of silently killing them (which hides root causes),
+  //    we log an error so each occurrence is investigated and the root cause is fixed.
+  //    The process group kill in claude.lib.mjs (killProcessTree) should have already
+  //    terminated all children; if any survive, that's a bug we need to know about.
   try {
     for (const handle of process._getActiveHandles()) {
-      if (handle?.constructor?.name === 'ChildProcess' && typeof handle.unref === 'function') {
-        handle.unref();
+      if (handle?.constructor?.name === 'ChildProcess') {
+        // Issue #1516: Report surviving child processes as errors instead of killing them.
+        // This surfaces the root cause for investigation rather than hiding it.
+        const detail = [handle.pid != null ? `pid=${handle.pid}` : null, handle.spawnfile ? `file=${handle.spawnfile}` : null, handle.killed ? 'killed=true' : 'killed=false'].filter(Boolean).join(', ');
+        const errorMsg = `❌ ERROR: Surviving ChildProcess detected at exit (${detail}). This indicates a leaked process that was not properly terminated. Investigate the root cause — do NOT suppress this error by killing the process. (Issue #1516)`;
+        if (logFunction) {
+          await logFunction(errorMsg, { level: 'error' });
+        } else {
+          console.error(errorMsg);
+        }
+        // Still unref so Node.js can exit, but do NOT kill — let the OS process
+        // continue so its effects are visible and the root cause can be diagnosed.
+        if (typeof handle.unref === 'function') {
+          handle.unref();
+        }
       }
     }
   } catch {

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.mjs

@@ -1175,8 +1175,7 @@ try {
   const autoRestartEnabled = argv['autoRestartOnUncommittedChanges'] !== false;
   const shouldRestart = await checkForUncommittedChanges(tempDir, owner, repo, branchName, $, log, shouldAutoCommit, autoRestartEnabled);
 
-  // Remove initial commit file (CLAUDE.md or .gitkeep) now that Claude command has finished
-  await cleanupClaudeFile(tempDir, branchName, claudeCommitHash, argv);
+  // Issue #1516: cleanupClaudeFile() moved to after completion signals (before endWorkSession)
 
   // Show summary of session and log file
   await showSessionSummary(sessionId, limitReached, argv, issueUrl, tempDir, shouldAttachLogs);
@@ -1442,6 +1441,9 @@ try {
     }
   }
 
+  // Issue #1516: Cleanup after all signals (was before verifyResults, caused premature commits)
+  await cleanupClaudeFile(tempDir, branchName, claudeCommitHash, argv);
+
   // End work session using the new module
   await endWorkSession({
     isContinueMode,

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,
+};