Troubleshooting

Agent Keeps Saying HEARTBEAT_OK?

If heartbeat replies are leaking into normal chat, your agent is probably handling maintenance prompts in the wrong place. Here’s the fast fix.

Recurring support pattern: users see random HEARTBEAT_OK messages in active conversations and assume the agent is broken. Usually the issue is instruction overlap, a stale heartbeat prompt, or context confusion between heartbeat checks and user-facing replies.

Reality check: heartbeat prompts are internal maintenance checks. They should not hijack normal chat responses unless no real task is pending.

Fast diagnosis (2 minutes)

Confirm where it happened: DM, server channel, or dashboard chat.
Check if a heartbeat poll was actually running at that moment.
Inspect HEARTBEAT.md for stale instructions like “always reply HEARTBEAT_OK”.
Run one canary message in normal chat: “Reply with one sentence describing today’s task.”

Known-good heartbeat behavior

Heartbeat polls run background checks or short maintenance tasks.
If nothing needs action, they return HEARTBEAT_OK once.
Normal user messages should get normal responses, not heartbeat tokens.
Exact-time reminders should use cron, not heartbeat loops.

Copy/paste recovery prompt

You are in normal conversation mode. Do NOT return HEARTBEAT_OK unless this is explicitly a heartbeat poll. 1) Confirm whether this current message is a heartbeat poll (yes/no). 2) If no, answer the user request directly in plain language. 3) If yes and no action is needed, return HEARTBEAT_OK exactly once. 4) If heartbeat instructions conflict with user conversation, prioritize direct user response and report the conflicting line from HEARTBEAT.md.

Avoid this trap: mixing “always return HEARTBEAT_OK” into global behavior instructions can leak maintenance behavior into every chat surface.

High-friction edge cases

Stale heartbeat file: old checklist still references completed tasks, causing repetitive no-op replies.
Thread/context drift: heartbeat event lands in a thread where users are actively chatting.
Instruction conflict: AGENTS.md/SOUL.md includes unconditional heartbeat language.
Cron vs heartbeat mismatch: users expect exact-time behavior from heartbeat sweeps.

Prevent it going forward

Keep HEARTBEAT.md short and explicit: maintenance only.
Add a guard line: “Only output HEARTBEAT_OK during heartbeat polls.”
Move exact-time tasks to cron reminders.
Retest with one heartbeat poll and one normal chat prompt.

When to escalate to #help

HEARTBEAT_OK appears repeatedly in normal chat after cleanup.
Heartbeat and normal messages are routed to the same destination unexpectedly.
Behavior differs across DM/server/dashboard with identical instructions.

Support packet

HEARTBEAT_OK leak report Surface where issue appears (dashboard/DM/server/thread): Timestamp + timezone: What user message was sent: What agent replied: Was a heartbeat poll active at that moment (yes/no/unsure): Current HEARTBEAT.md content (redacted if needed): Any cron jobs targeting same destination: Message link/screenshot:

Bottom line: keep heartbeat behavior scoped to heartbeat polls only. If it leaks into normal chat, isolate routing + instruction conflicts first.