feat: add experimental live progress monitoring for work sessions

[konard]

📊 Experimental Status Monitoring

This PR implements live progress monitoring for work sessions by tracking TODO list updates and reflecting them in pull request descriptions.

🎯 Summary

Implements issue #936 - adds experimental status monitoring that uses TODO list updates to provide real-time progress tracking in PR descriptions.

✨ Features Implemented

1. New CLI Flag: --working-session-live-progress

• Available in both solve and hive commands
• Enables automatic PR description updates based on TODO list changes
• Marked as [EXPERIMENTAL] and requires --interactive-mode to be enabled
• Defaults to false (opt-in feature)

2. Progress Monitoring Module (src/solve.progress-monitoring.lib.mjs)

• Progress Tracking: Monitors TodoWrite tool calls and tracks task completion
• Visual Progress Bar: Generates ASCII progress bars (e.g., █████░░░░░ 50%)
• Live PR Updates: Automatically updates PR description with dedicated progress section
• Rate Limiting: Prevents API abuse with 10-second minimum interval between updates
• Session Support: Optionally tracks progress per work session
• Smart Formatting:
  • Calculates completion percentage
  • Shows task breakdown (completed/in-progress/pending)
  • Collapsible task list in PR description
  • HTML comment markers for section replacement

3. Interactive Mode Integration (src/interactive-mode.lib.mjs)

• Automatically detects TodoWrite tool usage
• Triggers progress updates without blocking comment posting
• Graceful error handling for progress update failures
• Verbose logging support for debugging

4. Option Forwarding (src/hive.mjs)

• Properly forwards --working-session-live-progress from hive to solve
• Consistent with other experimental options (e.g., --interactive-mode)

📋 Implementation Details

Files Modified:

• src/solve.config.lib.mjs - Added CLI option definition
• src/hive.config.lib.mjs - Added CLI option definition
• src/hive.mjs - Added option forwarding logic
• src/interactive-mode.lib.mjs - Integrated progress monitoring

Files Created:

• src/solve.progress-monitoring.lib.mjs - Core progress monitoring logic (308 lines)
• tests/test-working-session-live-progress.mjs - Comprehensive test suite (29 tests)
• .changeset/working-session-live-progress.md - Changeset for release

🧪 Testing

Created comprehensive test suite with 29 passing tests covering:

• ✅ Progress calculation and statistics
• ✅ Progress bar generation (0%, 50%, 100%)
• ✅ TODO list formatting with status icons
• ✅ Progress section markdown generation
• ✅ CLI configuration in solve and hive
• ✅ Option forwarding from hive to solve
• ✅ Interactive mode integration
• ✅ Module structure and configuration

Run tests:

node tests/test-working-session-live-progress.mjs

📖 Usage

Enable progress monitoring:

# With solve command
solve https://github.com/owner/repo/issues/123 --interactive-mode --working-session-live-progress

# With hive command
hive https://github.com/owner/repo --interactive-mode --working-session-live-progress

What happens:

1. When Claude uses the TodoWrite tool, the progress monitor detects it
2. Progress statistics are calculated (completed, in-progress, pending tasks)
3. A dedicated section is added/updated in the PR description with:
   • Current completion percentage
   • Visual progress bar
   • Task breakdown stats
   • Collapsible full task list

Example progress section:

## 📊 Live Progress Monitor

**Session:** session-1234567890
**Last Updated:** 2025-12-16T19:45:23.456Z

### Progress: 65% Complete

███████████████████░░░░░░░░░░░ 65%

**Tasks:** 13/20 completed · 1 in progress · 6 pending

<details>
<summary>📋 Task List (20 total)</summary>

- [x] Read and analyze requirements
- [x] Explore codebase structure
- [~] Implement core functionality
- [ ] Write tests
...
</details>

🔧 Technical Architecture

Progress Section Management:

• Uses HTML comment markers for section boundaries:
  • <!-- LIVE-PROGRESS-START -->
  • <!-- LIVE-PROGRESS-END -->
• Replaces entire section on each update (idempotent)
• Appends new section if not present

Rate Limiting Strategy:

