t1454: harden pulse pre-run stages and queue accounting

[marcusquinn]

Summary

• Add bounded pre-run stage execution in pulse-wrapper.sh so cleanup/prefetch cannot hang indefinitely before run_pulse watchdogs engage.
• Improve queue visibility by replacing narrow fixed windows with configurable 200-item limits across prefetch and runnable-candidate counting paths.
• Make queued-worker and launch-validation checks repo-aware (repo + issue) to avoid cross-repo issue-number collisions.

Verification

• shellcheck .agents/scripts/pulse-wrapper.sh
• bash -n .agents/scripts/pulse-wrapper.sh
• Sourced helper smoke tests for timeout and repo-scoped worker matching logic

Closes #4261
Fixes #4260
Resolves #4262

Summary by CodeRabbit

• Improvements

  • Added timeout protection to prevent tasks from hanging indefinitely
  • Enhanced queue management with adaptive dispatch logic
  • Improved process availability tracking

• Configuration

  • Made previously hard-coded limits now configurable for better resource control

[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]

Warning

Rate limit exceeded

@marcusquinn has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 23 minutes and 13 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c2de075e-fd00-4265-be7d-4e20cc54642a

📥 Commits

Reviewing files that changed from the base of the PR and between 07ce68a and 67652fd.

📒 Files selected for processing (1)

• .agents/scripts/pulse-wrapper.sh

Walkthrough

This PR modifies .agents/scripts/pulse-wrapper.sh to introduce timeout-aware stage execution, dynamic per-repo/issue limits, and stricter worker-detection logic. It adds three new helper functions: run_stage_with_timeout() for bounded stage execution with process-tree cleanup, get_repo_path_by_slug() for repository path resolution, and has_worker_for_repo_issue() for repo-scoped worker existence checks. Existing stage invocations, prefetch logic, queue governance, and worker validation are refactored to use these utilities and dynamic limit constants.

Changes

Cohort / File(s)	Summary
New Helper Functions & Timeout Infrastructure .agents/scripts/pulse-wrapper.sh	Added run_stage_with_timeout() to execute stages with wall-clock timeout, process tree termination on timeout, and status-code handling. Added get_repo_path_by_slug() to resolve repository paths from REPOS_JSON. Added has_worker_for_repo_issue() for per-repo/issue worker existence checks via process scanning, replacing pgrep-based issue-number-only matching.
Stage Invocation & Prefetch Refactoring .agents/scripts/pulse-wrapper.sh	Wrapped cleanup stages (cleanup_orphans, cleanup_worktrees, cleanup_stashes) and prefetch_state with run_stage_with_timeout() and PRE_RUN_STAGE_TIMEOUT. Replaced hard-coded API limits in prefetch_state with dynamic limit constants (PULSE_PREFETCH_PR_LIMIT, PULSE_PREFETCH_ISSUE_LIMIT). Updated prefetch to abort on failure with fallback behavior.
Worker Detection & Launch Validation .agents/scripts/pulse-wrapper.sh	Replaced pgrep issue-number-only checks in worker-launch validation and queued-without-worker detection with has_worker_for_repo_issue() calls, ensuring repo-scoped matching and eliminating cross-repo issue-number collisions.
Adaptive Queue Governor & Per-Cycle Metrics .agents/scripts/pulse-wrapper.sh	Enhanced append_adaptive_queue_governor() to compute per-repo PR/issue readiness and backlog metrics via GH queries, persist deltas to QUEUE_METRICS_FILE, and output adaptive dispatch plan based on aggregated per-cycle state.
Configuration & Constants .agents/scripts/pulse-wrapper.sh	Added PRE_RUN_STAGE_TIMEOUT, PULSE_PREFETCH_PR_LIMIT, PULSE_PREFETCH_ISSUE_LIMIT, PULSE_RUNNABLE_PR_LIMIT, PULSE_RUNNABLE_ISSUE_LIMIT, PULSE_QUEUED_SCAN_LIMIT constants with defaults and validation via _validate_int(). Enhanced configuration validation section.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• t1452: enforce pulse dispatch launch validation and CLI guardrails #4193 — Modifies pulse worker-launch validation logic; the main PR replaces pgrep checks with has_worker_for_repo_issue() helper that directly implements per-repo/issue worker detection.
• t1455: add adaptive pulse queue-governor and strict worker counting #4218 — Adds adaptive queue governor and QUEUE_METRICS_FILE; the main PR integrates and expands this logic with per-cycle PR/issue readiness metrics.
• t1397: fix pulse-wrapper stuck process — add watchdog timeout #2853 — Adds timeout/watchdog behavior for stalled processes; the main PR introduces run_stage_with_timeout() to bound pre-run cleanup stages and prevent wrapper hangs.

Suggested labels

bug

Poem

🛡️ Pre-run stages now wear timeout armor bright,
Repo slugs guide workers through the multi-repo night,
No more issue-number ghosts crossing repo lines,
Adaptive governors count what truly shines,
Pulse breathes free—no more hangs, just forward design! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title accurately summarizes the core changes: hardening pre-run stages with timeouts and improving queue accounting with repo-aware checks.
Linked Issues check	✅ Passed	All three linked issues are comprehensively addressed: timeouts bound pre-run stages (#4261), configurable limits replace fixed windows (#4260), and repo+issue keying eliminates cross-repo collisions (#4262).
Out of Scope Changes check	✅ Passed	All changes directly support the stated objectives: timeout infrastructure, dynamic limits, repo-aware worker checks, and adaptive queue metrics are all required by the linked issues.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bugfix/pulse-prerun-timeout-guard

📝 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, 405 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Thu Mar 12 23:16:59 UTC 2026: Code review monitoring started
Thu Mar 12 23:16:59 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 405

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 405
• VULNERABILITIES: 0

Generated on: Thu Mar 12 23:17:01 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.agents/scripts/pulse-wrapper.sh:
- Around line 2187-2191: prefetch_state exports PULSE_SCOPE_REPOS but
run_stage_with_timeout runs it in a subshell so that export is lost; change
prefetch_state to also write the scope value to a file (e.g., echo
"$PULSE_SCOPE_REPOS" > "$SCOPE_FILE") and then, immediately after the successful
call to run_stage_with_timeout "prefetch_state" (before run_pulse is started),
read and re-export that file (e.g., if [ -f "$SCOPE_FILE" ]; then export
PULSE_SCOPE_REPOS="$(<"$SCOPE_FILE")"; fi) so run_pulse sees the correct
PULSE_SCOPE_REPOS. Ensure you reference the same SCOPE_FILE variable in both
prefetch_state and the main flow around run_stage_with_timeout and run_pulse.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 93da1dd8-051e-4138-bedf-31953edc0ece

📥 Commits

Reviewing files that changed from the base of the PR and between 3258b87 and 07ce68a.

📒 Files selected for processing (1)

• .agents/scripts/pulse-wrapper.sh

[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, 405 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Thu Mar 12 23:35:52 UTC 2026: Code review monitoring started
Thu Mar 12 23:35:52 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 405

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 405
• VULNERABILITIES: 0

Generated on: Thu Mar 12 23:35:55 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[sonarqubecloud]

Quality Gate passed

Issues
2 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

Addressed in 67652fd: persisted scope through timed prefetch stage.