feat(agentMentionService): inline reply-mechanics cue (heartbeat-clobber mitigation)

[samxu01]

Summary

Kernel-side mitigation for the openclaw heartbeat-clobbers-mention bug (3 reproductions in smoke 2026-05-20: Nova c3, Pixel c7, Ops c7). Adds a tight inline cue to every chat.mention payload.content telling the model to commit its reply via explicit commonly_post_message BEFORE returning its final assistant turn.

The bug

When an openclaw agent processes a chat.mention AND a heartbeat trigger fires in the same model session before the mention reply is committed, the openclaw run-loop's final-turn auto-post emits the heartbeat's HEARTBEAT_OK (the LAST assistant turn) and clobbers the in-flight mention answer. Nova's session log proves it: she produced a 7-row table in assistant content, her next assistant turn was HEARTBEAT_OK, and the table never landed in chat.

The cue

[Reply mechanics: post your reply by calling commonly_post_message(
 { podId: "...", content: <your-reply> }) as soon as it's ready,
 BEFORE returning your final assistant turn. Do NOT rely on the
 implicit final-turn auto-post — a heartbeat trigger arriving
 mid-session can overwrite your final turn with HEARTBEAT_OK and
 your reply will never reach the pod (openclaw heartbeat-clobber-
 mention bug, 3 reproductions 2026-05-20). Post-then-stop is the
 safe sequence.]

Scoping

Added ONLY to chat.mention events. thread.mention replies post via a different path on the openclaw side (thread comments aren't subject to the same final-turn auto-post race), so the cue would be noise there.

Why not upstream fix

Upstream fix in the openclaw fork is a larger change (session-key per-event-type, OR a final-turn selector that prefers mention-reply over heartbeat-reply when both produced output). That's worth doing, but this kernel-side mitigation is independent — it works even if the model is the only thing that changes behavior. Once committed via tool call, the heartbeat trigger is harmless.

Token cost

~80 tokens per chat.mention. Tradeoff is acceptable against silent-loss of mention replies — the smoke had 3 cases where good answers vanished.

Test plan

• 2 new tests in agentMentionService.test.js:
  • chat.mention payload includes both pod-context AND reply-mechanics cues, original message preserved
  • thread.mention payload includes pod-context only (reply-mechanics OMITTED)
• CI green
• Manual smoke: after deploy, post @nova task; check her session log for the cue inline; verify she calls commonly_post_message explicitly (not relying on auto-post)

Merge-order note

Textually overlaps with PR #416 (cross-runtime consultation cue, same function file). Both touch the content-build expression in enqueueMentions. Whichever lands second needs a small rebase to compose both cues — they're independent in intent and can stack cleanly.

🤖 Generated with Claude Code

[samxu01]

Superseded by PR #420 (unified inline cue composition). #420 incorporates this reply-mechanics cue + #416's consultation cue with correct chat.mention-only gating. Mechanically incompatible with #416 — landing both standalone would conflict. Closing.