feat(cron): add heartbeat wake cooldown to prevent exec re-fire loop (#871)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: Fabien Penso <gpg@pen.so>

Author: 3 people

crates/config/src/schema/system.rs

@@ -182,6 +182,10 @@ pub struct HeartbeatConfig {
     pub sandbox_enabled: bool,
     /// Override sandbox image for heartbeat. If `None`, uses the default image.
     pub sandbox_image: Option<String>,
+    /// Minimum duration between exec-triggered heartbeat wakes (e.g. "5m", "0").
+    /// Prevents exec-completion callbacks from re-waking the heartbeat in a tight loop.
+    /// Defaults to "5m". Set to "0" to disable.
+    pub wake_cooldown: String,
 }
 
 impl Default for HeartbeatConfig {
@@ -198,6 +202,7 @@ impl Default for HeartbeatConfig {
             to: None,
             sandbox_enabled: true,
             sandbox_image: None,
+            wake_cooldown: "5m".into(),
         }
     }
 }

crates/config/src/template.rs

@@ -490,6 +490,7 @@ port = {port}                           # Port number (auto-generated for this i
 # ack_max_chars = 300               # Max characters for acknowledgment reply
 # deliver = false                   # Deliver heartbeat replies to a channel
 # sandbox_enabled = true            # Run heartbeat commands in sandbox
+# wake_cooldown = "5m"              # Min duration between exec-triggered heartbeat wakes (0 to disable)
 
 # [heartbeat.active_hours]
 # start = "08:00"

crates/config/src/validate/schema_map.rs

