t1471: adapt pulse cold-start timeout to underfill severity

[marcusquinn]

Summary

• Make run_pulse() compute cold-start timeout from underfill severity, not only binary underfilled mode.
• Use 300s cold-start timeout for severe underfill (>=50%), 450s for moderate underfill (>=25%), and configured underfilled timeout otherwise.
• Pass underfill percentage to run_pulse() from both initial cycle and utilization backfill loop, with explicit logging for observability.

Verification

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

Closes #4351
Refs #4347

Summary by CodeRabbit

• Chores
  • Enhanced internal system initialization logic with improved parameter validation and conditional timeout adjustments for better resource management.

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

Walkthrough

This PR modifies the pulse-wrapper.sh script to introduce a new underfill_pct parameter to the run_pulse function, enabling adaptive cold-start timeout adjustments based on underfill severity thresholds (50% and 25%). The parameter is propagated through the call chain from main and enforce_utilization_invariants to run_pulse.

Changes

Cohort / File(s)	Summary
Pulse Timeout Adaptation .agents/scripts/pulse-wrapper.sh	Added underfill_pct parameter to run_pulse function; introduced conditional cold-start timeout overrides (300s if ≥50%, 450s if ≥25%); updated log messages to reflect underfill percentage; propagated parameter through call chain in enforce_utilization_invariants and main with numeric validation defaulting to 0.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• t1469: adapt stale pulse recovery timeout to underfill severity #4348 — Implements adaptive underfill-severity timeouts in the same script using identical 50%/25% thresholds and shortened recovery windows.
• t1466: tighten pulse cold-start timeout when underfilled #4323 — Modifies run_pulse and cold-start timeout behavior for underfilled conditions with alternative parameter handling.
• t1463: prevent cold-start false idle kills in pulse watchdog #4312 — Adjusts pulse-wrapper.sh's cold-start and watchdog timeout logic with related timing concerns.

Suggested labels

bug

Poem

⏱️ When underfill creeps in with weary strain,
The timeouts bend to match the pain—
Fifty percent calls for swift reprieve,
Twenty-five seeks patience's reprieve,
Cold-start sleeps longer, burnout's refrain.

🚥 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	The title accurately summarizes the main change: adapting pulse cold-start timeout behavior based on underfill severity levels, which is the core objective of this PR.
Linked Issues check	✅ Passed	The code changes fully implement issue #4351 requirements: timeout scaling based on underfill severity (300s/450s thresholds), underfill_pct propagation through call chains, and logging for observability.
Out of Scope Changes check	✅ Passed	All changes are tightly scoped to the stated objective of adapting cold-start timeout to underfill severity; no extraneous modifications detected.
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 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-adaptive-coldstart-timeout

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

�[0;34m[INFO]�[0m Recent monitoring activity:
Fri Mar 13 04:10:05 UTC 2026: Code review monitoring started
Fri Mar 13 04:10:05 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 412

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 412
• VULNERABILITIES: 0

Generated on: Fri Mar 13 04:10:08 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

[coderabbitai]

🧹 Nitpick comments (1)

.agents/scripts/pulse-wrapper.sh (1)

1433-1437: Consider extracting timeout constants for the tiered thresholds.

The timeout values 300 and 450 are hardcoded here and duplicated in check_dedup() (lines 242-244). For maintainability, these could be extracted to configuration variables alongside the existing PULSE_COLD_START_TIMEOUT_* family.

That said, since these implement a specific policy defined in the PR objectives and are consistent across both locations, this is a minor refinement that could be deferred.

♻️ Optional: Extract tiered timeout constants

 PULSE_COLD_START_TIMEOUT_UNDERFILLED="${PULSE_COLD_START_TIMEOUT_UNDERFILLED:-600}"
+PULSE_COLD_START_TIMEOUT_SEVERE="${PULSE_COLD_START_TIMEOUT_SEVERE:-300}"       # >=50% underfill
+PULSE_COLD_START_TIMEOUT_MODERATE="${PULSE_COLD_START_TIMEOUT_MODERATE:-450}"   # >=25% underfill

Then update both run_pulse() and check_dedup() to reference these constants.

🤖 Prompt for AI Agents

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

In @.agents/scripts/pulse-wrapper.sh around lines 1433 - 1437, Extract the
hardcoded tiered timeouts (300 and 450) into named configuration variables
(e.g., PULSE_COLD_START_TIMEOUT_TIER1 and PULSE_COLD_START_TIMEOUT_TIER2
alongside the existing PULSE_COLD_START_TIMEOUT_* family) and update run_pulse()
where effective_cold_start_timeout is set and check_dedup() (the duplicated
logic) to reference these new constants instead of literals; ensure the variable
names are consistent with existing PULSE_COLD_START_TIMEOUT_* naming and that
any default behavior remains unchanged.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In @.agents/scripts/pulse-wrapper.sh:
- Around line 1433-1437: Extract the hardcoded tiered timeouts (300 and 450)
into named configuration variables (e.g., PULSE_COLD_START_TIMEOUT_TIER1 and
PULSE_COLD_START_TIMEOUT_TIER2 alongside the existing PULSE_COLD_START_TIMEOUT_*
family) and update run_pulse() where effective_cold_start_timeout is set and
check_dedup() (the duplicated logic) to reference these new constants instead of
literals; ensure the variable names are consistent with existing
PULSE_COLD_START_TIMEOUT_* naming and that any default behavior remains
unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d3851394-4a09-4fe0-b9a2-a663e75516f3

📥 Commits

Reviewing files that changed from the base of the PR and between 706ac41 and 7162148.

📒 Files selected for processing (1)

• .agents/scripts/pulse-wrapper.sh