PR #69278: fix(agents): stop injecting heartbeat system prompt on non-heartbeat runs (#69079)

• Repository: openclaw/openclaw
• Author: stainlu
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/69278

Description (problem / solution / changelog)

Summary

• Problem: On a fresh session, the main agent does not respond to user messages. Two reproducible failure modes: (1) the agent replies with the literal string HEARTBEAT_OK, which the delivery runtime treats as "no reply" and sends nothing to the channel (user sees silence); (2) with HEARTBEAT references stripped from AGENTS.md, the agent fabricates "Looks like your message came through as \[object Object]`..."` — a hallucinated serialization error that does not exist anywhere in OpenClaw or the user's actual payload.
• Why it matters: The main agent is completely unresponsive on the first turn of a fresh session. Reproduces via openclaw agent --agent main -m "..." (bypasses all channel plugins), via Telegram DM, on both Sonnet 4 and Opus 4.7, on 2026.4.15 and 2026.4.19-beta.2.
• What changed: Flip the embedded-run trigger policy. The heartbeat system prompt (which instructs the model to reply exactly HEARTBEAT_OK when nothing needs attention) now opts in on the heartbeat trigger only, rather than opting out on cron only and defaulting on for everything else. User, manual, memory, and overflow triggers — plus callers that pass no trigger — no longer inject heartbeat instructions into the system prompt.
• What did NOT change (scope boundary): Heartbeat runs themselves still get the heartbeat prompt (they need it). The HEARTBEAT_OK token filter in the delivery pipeline is untouched. HEARTBEAT.md parsing, heartbeat cron scheduling, and the resolveHeartbeatPromptForSystemPrompt helper are all unchanged.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway / orchestration

Linked Issue/PR

• Closes #69079
• Related: still-open parent #50797 (same symptom class, surfaced on the gateway-poll/user-message race; this fix addresses the underlying trigger policy).
• This PR fixes a bug or regression

Root Cause

• Root cause: src/agents/pi-embedded-runner/run/trigger-policy.ts set DEFAULT_EMBEDDED_RUN_TRIGGER_POLICY.injectHeartbeatPrompt = true and only excluded cron via an explicit entry. Every other trigger (user, heartbeat, manual, memory, overflow) fell through to the default-true path. Callers with trigger: "user" (channels + openclaw agent CLI) therefore got the heartbeat system prompt block injected at src/agents/pi-embedded-runner/run/attempt.ts:733, which includes the instruction "If the current user message is a heartbeat poll and nothing needs attention, reply exactly: HEARTBEAT_OK". Smaller or weaker models (or any model under prompt pressure) fail the conditional and pattern-match on the directive, producing the literal HEARTBEAT_OK output on real user turns. When that instruction is not obviously reachable (HEARTBEAT stripped from AGENTS.md), the same confusion surfaces as the fabricated [object Object] explanation — "object Object" does not exist anywhere in the source tree (verified via grep), confirming the model is hallucinating it while trying to reconcile the heartbeat context with a non-heartbeat message.
• Missing detection / guardrail: no test existed for shouldInjectHeartbeatPromptForTrigger across the full trigger enum. Existing coverage only exercised cron (excluded) and heartbeat / user indirectly via higher-level tests that did not assert the prompt-injection decision.
• Contributing context: the policy shape implied opt-out semantics ("list the triggers that should NOT inject"), which is backwards for this kind of feature — only one trigger should opt in. The original intent was likely "heartbeat only," but the implementation was the inverse.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
• Target test or file: new src/agents/pi-embedded-runner/run/trigger-policy.test.ts
• Scenario the test should lock in: shouldInjectHeartbeatPromptForTrigger("heartbeat") returns true; every other trigger (user, manual, cron, memory, overflow) returns false; absent trigger returns false.
• Why this is the smallest reliable guardrail: the bug is entirely a single boolean decision on a single helper. Asserting the helper's output across the full EmbeddedRunTrigger union is the cheapest, most direct regression lock. Running via attempt.test.ts (106 tests) verifies no downstream behavior breaks.

User-visible / Behavior Changes

Main-agent user turns no longer see the heartbeat system prompt block. Users who reported silent sessions or fabricated [object Object] explanations should get normal replies. Heartbeat-triggered polls continue to work the same way.

Diagram

Before:
user message via channel or CLI
  → trigger = "user"
  → shouldInjectHeartbeatPromptForTrigger("user") = true (default)
  → system prompt includes "reply HEARTBEAT_OK when nothing needs attention"
  → model sees heartbeat instructions on a real user turn
  → outputs literal "HEARTBEAT_OK" (delivery treats as no-reply → silence)
  OR fabricates "[object Object]" explanation (hallucinated reconciliation)

After:
user message via channel or CLI
  → trigger = "user"
  → shouldInjectHeartbeatPromptForTrigger("user") = false (default is off)
  → heartbeat block omitted; model sees a clean user-turn system prompt
  → normal reply

heartbeat poll
  → trigger = "heartbeat"
  → shouldInjectHeartbeatPromptForTrigger("heartbeat") = true (explicit opt-in)
  → heartbeat block included, HEARTBEAT_OK semantics preserved

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS 15 (reporter), reproducible on any platform
• Runtime: OpenClaw 2026.4.15 and 2026.4.19-beta.2
• Model/provider: claude-max via claude-max-api-proxy (openai-completions API). Also reproduces on Sonnet 4 and Opus 4.7 via stock Anthropic routing.
• Integration: CLI (openclaw agent --agent main -m ...) and Telegram DM

Steps

1. Configure the main agent with standard workspace files (SOUL.md, AGENTS.md including heartbeat references, etc.).
2. Run openclaw agent --agent main -m "Pierce here. Status check on project X." --json and grep finalAssistantVisibleText.

Expected

Model returns an actual reply to the user's content.

Actual (before fix)

finalAssistantVisibleText": "HEARTBEAT_OK" or finalAssistantVisibleText": "Looks like your message came through as \[object Object]`..."`. Session jsonl confirms the user's message arrived intact; the model is emitting HEARTBEAT_OK or hallucinating the serialization error.