@@ -535,6 +535,7 @@ pub(super) fn build_schema_map() -> KnownKeys {
                 ("to", Leaf),
                 ("sandbox_enabled", Leaf),
                 ("sandbox_image", Leaf),
+                ("wake_cooldown", Leaf),
             ])),
         ),
         (

crates/cron/src/heartbeat.rs

@@ -461,7 +461,7 @@ mod tests {
         let events = vec![
             crate::system_events::SystemEvent {
                 text: "Command `ls` exited 0".into(),
-                reason: "exec-event".into(),
+                reason: crate::service::WAKE_REASON_EXEC_EVENT.into(),
                 enqueued_at_ms: 1000,
             },
             crate::system_events::SystemEvent {
@@ -472,7 +472,10 @@ mod tests {
         ];
         let prompt = build_event_enriched_prompt(&events, "check inbox");
         assert!(prompt.starts_with(EVENTS_PROMPT_PREFIX));
-        assert!(prompt.contains("Command `ls` exited 0 [exec-event]"));
+        assert!(prompt.contains(&format!(
+            "Command `ls` exited 0 [{}]",
+            crate::service::WAKE_REASON_EXEC_EVENT
+        )));
         assert!(prompt.contains("Cron job fired [cron:abc]"));
         assert!(prompt.ends_with("check inbox"));
     }

crates/cron/src/lib.rs

@@ -15,6 +15,7 @@ pub mod system_events;
 pub mod types;
 
 pub use error::{Error, Result};
+pub use service::{DEFAULT_WAKE_COOLDOWN_MS, WAKE_REASON_CRON_EVENT, WAKE_REASON_EXEC_EVENT};
 
 /// Run database migrations for the cron crate.
 ///

crates/cron/src/parse.rs

@@ -5,13 +5,19 @@ use crate::{Error, Result};
 /// Parse a human-friendly duration string into milliseconds.
 ///
 /// Supported suffixes: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
-/// Examples: `"30s"`, `"5m"`, `"2h"`, `"1d"`.
+/// A bare `"0"` is accepted as a disable sentinel that returns `0`.
+/// Examples: `"30s"`, `"5m"`, `"2h"`, `"1d"`, `"0"`.
 pub fn parse_duration_ms(input: &str) -> Result<u64> {
     let input = input.trim();
     if input.is_empty() {
         return Err(Error::message("empty duration string"));
     }
 
+    // Bare "0" is the disable sentinel.
+    if input == "0" {
+        return Ok(0);
+    }
+
     let (num_str, suffix) = match input.find(|c: char| c.is_alphabetic()) {
         Some(i) => (&input[..i], &input[i..]),
         None => {
@@ -74,6 +80,8 @@ mod tests {
     #[case("2h", 7_200_000)]
     #[case("1d", 86_400_000)]
     #[case("  10m  ", 600_000)]
+    #[case("0", 0)]
+    #[case("  0  ", 0)]
     fn test_parse_duration_ok(#[case] input: &str, #[case] expected: u64) {
         assert_eq!(parse_duration_ms(input).unwrap(), expected);
     }

crates/cron/src/service.rs

@@ -128,11 +128,30 @@ pub struct CronService {
     on_notify: Option<NotifyFn>,
     rate_limiter: Mutex<RateLimiter>,
     events_queue: Arc<SystemEventsQueue>,
+    /// Minimum ms between exec-triggered heartbeat wakes. Zero disables cooldown.
+    wake_cooldown_ms: u64,
 }
 
 /// Max time a job can be in "running" state before we consider it stuck (2 hours).
 const STUCK_THRESHOLD_MS: u64 = 2 * 60 * 60 * 1000;
 
+/// Minimum cooldown between exec-triggered heartbeat wake calls.
+///
+/// Prevents exec-completion callbacks from re-waking the heartbeat
+/// in a tight loop when the agent uses `exec` during a heartbeat turn.
+/// The wake is skipped if the heartbeat last completed less than this
+/// duration ago. This is a safety net — the scheduled interval still
+/// applies for normal periodic firing.
+///
+/// This cooldown only applies to exec-triggered wakes ([`WAKE_REASON_EXEC_EVENT`]).
+/// CronWakeMode::Now wakes ([`WAKE_REASON_CRON_EVENT`]) are never suppressed.
+pub const DEFAULT_WAKE_COOLDOWN_MS: u64 = 5 * 60 * 1000;
+
+/// Wake reason: exec-completion callback.
+pub const WAKE_REASON_EXEC_EVENT: &str = "exec-event";
+/// Wake reason: cron job with [`CronWakeMode::Now`](crate::types::CronWakeMode::Now) finished.
+pub const WAKE_REASON_CRON_EVENT: &str = "cron-event";
+
 fn now_ms() -> u64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -152,6 +171,7 @@ impl CronService {
             on_agent_turn,
             None,
             RateLimitConfig::default(),
+            DEFAULT_WAKE_COOLDOWN_MS,
         )
     }
 
@@ -168,6 +188,7 @@ impl CronService {
             on_agent_turn,
             Some(on_notify),
             RateLimitConfig::default(),
+            DEFAULT_WAKE_COOLDOWN_MS,
         )
     }
 
@@ -178,13 +199,15 @@ impl CronService {
         on_agent_turn: AgentTurnFn,
         on_notify: Option<NotifyFn>,
         rate_limit_config: RateLimitConfig,
+        wake_cooldown_ms: u64,
     ) -> Arc<Self> {
         Self::with_events_queue(
             store,
             on_system_event,
             on_agent_turn,
             on_notify,
             rate_limit_config,
+            wake_cooldown_ms,
             SystemEventsQueue::new(),
         )
     }
@@ -199,6 +222,7 @@ impl CronService {
         on_agent_turn: AgentTurnFn,
         on_notify: Option<NotifyFn>,
         rate_limit_config: RateLimitConfig,
+        wake_cooldown_ms: u64,
         events_queue: Arc<SystemEventsQueue>,
     ) -> Arc<Self> {
         Arc::new(Self {
@@ -212,6 +236,7 @@ impl CronService {
             on_notify,
             rate_limiter: Mutex::new(RateLimiter::new(rate_limit_config)),
             events_queue,
+            wake_cooldown_ms,
         })
     }
 
@@ -224,13 +249,38 @@ impl CronService {
     ///
     /// Multiple wake calls coalesce naturally: they all set `next_run_at_ms = now`
     /// idempotently, and `running_at_ms` prevents the heartbeat from firing twice.
+    ///
+    /// When called with reason [`WAKE_REASON_EXEC_EVENT`], a cooldown guard applies: if the
+    /// heartbeat last completed less than `wake_cooldown_ms` ago, the wake is skipped.
+    /// This prevents exec-completion callbacks from creating a re-fire loop.
+    /// Other reasons (e.g. [`WAKE_REASON_CRON_EVENT`]) are never suppressed.
     pub async fn wake(&self, reason: &str) {
         let now = now_ms();
         let mut jobs = self.jobs.write().await;
         if let Some(job) = jobs.iter_mut().find(|j| j.id == "__heartbeat__")
             && job.enabled
             && job.state.running_at_ms.is_none()
         {
+            // Enforce cooldown for exec-triggered wakes only. This prevents
+            // exec-completion callbacks from creating a re-fire loop when the
+            // heartbeat agent uses `exec` during its turn. CronWakeMode::Now wakes
+            // are never suppressed.
+            if reason == WAKE_REASON_EXEC_EVENT
+                && self.wake_cooldown_ms > 0
+                && let Some(last_run) = job.state.last_run_at_ms
+            {
+                let elapsed = now.saturating_sub(last_run);
+                if elapsed < self.wake_cooldown_ms {
+                    debug!(
+                        reason,
+                        elapsed_ms = elapsed,
+                        cooldown_ms = self.wake_cooldown_ms,
+                        "skipping heartbeat wake — within cooldown"
+                    );
+                    return;
+                }
+            }
+
             debug!(reason, "waking heartbeat");
             job.state.next_run_at_ms = Some(now);
         }
@@ -665,7 +715,7 @@ impl CronService {
 
         // Wake heartbeat immediately if this job requested it.
         if job.wake_mode == CronWakeMode::Now && job.id != "__heartbeat__" {
-            self.wake("cron-event").await;
+            self.wake(WAKE_REASON_CRON_EVENT).await;
         }
 
         info!(