Defer heartbeat delivery while sessions are active

[sethkarten]

Summary

• Defer user /heartbeat and internal rlm_heartbeat cron jobs when the target session is already active.
• Treat streaming, running bash, or an existing pending follow-up as active work for heartbeat delivery.
• Preserve existing generic cron behavior: non-heartbeat cron jobs still queue behind busy sessions.

Why

Heartbeat prompts should not pile onto an agent that is already working. If a heartbeat fires while the target session is active, the scheduler now treats that run as skipped and reschedules the next interval instead of enqueueing a follow-up message.

Tests

• npm test -- cron-jobs.test.ts daemon-mode.test.ts
• npm run build
• pre-commit npm run check
• isolated daemon smoke test: set a heartbeat, queued existing work, waited past the heartbeat interval, and verified no heartbeat follow-up was queued while the job remained scheduled for the next interval

---

Note

Medium Risk
Changes daemon scheduling and message delivery for heartbeats versus ordinary crons; misclassification could drop heartbeats or alter queue behavior, but behavior is covered by unit tests.

Overview
Heartbeat cron jobs (heartbeat and rlm_heartbeat) no longer enqueue follow-ups when the target session is busy. The daemon returns "skipped" instead, and the scheduler reschedules the next interval via recordSkipResult, which now records lastSkippedAt (also shown in formatAgentCronJob).

Busy is defined by new shouldDeferHeartbeatCronJob: streaming, bash running, or any pending follow-up messages. Generic cron behavior is unchanged—busy sessions still get followUp for non-heartbeat jobs.

When a cron job actually runs on an idle session, delivery goes through session.prompt with streamingBehavior: "followUp" (and heartbeat-specific followUpQueueKey when applicable), so a stream that starts mid-dispatch still queues safely instead of colliding.

^{Reviewed by Cursor Bugbot for commit da4ff04. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Defer heartbeat cron job delivery while sessions are streaming, running bash, or have pending messages

• Adds shouldDeferHeartbeatCronJob and isHeartbeatCronJob helpers in cron-jobs.ts that check a HeartbeatCronSessionActivity snapshot to decide whether to skip execution.
• Updates AgentDaemon.runCronJob in daemon-mode.ts to call shouldDeferHeartbeatCronJob before scheduling; heartbeats return "skipped" and no follow-up is queued when the session is busy.
• Behavioral Change: previously, heartbeats for busy sessions were enqueued as follow-ups; now they are silently dropped until the next scheduled interval.

Changes since #265 opened

• Modified AgentDaemon.runCronJob method to defer heartbeat job execution when sessions are streaming or have pending messages, and removed follow-up queue key logic for all cron jobs [5a73a9b]
• Added lastSkippedAt timestamp tracking to the AgentCronJob interface and AgentCronJobStore class to record when cron jobs are skipped [5a73a9b]
• Modified AgentDaemon.runCronJob method to pass streamingBehavior: 'followUp' option when prompting idle sessions for non-heartbeat cron jobs [f4501f8]
• Modified AgentDaemon.runCronJob method to pass a followUpQueueKey option when invoking state.runtime.session.prompt, setting it to heartbeat:${job.id} for heartbeat cron jobs and leaving it undefined for non-heartbeat cron jobs [da4ff04]
• Added test assertions to verify that session.prompt is called with the correct followUpQueueKey value for both heartbeat and generic cron jobs, and introduced a new test case for idle generic cron jobs [da4ff04]

📊 Macroscope summarized 5a73a9b. 2 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 5a73a9b. Configure here.}