Evidence

• Failing test/log before + passing after

New test src/agents/pi-embedded-runner/run/trigger-policy.test.ts (7 cases) would have failed on current main for every non-heartbeat trigger. Passes after this change.

Human Verification

• Verified scenarios:
  • pnpm tsgo clean
  • pnpm test src/agents/pi-embedded-runner/run/trigger-policy.test.ts — 7 pass
  • pnpm test src/agents/pi-embedded-runner/run/attempt.test.ts — 106 pass (no regression in downstream attempt logic)
  • pnpm test src/agents/pi-embedded-runner/run/attempt.prompt-helpers.test.ts — 2 pass
  • pnpm test src/auto-reply/reply/session.heartbeat-no-reset.test.ts — 5 pass (heartbeat-reset behavior untouched)
  • pnpm oxlint clean on both changed files
• Edge cases checked:
  • Heartbeat trigger still gets the prompt (explicit opt-in).
  • Cron still does not get the prompt (was explicit exclusion, now falls through the safe default — same result, cleaner policy).
  • Callers without a trigger (defensive): now safely default off rather than silently injecting heartbeat instructions.
  • resolveHeartbeatPromptForSystemPrompt itself is untouched; the helper's output is still wired into heartbeat turns.
• What I did NOT verify:
  • Live repro against claude-max-api-proxy. The unit-level assertion on the trigger policy + the 106 passing attempt tests is sufficient evidence that the reported symptom is gone.

Compatibility / Migration

• Backward compatible? Yes — user-facing behavior improves (agent stops hallucinating heartbeat acks on user turns). Heartbeat semantics unchanged.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: some tests or harnesses might construct embedded runs without a trigger and rely on the old default-true behavior.
  • Mitigation: grepped all call sites of shouldInjectHeartbeatPromptForTrigger and shouldInjectHeartbeatPrompt (the wrapper at attempt.prompt-helpers.ts:98). The only call site is attempt.ts:733, and all runtime callers pass an explicit trigger. The 106-test attempt.test.ts suite still passes, including cases with trigger: "user" and trigger: "heartbeat".
• Risk: removing the explicit cron entry loses documentation of the intended cron behavior.
  • Mitigation: added a block comment explaining the policy — heartbeat only opts in; everything else defaults off. Cron's behavior is preserved through the new default.

Changed files

• src/agents/pi-embedded-runner/run/trigger-policy.test.ts (added, +32/-0)
• src/agents/pi-embedded-runner/run/trigger-policy.ts (modified, +11/-3)