• Minimum 10-second interval between PR description updates
• Prevents GitHub API rate limiting issues
• Non-blocking design (doesn't slow down tool execution)

Integration Points:

• Hooks into handleToolUse in interactive-mode.lib.mjs
• Triggered only when toolName === 'TodoWrite'
• Updates happen asynchronously after comment posting

🚀 Future Enhancements

Potential improvements mentioned in issue #936:

• Display progress in work session start comments (alternative/additional location)
• Multiple progress sections per PR (one per work session)
• Progress history tracking
• Customizable progress bar styles
• Export progress data for analytics

✅ Quality Assurance

• All 29 tests passing
• No syntax errors in JavaScript modules
• Follows existing code patterns from similar features
• Consistent with CLI option naming conventions
• Changeset created for version tracking
• Comprehensive documentation in code comments

📚 Related Work

This feature builds on:

• Interactive mode infrastructure (PR #XXX)
• TodoWrite tool integration
• PR description management patterns from solve.results.lib.mjs

🔗 Fixes

Fixes #936

---

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $2.892403 USD
• Calculated by Anthropic: $2.759294 USD
• Difference: $-0.133109 (-4.60%)
  📎 Log file uploaded as GitHub Gist (1346KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

Resolve conflicts, and make sure:

[2025-12-16T18:54:06.246Z] [INFO] {
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "tool_use_id": "toolu_014SnZ1JE7jEoaDb2t5bhyiK",
        "type": "tool_result",
        "content": "Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable"
      }
    ]
  },
  "parent_tool_use_id": null,
  "session_id": "5cd6dd8c-2069-4c12-9303-7ef379288c29",
  "uuid": "4cb0e405-fdde-41b2-a9b0-eb971470a9ef",
  "tool_use_result": {
    "oldTodos": [
      {
        "content": "Read and analyze issue #936 requirements and PR description",
        "status": "completed",
        "activeForm": "Reading and analyzing issue #936 requirements"
      },
      {
        "content": "Explore codebase to understand TODO list and PR description management",
        "status": "completed",
        "activeForm": "Exploring codebase structure"
      },
      {
        "content": "Design the implementation approach for live progress monitoring",
        "status": "completed",
        "activeForm": "Designing implementation approach"
      },
      {
        "content": "Read contributing guidelines and code style from merged PRs",
        "status": "completed",
        "activeForm": "Reading contributing guidelines"
      },
      {
        "content": "Implement progress monitoring module (solve.progress-monitoring.lib.mjs)",
        "status": "in_progress",
        "activeForm": "Implementing progress monitoring module"
      },
      {
        "content": "Add --working-session-live-progress CLI flag to solve.config.lib.mjs",
        "status": "pending",
        "activeForm": "Adding CLI flag configuration"
      },
      {
        "content": "Add --working-session-live-progress CLI flag to hive.config.lib.mjs",
        "status": "pending",
        "activeForm": "Adding CLI flag to hive config"
      },
      {
        "content": "Integrate progress monitoring into interactive-mode.lib.mjs",
        "status": "pending",
        "activeForm": "Integrating progress monitoring into interactive mode"
      },
      {
        "content": "Forward option from hive to solve command in hive.mjs",
        "status": "pending",
        "activeForm": "Forwarding option from hive to solve"
      },
      {
        "content": "Write comprehensive tests for progress monitoring functionality",
        "status": "pending",
        "activeForm": "Writing comprehensive tests"
      },
      {
        "content": "Test the implementation with real TODO list updates",
        "status": "pending",
        "activeForm": "Testing implementation"
      },
      {
        "content": "Run local CI checks (npm run lint)",
        "status": "pending",
        "activeForm": "Running local CI checks"
      },
      {
        "content": "Update PR description with implementation details",
        "status": "pending",
        "activeForm": "Updating PR description"
      },
      {
        "content": "Add changeset for the new feature",
        "status": "pending",
        "activeForm": "Adding changeset"
      },
      {
        "content": "Commit and push changes to issue-936-879ade8d882b branch",
        "status": "pending",
        "activeForm": "Committing and pushing changes"
      },
      {
        "content": "Mark PR #939 as ready for review",
        "status": "pending",
        "activeForm": "Marking PR as ready for review"
      }
    ],
    "newTodos": [
      {
        "content": "Read and analyze issue #936 requirements and PR description",
        "status": "completed",
        "activeForm": "Reading and analyzing issue #936 requirements"
      },
      {
        "content": "Explore codebase to understand TODO list and PR description management",
        "status": "completed",
        "activeForm": "Exploring codebase structure"
      },
      {
        "content": "Design the implementation approach for live progress monitoring",
        "status": "completed",
        "activeForm": "Designing implementation approach"
      },
      {
        "content": "Read contributing guidelines and code style from merged PRs",
        "status": "completed",
        "activeForm": "Reading contributing guidelines"
      },
      {
        "content": "Implement progress monitoring module (solve.progress-monitoring.lib.mjs)",
        "status": "completed",
        "activeForm": "Implementing progress monitoring module"
      },
      {
        "content": "Add --working-session-live-progress CLI flag to solve.config.lib.mjs",
        "status": "in_progress",
        "activeForm": "Adding CLI flag configuration"
      },
      {
        "content": "Add --working-session-live-progress CLI flag to hive.config.lib.mjs",
        "status": "pending",
        "activeForm": "Adding CLI flag to hive config"
      },
      {
        "content": "Integrate progress monitoring into interactive-mode.lib.mjs",
        "status": "pending",
        "activeForm": "Integrating progress monitoring into interactive mode"
      },
      {
        "content": "Forward option from hive to solve command in hive.mjs",
        "status": "pending",
        "activeForm": "Forwarding option from hive to solve"
      },
      {
        "content": "Write comprehensive tests for progress monitoring functionality",
        "status": "pending",
        "activeForm": "Writing comprehensive tests"
      },
      {
        "content": "Test the implementation with real TODO list updates",
        "status": "pending",
        "activeForm": "Testing implementation"
      },
      {
        "content": "Run local CI checks (npm run lint)",
        "status": "pending",
        "activeForm": "Running local CI checks"
      },
      {
        "content": "Update PR description with implementation details",
        "status": "pending",
        "activeForm": "Updating PR description"
      },
      {
        "content": "Add changeset for the new feature",
        "status": "pending",
        "activeForm": "Adding changeset"
      },
      {
        "content": "Commit and push changes to issue-936-879ade8d882b branch",
        "status": "pending",
        "activeForm": "Committing and pushing changes"
      },
      {
        "content": "Mark PR #939 as ready for review",
        "status": "pending",
        "activeForm": "Marking PR as ready for review"
      }
    ]
  }
}

