t1467: recycle stale pulse process when underfilled

[marcusquinn]

Summary

• Add PULSE_UNDERFILLED_STALE_RECOVERY_TIMEOUT (default 900s) to pulse-wrapper.sh.
• Extend check_dedup() to recycle a running pulse process early when it is old enough and worker utilization is under target.
• Keep existing hard stale-threshold behavior unchanged; this only accelerates recovery in underfilled conditions.

Verification

• shellcheck .agents/scripts/pulse-wrapper.sh
• bash -n .agents/scripts/pulse-wrapper.sh

Closes #4325
Refs #4311

Summary by CodeRabbit

• New Features
  • Implemented intelligent automatic background process recovery that continuously monitors system resource availability and intelligently recycles underutilized or stale processes when capacity becomes available, ensuring optimal performance. This enhancement significantly improves system stability, responsiveness, operational efficiency, and resource utilization across all operations. Also includes configurable timeout settings for customizing recovery behavior to match workload needs.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7d944fb2-0c77-4b84-864c-2deefb39ccef

📥 Commits

Reviewing files that changed from the base of the PR and between 04ede67 and 8ac2da0.

📒 Files selected for processing (1)

• .agents/scripts/pulse-wrapper.sh

---

Walkthrough

This PR adds a stale process auto-recovery mechanism to the pulse dedup logic. It introduces a new configurable timeout (PULSE_UNDERFILLED_STALE_RECOVERY_TIMEOUT) and implements an early recycling pathway that detects long-running pulse processes with insufficient active workers, triggering their controlled termination and PID cleanup.

Changes

Cohort / File(s)	Summary
Pulse Dedup Recovery .agents/scripts/pulse-wrapper.sh	Adds PULSE_UNDERFILLED_STALE_RECOVERY_TIMEOUT configuration parameter with numeric validation. Inserts new early-recycle branch in check_dedup that monitors pulse runtime and active worker count; triggers forced termination and PID cleanup when pulse runs longer than timeout threshold with insufficient active workers relative to max target. Preserves existing dedup logic flow.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• t1454: harden pulse pre-run stages and queue accounting #4293: Modifies pulse-wrapper.sh dedup and worker-checking paths with repo-aware worker checks and gating logic
• t1455: add adaptive pulse queue-governor and strict worker counting #4218: Adjusts active worker counting and usage within pulse-wrapper.sh, adding adaptive queue governor state
• t1425, t1426, t1427: Fix pulse-wrapper zombie accumulation and blocking #4020: Changes PID handling and dedup/check_dedup logic in pulse-wrapper.sh to address race conditions

Suggested labels

bug

Poem

🔄 A stale pulse sleeps too long,

When workers fade and timeout songs,

The wrapper wakes and sets it free—

Early recycle, swift and clean! 🧹

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bugfix/pulse-stale-underfill-recovery

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔍 Code Quality Report

�[0;35m[MONITOR]�[0m Code Review Monitoring Report

�[0;34m[INFO]�[0m Latest Quality Status:
SonarCloud: 0 bugs, 0 vulnerabilities, 411 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Fri Mar 13 02:34:38 UTC 2026: Code review monitoring started
Fri Mar 13 02:34:38 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 411

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 411
• VULNERABILITIES: 0

Generated on: Fri Mar 13 02:34:40 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud