@swarmclawai/swarmclaw 0.7.8 → 0.8.0

package/src/lib/server/heartbeat-service.ts

@@ -14,6 +14,7 @@ import { drainSystemEvents } from './system-events'
 import { buildIdentityContinuityContext } from './identity-continuity'
 import { buildMainLoopHeartbeatPrompt, isMainSession } from './main-agent-loop'
 import { ensureAgentThreadSession } from './agent-thread-session'
+import { isAgentDisabled } from './agent-availability'
 
 const HEARTBEAT_TICK_MS = 5_000
 
@@ -134,7 +135,7 @@ interface HeartbeatFileSession {
 
 const DEFAULT_HEARTBEAT_PROMPT = 'Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.'
 
-function readHeartbeatFile(session: HeartbeatFileSession): string {
+export function readHeartbeatFile(session: HeartbeatFileSession): string {
   try {
     const filePath = path.join(session.cwd || WORKSPACE_DIR, 'HEARTBEAT.md')
     if (fs.existsSync(filePath)) {
@@ -196,7 +197,7 @@ export function isHeartbeatContentEffectivelyEmpty(content: string | undefined |
   return true
 }
 
-function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackPrompt: string, heartbeatFileContent: string): string {
+export function buildAgentHeartbeatPrompt(session: any, agent: any, fallbackPrompt: string, heartbeatFileContent: string): string {
   if (!agent) return fallbackPrompt
 
   const identityContext = buildIdentityContext(session, agent)
@@ -285,7 +286,7 @@ function resolveNum(obj: Record<string, any>, key: string, current: number): num
   return current
 }
 
-function heartbeatConfigForSession(session: any, settings: Record<string, any>, agents: Record<string, any>): HeartbeatConfig {
+export function heartbeatConfigForSession(session: any, settings: Record<string, any>, agents: Record<string, any>): HeartbeatConfig {
   // Global defaults — 30 min interval (was 120s)
   let intervalSec = resolveInterval(settings, DEFAULT_HEARTBEAT_INTERVAL_SEC)
   const globalPrompt = (typeof settings.heartbeatPrompt === 'string' && settings.heartbeatPrompt.trim())
@@ -366,11 +367,11 @@ async function tickHeartbeats() {
 
   const agents = loadAgents()
   for (const agent of Object.values(agents) as any[]) {
-    if (!agent?.id || agent.heartbeatEnabled !== true) continue
+    if (!agent?.id || agent.heartbeatEnabled !== true || isAgentDisabled(agent)) continue
     ensureAgentThreadSession(String(agent.id))
   }
   const sessions = loadSessions()
-  const hasScopedAgents = Object.values(agents).some((a: any) => a?.heartbeatEnabled === true)
+  const hasScopedAgents = Object.values(agents).some((a: any) => a?.heartbeatEnabled === true && !isAgentDisabled(a))
 
   // Prune tracked sessions that no longer exist or have heartbeat disabled
   for (const trackedId of state.lastBySession.keys()) {
@@ -391,6 +392,7 @@ async function tickHeartbeats() {
 
     // Check if this session or its agent has explicit heartbeat opt-in
     const agent = session.agentId ? agents[session.agentId] : null
+    if (isAgentDisabled(agent)) continue
     const explicitOptIn = session.heartbeatEnabled === true || (agent && agent.heartbeatEnabled === true)
 
     // If global loopMode is bounded, only allow sessions with explicit opt-in
@@ -428,12 +430,15 @@ async function tickHeartbeats() {
 
     const rawHeartbeatFileContent = readHeartbeatFile(session)
     const heartbeatFileContent = isHeartbeatContentEffectivelyEmpty(rawHeartbeatFileContent) ? '' : rawHeartbeatFileContent
-    const hasGoal = !!(agent?.heartbeatGoal || agent?.description || agent?.systemPrompt || agent?.soul)
+    const hasExplicitGoal = !!(agent?.heartbeatGoal || agent?.heartbeatNextAction)
+    const hasAgentContext = !!(agent?.description || agent?.systemPrompt || agent?.soul)
     const hasCustomPrompt = cfg.prompt !== DEFAULT_HEARTBEAT_PROMPT
-    // Skip heartbeat only if there's truly nothing to drive it:
-    // no agent goal, no HEARTBEAT.md content, AND no custom prompt configured
-    if (!hasGoal && !heartbeatFileContent && !hasCustomPrompt) {
-      continue
+    const hasUserMessages = lastUserMessageAt(session) > 0
+    // Skip heartbeat if there's nothing to drive it. An agent description alone
+    // is not enough — the session needs at least one user message or an explicit
+    // heartbeat goal/HEARTBEAT.md content. This prevents noise on unused sessions.
+    if (!hasExplicitGoal && !heartbeatFileContent && !hasCustomPrompt) {
+      if (!hasAgentContext || !hasUserMessages) continue
     }
     const baseHeartbeatMessage = buildAgentHeartbeatPrompt(session, agent, cfg.prompt, heartbeatFileContent)
     const heartbeatMessage = isMainSession(session)

package/src/lib/server/heartbeat-wake.test.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict'
+import { afterEach, describe, it } from 'node:test'
+
+import {
+  buildHeartbeatWakePrompt,
+  buildWakeTriggerContext,
+  hasPendingHeartbeatWake,
+  mergeHeartbeatWakeRequest,
+  requestHeartbeatNow,
+  resetHeartbeatWakeStateForTests,
+  snapshotPendingHeartbeatWakesForTests,
+} from './heartbeat-wake'
+
+describe('heartbeat-wake helpers', () => {
+  afterEach(() => {
+    resetHeartbeatWakeStateForTests()
+  })
+
+  it('retains distinct wake events per target and keeps the latest requested timestamp', () => {
+    const first = mergeHeartbeatWakeRequest(undefined, {
+      agentId: 'ops',
+      reason: 'connector-message',
+      source: 'connector:slack',
+      resumeMessage: 'Slack says the deploy is red.',
+      requestedAt: 100,
+    })
+    const merged = mergeHeartbeatWakeRequest(first, {
+      agentId: 'ops',
+      reason: 'schedule',
+      source: 'schedule:nightly',
+      resumeMessage: 'Nightly check-in fired.',
+      requestedAt: 250,
+    })
+
+    assert.equal(merged.agentId, 'ops')
+    assert.equal(merged.requestedAt, 250)
+    assert.equal(merged.events.length, 2)
+    assert.deepEqual(merged.events.map((event) => event.reason), ['connector-message', 'schedule'])
+  })
+
+  it('deduplicates identical events but preserves differently sourced triggers', () => {
+    let wake = mergeHeartbeatWakeRequest(undefined, {
+      sessionId: 's1',
+      reason: 'schedule',
+      source: 'schedule:nightly',
+      requestedAt: 1,
+    })
+    wake = mergeHeartbeatWakeRequest(wake, {
+      sessionId: 's1',
+      reason: 'schedule',
+      source: 'schedule:nightly',
+      requestedAt: 2,
+    })
+    wake = mergeHeartbeatWakeRequest(wake, {
+      sessionId: 's1',
+      reason: 'schedule',
+      source: 'schedule:hourly',
+      requestedAt: 3,
+    })
+
+    assert.equal(wake.events.length, 2)
+    assert.deepEqual(wake.events.map((event) => event.source), ['schedule:hourly', 'schedule:nightly'])
+  })
+
+  it('builds a structured trigger context for event-driven wakes', () => {
+    const wake = mergeHeartbeatWakeRequest(undefined, {
+      sessionId: 'sess-1',
+      reason: 'connector-message',
+      source: 'connector:slack',
+      resumeMessage: 'Slack says deploy is still red.',
+      detail: 'Text: prod deploy is still failing health checks',
+      requestedAt: 10,
+      priority: 90,
+    })
+    const triggerContext = buildWakeTriggerContext(wake.events, '2026-03-08T15:30:00.000Z')
+    const prompt = buildHeartbeatWakePrompt({
+      wake,
+      basePrompt: 'BASE_PROMPT',
+      nowIso: '2026-03-08T15:30:00.000Z',
+    })
+
+    assert.match(triggerContext, /## Wake Trigger Context/)
+    assert.match(triggerContext, /reason=connector-message \| source=connector:slack \| priority=90/)
+    assert.match(triggerContext, /Resume: Slack says deploy is still red\./)
+    assert.match(triggerContext, /Detail: Text: prod deploy is still failing health checks/)
+    assert.match(prompt, /^BASE_PROMPT/m)
+    assert.match(prompt, /Reply HEARTBEAT_OK only if every trigger above is already handled/)
+  })
+
+  it('tracks pending wake state while coalesced wakes are queued', () => {
+    requestHeartbeatNow({
+      sessionId: 'sess-2',
+      reason: 'watch_job',
+      source: 'watch:http',
+      resumeMessage: 'Check the changed API response.',
+    })
+    requestHeartbeatNow({
+      sessionId: 'sess-2',
+      reason: 'connector-message',
+      source: 'connector:slack',
+      resumeMessage: 'Slack asks for an update.',
+    })
+
+    assert.equal(hasPendingHeartbeatWake(), true)
+    const wakes = snapshotPendingHeartbeatWakesForTests()
+    assert.equal(wakes.length, 1)
+    assert.deepEqual(
+      [...wakes[0].events.map((event) => event.reason)].sort(),
+      ['connector-message', 'watch_job'],
+    )
+  })
+})

package/src/lib/server/heartbeat-wake.ts

@@ -1,84 +1,338 @@
 /**
  * On-demand heartbeat wake — triggers an immediate heartbeat for an agent/session.
- * Requests are debounced with a 250ms coalesce window to batch rapid-fire events.
+ * Requests are debounced with a short coalesce window, retain distinct trigger
+ * events per target, and retry when the session lane is already busy.
  */
 
 import { ensureAgentThreadSession } from './agent-thread-session'
+import {
+  buildAgentHeartbeatPrompt,
+  heartbeatConfigForSession,
+  isHeartbeatContentEffectivelyEmpty,
+  readHeartbeatFile,
+} from './heartbeat-service'
+import { buildMainLoopHeartbeatPrompt, isMainSession } from './main-agent-loop'
 import { loadSessions, loadAgents, loadSettings } from './storage'
-import { enqueueSessionRun } from './session-run-manager'
+import { enqueueSessionRun, getSessionExecutionState } from './session-run-manager'
 import { log } from './logger'
+import { isAgentDisabled } from './agent-availability'
 
-interface WakeRequest {
+export interface WakeRequestInput {
+  eventId?: string
   agentId?: string
   sessionId?: string
   reason?: string
+  source?: string
+  resumeMessage?: string
+  detail?: string
+  requestedAt?: number
+  occurredAt?: number
+  priority?: number
+  retryCount?: number
+}
+
+export interface WakeEvent {
+  eventId?: string
+  reason: string
+  source?: string
+  resumeMessage?: string
+  detail?: string
+  occurredAt: number
+  priority: number
+}
+
+export interface WakeRequest {
+  agentId?: string
+  sessionId?: string
+  requestedAt: number
+  retryCount: number
+  events: WakeEvent[]
 }
 
 const COALESCE_MS = 250
+const RETRY_MS = 1_000
+const MAX_WAKE_EVENTS = 6
+const MAX_RESUME_CHARS = 280
+const MAX_DETAIL_CHARS = 800
+type WakeTimerKind = 'normal' | 'retry'
 
 const globalKey = '__swarmclaw_heartbeat_wake__' as const
 const globalScope = globalThis as typeof globalThis & {
-  [globalKey]?: { pending: Map<string, WakeRequest>; timer: ReturnType<typeof setTimeout> | null }
+  [globalKey]?: {
+    pending: Map<string, WakeRequest>
+    timer: ReturnType<typeof setTimeout> | null
+    timerDueAt: number | null
+    timerKind: WakeTimerKind | null
+  }
 }
 const state = globalScope[globalKey] ?? (globalScope[globalKey] = {
   pending: new Map(),
   timer: null,
+  timerDueAt: null,
+  timerKind: null,
 })
 
+function trimText(value: unknown, maxChars: number): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const normalized = value.replace(/\s+/g, ' ').trim()
+  return normalized ? normalized.slice(0, maxChars) : undefined
+}
+
+function normalizeWakeReason(reason?: string): string {
+  return trimText(reason, 80) || 'on-demand'
+}
+
+function normalizeWakeTarget(value?: string): string | undefined {
+  return trimText(value, 160)
+}
+
+function normalizeOccurredAt(value?: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : Date.now()
+}
+
+function reasonPriority(reason: string): number {
+  const normalized = reason.toLowerCase()
+  if (/(approval|connector-message|webhook|watch_job|scheduled_wake|task-completed)/.test(normalized)) return 90
+  if (/(schedule)/.test(normalized)) return 70
+  if (/(comparison|manual|on-demand)/.test(normalized)) return 50
+  return 40
+}
+
+function normalizeWakeEvent(input: WakeRequestInput): WakeEvent {
+  const reason = normalizeWakeReason(input.reason)
+  const explicitPriority = typeof input.priority === 'number' && Number.isFinite(input.priority)
+    ? Math.trunc(input.priority)
+    : reasonPriority(reason)
+  return {
+    ...(trimText(input.eventId, 160) ? { eventId: trimText(input.eventId, 160) } : {}),
+    reason,
+    ...(trimText(input.source, 120) ? { source: trimText(input.source, 120) } : {}),
+    ...(trimText(input.resumeMessage, MAX_RESUME_CHARS) ? { resumeMessage: trimText(input.resumeMessage, MAX_RESUME_CHARS) } : {}),
+    ...(trimText(input.detail, MAX_DETAIL_CHARS) ? { detail: trimText(input.detail, MAX_DETAIL_CHARS) } : {}),
+    occurredAt: normalizeOccurredAt(input.occurredAt ?? input.requestedAt),
+    priority: Math.max(0, Math.min(100, explicitPriority)),
+  }
+}
+
+function uniqueWakeEvents(existing: WakeEvent[], incoming: WakeEvent): WakeEvent[] {
+  const merged = [...existing]
+  const matchIndex = merged.findIndex((candidate) => {
+    if (candidate.eventId && incoming.eventId) return candidate.eventId === incoming.eventId
+    return candidate.reason === incoming.reason
+      && candidate.source === incoming.source
+      && candidate.resumeMessage === incoming.resumeMessage
+      && candidate.detail === incoming.detail
+  })
+
+  if (matchIndex >= 0) {
+    const previous = merged[matchIndex]
+    merged[matchIndex] = {
+      ...previous,
+      ...incoming,
+      priority: Math.max(previous.priority, incoming.priority),
+      occurredAt: Math.max(previous.occurredAt, incoming.occurredAt),
+      resumeMessage: incoming.resumeMessage || previous.resumeMessage,
+      detail: incoming.detail || previous.detail,
+    }
+  } else {
+    merged.push(incoming)
+  }
+
+  merged.sort((left, right) => {
+    if (right.priority !== left.priority) return right.priority - left.priority
+    return right.occurredAt - left.occurredAt
+  })
+  return merged.slice(0, MAX_WAKE_EVENTS)
+}
+
+function wakeTargetKey(input: { agentId?: string; sessionId?: string }): string {
+  return `${normalizeWakeTarget(input.agentId) || ''}::${normalizeWakeTarget(input.sessionId) || ''}`
+}
+
+export function mergeHeartbeatWakeRequest(
+  existing: WakeRequest | undefined,
+  next: WakeRequestInput,
+): WakeRequest {
+  const agentId = normalizeWakeTarget(next.agentId) || existing?.agentId
+  const sessionId = normalizeWakeTarget(next.sessionId) || existing?.sessionId
+  const requestedAt = Math.max(existing?.requestedAt || 0, normalizeOccurredAt(next.requestedAt))
+  const retryCount = Math.max(existing?.retryCount || 0, typeof next.retryCount === 'number' ? Math.trunc(next.retryCount) : 0)
+  const events = uniqueWakeEvents(existing?.events || [], normalizeWakeEvent(next))
+  return {
+    ...(agentId ? { agentId } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    requestedAt,
+    retryCount,
+    events,
+  }
+}
+
+function queuePendingWake(next: WakeRequestInput): void {
+  const key = wakeTargetKey(next)
+  const existing = state.pending.get(key)
+  state.pending.set(key, mergeHeartbeatWakeRequest(existing, next))
+}
+
+function queuePendingWakeRequest(next: WakeRequest): void {
+  const key = wakeTargetKey(next)
+  let merged = state.pending.get(key)
+  for (const event of next.events) {
+    merged = mergeHeartbeatWakeRequest(merged, {
+      agentId: next.agentId,
+      sessionId: next.sessionId,
+      requestedAt: next.requestedAt,
+      retryCount: next.retryCount,
+      eventId: event.eventId,
+      reason: event.reason,
+      source: event.source,
+      resumeMessage: event.resumeMessage,
+      detail: event.detail,
+      occurredAt: event.occurredAt,
+      priority: event.priority,
+    })
+  }
+  if (merged) state.pending.set(key, merged)
+}
+
+function scheduleFlush(delayMs: number, kind: WakeTimerKind = 'normal'): void {
+  const delay = Math.max(0, Number.isFinite(delayMs) ? Math.trunc(delayMs) : COALESCE_MS)
+  const dueAt = Date.now() + delay
+  if (state.timer) {
+    if (state.timerKind === 'retry' && kind !== 'normal') return
+    if (typeof state.timerDueAt === 'number' && state.timerDueAt <= dueAt) return
+    clearTimeout(state.timer)
+    state.timer = null
+    state.timerDueAt = null
+    state.timerKind = null
+  }
+
+  state.timerDueAt = dueAt
+  state.timerKind = kind
+  state.timer = setTimeout(() => {
+    flushWakes()
+  }, delay)
+}
+
+export function buildWakeTriggerContext(events: WakeEvent[], nowIso?: string): string {
+  const lines = [
+    '## Wake Trigger Context',
+    `Triggered at: ${nowIso || new Date().toISOString()}`,
+    'These new events caused this immediate wake. Prioritize them over generic background polling and avoid repeating already-completed work.',
+    'If the base heartbeat instructions require an exact file change or exact acknowledgment phrase, follow that exactly and do not add extra commentary.',
+  ]
+  for (const event of events.slice(0, MAX_WAKE_EVENTS)) {
+    const tags = [
+      `reason=${event.reason}`,
+      event.source ? `source=${event.source}` : '',
+      `priority=${event.priority}`,
+      `at=${new Date(event.occurredAt).toISOString()}`,
+    ].filter(Boolean).join(' | ')
+    lines.push(`- ${tags}`)
+    if (event.resumeMessage) lines.push(`  Resume: ${event.resumeMessage}`)
+    if (event.detail) lines.push(`  Detail: ${event.detail}`)
+  }
+  lines.push('Reply HEARTBEAT_OK only if every trigger above is already handled or truly needs no action.')
+  return lines.join('\n')
+}
+
+export function buildHeartbeatWakePrompt(input: {
+  wake: WakeRequest
+  basePrompt?: string
+  nowIso?: string
+}): string {
+  const triggerContext = buildWakeTriggerContext(input.wake.events, input.nowIso)
+  if (input.basePrompt?.trim()) {
+    return [
+      input.basePrompt.trim(),
+      '',
+      triggerContext,
+    ].join('\n')
+  }
+  return [
+    'AGENT_HEARTBEAT_WAKE',
+    `Time: ${input.nowIso || new Date().toISOString()}`,
+    triggerContext,
+    'Take the highest-value next step now, or reply HEARTBEAT_OK if nothing needs attention.',
+  ].join('\n')
+}
+
+function resolveWakeSessionId(
+  wake: WakeRequest,
+  sessions: Record<string, Record<string, unknown>>,
+): string | undefined {
+  if (wake.sessionId) return wake.sessionId
+  if (!wake.agentId) return undefined
+
+  let bestSession: { id: string; lastActiveAt: number } | null = null
+  for (const session of Object.values(sessions)) {
+    if (session.agentId !== wake.agentId) continue
+    const lastActive = typeof session.lastActiveAt === 'number' ? session.lastActiveAt : 0
+    if (!bestSession || lastActive > bestSession.lastActiveAt) {
+      bestSession = { id: String(session.id), lastActiveAt: lastActive }
+    }
+  }
+  if (bestSession?.id) return bestSession.id
+  return ensureAgentThreadSession(wake.agentId)?.id
+}
+
 function flushWakes(): void {
   state.timer = null
-  const wakes = new Map(state.pending)
+  state.timerDueAt = null
+  state.timerKind = null
+  const wakes = [...state.pending.values()]
   state.pending.clear()
 
+  if (!wakes.length) return
+
   const agents = loadAgents()
   const settings = loadSettings()
+  const sessions = loadSessions() as Record<string, Record<string, unknown>>
+  let delayedForRetry = false
 
-  for (const [_key, wake] of wakes) {
+  for (const wake of wakes) {
     try {
-      let sessionId = wake.sessionId
-
-      // If only agentId provided, find the agent's most recently active session
-      if (!sessionId && wake.agentId) {
-        const sessions = loadSessions()
-        let bestSession: { id: string; lastActiveAt: number } | null = null
-        for (const s of Object.values(sessions) as Array<Record<string, unknown>>) {
-          if (s.agentId !== wake.agentId) continue
-          const lastActive = typeof s.lastActiveAt === 'number' ? s.lastActiveAt : 0
-          if (!bestSession || lastActive > bestSession.lastActiveAt) {
-            bestSession = { id: s.id as string, lastActiveAt: lastActive }
-          }
-        }
-        sessionId = bestSession?.id
-        if (!sessionId) {
-          sessionId = ensureAgentThreadSession(wake.agentId)?.id
-        }
-      }
-
+      const sessionId = resolveWakeSessionId(wake, sessions)
       if (!sessionId) continue
 
-      const session = loadSessions()[sessionId] as Record<string, unknown> | undefined
+      const session = (sessions[sessionId] || loadSessions()[sessionId]) as Record<string, unknown> | undefined
       if (!session) continue
 
+      const execution = getSessionExecutionState(sessionId)
+      if (execution.hasRunning || execution.hasQueued) {
+        queuePendingWakeRequest({
+          ...wake,
+          sessionId,
+          retryCount: wake.retryCount + 1,
+        })
+        delayedForRetry = true
+        log.info('heartbeat-wake', `Wake delayed for busy session ${sessionId}`, {
+          running: execution.hasRunning,
+          queued: execution.queueLength,
+        })
+        continue
+      }
+
       const agentId = (session.agentId || wake.agentId) as string | undefined
-      const agent = agentId ? agents[agentId] : null
-
-      // Build a minimal heartbeat prompt for the wake
-      const reason = wake.reason || 'on-demand'
-      const prompt = [
-        'AGENT_HEARTBEAT_WAKE',
-        `Time: ${new Date().toISOString()}`,
-        agent ? `Agent: ${(agent as Record<string, unknown>).name}` : '',
-        `Wake reason: ${reason}`,
-        '',
-        'An event has occurred that may require your attention.',
-        'Review and take appropriate action, or reply HEARTBEAT_OK if nothing is needed.',
-      ].filter(Boolean).join('\n')
-
-      // Resolve heartbeat model from agent/settings
-      const heartbeatModel =
-        (agent as Record<string, unknown> | null)?.heartbeatModel as string | undefined
-        || settings.heartbeatModel as string | undefined
-        || undefined
+      const agent = agentId ? agents[agentId] as Record<string, unknown> | null : null
+      if (isAgentDisabled(agent)) continue
+
+      const cfg = heartbeatConfigForSession(session, settings, agents)
+      if (!cfg.enabled) {
+        log.info('heartbeat-wake', `Wake skipped for session ${sessionId}: heartbeat disabled`, {
+          agentId,
+        })
+        continue
+      }
+      const rawHeartbeatFileContent = readHeartbeatFile(session)
+      const heartbeatFileContent = isHeartbeatContentEffectivelyEmpty(rawHeartbeatFileContent) ? '' : rawHeartbeatFileContent
+      const baseHeartbeatPrompt = buildAgentHeartbeatPrompt(session, agent, cfg.prompt, heartbeatFileContent)
+      const promptCore = isMainSession(session)
+        ? buildMainLoopHeartbeatPrompt(session, baseHeartbeatPrompt)
+        : baseHeartbeatPrompt
+      const prompt = buildHeartbeatWakePrompt({
+        wake,
+        basePrompt: promptCore,
+      })
 
       enqueueSessionRun({
         sessionId,
@@ -87,28 +341,55 @@ function flushWakes(): void {
         source: 'heartbeat-wake',
         mode: 'collect',
         dedupeKey: `heartbeat-wake:${sessionId}`,
-        modelOverride: heartbeatModel,
+        modelOverride: cfg.model || undefined,
         heartbeatConfig: {
-          ackMaxChars: 300,
-          showOk: false,
-          showAlerts: true,
-          target: null,
+          ackMaxChars: cfg.ackMaxChars,
+          showOk: cfg.showOk,
+          showAlerts: cfg.showAlerts,
+          target: cfg.target,
         },
       })
 
-      log.info('heartbeat-wake', `Wake fired for session ${sessionId} (reason: ${reason})`)
+      log.info('heartbeat-wake', `Wake fired for session ${sessionId}`, {
+        reasons: wake.events.map((event: WakeEvent) => event.reason),
+        retryCount: wake.retryCount,
+      })
     } catch (err: unknown) {
+      queuePendingWakeRequest({
+        ...wake,
+        retryCount: wake.retryCount + 1,
+      })
+      delayedForRetry = true
       log.warn('heartbeat-wake', `Wake failed: ${err instanceof Error ? err.message : String(err)}`)
     }
   }
+
+  if (delayedForRetry && state.pending.size > 0) {
+    scheduleFlush(RETRY_MS, 'retry')
+  }
 }
 
 /** Queue a heartbeat wake. Multiple rapid calls are coalesced into a single flush. */
-export function requestHeartbeatNow(opts: WakeRequest): void {
-  const key = opts.agentId || opts.sessionId || 'unknown'
-  state.pending.set(key, opts)
+export function requestHeartbeatNow(opts: WakeRequestInput): void {
+  queuePendingWake(opts)
+  scheduleFlush(COALESCE_MS, 'normal')
+}
 
-  if (!state.timer) {
-    state.timer = setTimeout(flushWakes, COALESCE_MS)
-  }
+export function resetHeartbeatWakeStateForTests(): void {
+  if (state.timer) clearTimeout(state.timer)
+  state.timer = null
+  state.timerDueAt = null
+  state.timerKind = null
+  state.pending.clear()
+}
+
+export function hasPendingHeartbeatWake(): boolean {
+  return state.pending.size > 0 || Boolean(state.timer)
+}
+
+export function snapshotPendingHeartbeatWakesForTests(): WakeRequest[] {
+  return [...state.pending.values()].map((wake) => ({
+    ...wake,
+    events: wake.events.map((event: WakeEvent) => ({ ...event })),
+  }))
 }