Double check that we actually parse todo changes like these from Claude Code CLI output. And if --working-session-live-progress is enabled we clearly mark even first working session as separate comment, to keep all progress for all working sessions separately. And we should double check that each start and restart of each session is clearly marked as separate GitHub comment.

Also if option is not disabled we should not break anything that was working before.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-01-11T01:44:38.946Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

Work Session Summary

This session resolved the merge conflicts and completed the live progress monitoring integration:

Changes Made

1. Resolved merge conflicts in:

   • src/hive.mjs
   • src/interactive-mode.lib.mjs
   • src/solve.config.lib.mjs

2. Fixed lint error: Removed unused idx parameter in solve.progress-monitoring.lib.mjs

3. Completed integration: The --working-session-live-progress flag now properly passes to createInteractiveHandler with:

   • enableProgressMonitoring boolean flag
   • sessionId unique work session identifier

4. Added flag forwarding: hive.mjs now forwards --working-session-live-progress to solve command

5. Updated tests: Removed obsolete test assertions for old flag variable pattern

How It Works

When --working-session-live-progress is used with --interactive-mode:

1. A unique sessionId is generated (e.g., session-1736563200000)
2. The progress monitor is initialized with this session ID
3. TODO list updates from Claude trigger progressMonitor.updateProgress()
4. The PR description is updated with a live progress section showing:
   • Progress bar visualization
   • Task completion stats (completed/total)
   • Collapsible task list with status indicators

CI Status

✅ All checks passing

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $10.477737 USD
• Calculated by Anthropic: $6.566422 USD
• Difference: $-3.911315 (-37.33%)
  📎 Log file uploaded as GitHub Gist (1318KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.