Heartbeat sessions receive empty exec completion notifications due to sessionKey mismatch

Description

Heartbeat sessions frequently receive exec completion notifications without the actual command output, causing the model to respond with confusion messages like:

I don't see any system messages or command output in the current context. 
This appears to be a completion notification without attached results.
Could you share what command was run, or if there's output I should be seeing?

This is caused by a sessionKey mismatch in the event routing logic between parent sessions and isolated heartbeat sessions.

Environment

• OpenClaw Version: 2026.4.15 (041266a)
• Node Version: v24.13.1
• OS: Linux (WSL2)
• Affected Sessions:
  • agent:main:main:heartbeat
  • agent:main:cron:*:heartbeat
  • agent:main:feishu:group:*:heartbeat

Reproduction Steps

1. Start a background exec command in a main session (e.g., agent:main:main)
2. Wait for the command to complete
3. The system triggers a heartbeat wake with reason: "exec-event"
4. Observe the heartbeat session (agent:main:main:heartbeat) receives the prompt but no system messages

Expected Behavior

When a background exec command completes:

1. The completion event should be enqueued to the heartbeat session
2. The system messages (command output) should be available in the heartbeat context
3. The model should be able to see and relay the command output

Actual Behavior

1. The completion event is enqueued to the parent session (agent:main:main)
2. The heartbeat runs in an isolated session (agent:main:main:heartbeat)
3. peekSystemEventEntries(isolatedSessionKey) returns an empty array
4. But hasExecCompletion detects an event (possibly from parent session check)
5. The prompt is built: "An async command you ran earlier has completed..."
6. The model receives the prompt but finds no system messages in context
7. The model responds with confusion

Root Cause Analysis

Call Chain

exec background task completes
  ↓
enqueueSystemEvent(text, { sessionKey: "agent:main:main" })
  ↓
requestHeartbeatNow({ sessionKey: "agent:main:main", reason: "exec-event" })
  ↓
runHeartbeat(isolatedSessionKey: "agent:main:main:heartbeat")
  ↓
peekSystemEventEntries("agent:main:main:heartbeat") → []
  ↓
hasExecCompletion detects event (from parent session?)
  ↓
buildExecEventPrompt() → "An async command you ran earlier has completed..."
  ↓
Model: "I don't see any system messages..."

Affected Code Files

1. bash-tools.exec-runtime-DNTWYnIA.js - maybeNotifyOnExit function

   enqueueSystemEvent(output ? `Exec ${status} (${session.id.slice(0, 8)}, ${exitLabel}) :: ${output}` : ..., {
     sessionKey,  // This is the parent session key
     deliveryContext: session.notifyDeliveryContext,
     trusted: false
   });
   requestHeartbeatNow(scopedHeartbeatWakeOptions(sessionKey, { reason: "exec-event" }));

2. heartbeat-runner-CInrztfM.js - resolveHeartbeatRunPrompt function

   const pendingEventEntries = peekSystemEventEntries(session.sessionKey);
   // session.sessionKey is the isolated heartbeat session key
   const hasExecCompletion = pendingEvents.some(isExecCompletionEvent);

3. system-events-Dq_M0n12.js - Event queue management

   function peekSystemEventEntries(sessionKey) {
     return getSessionQueue(sessionKey)?.queue.map(cloneSystemEvent) ?? [];
   }

Impact

• Frequency: Observed 6 times in production
• Affected Sessions: 29 sessions
• User Experience: Creates noise and confusion in heartbeat responses
• Severity: Medium (workaround available, but degrades heartbeat quality)

Proposed Solutions

Solution 1: Fix Event Routing (Recommended)

Copy events from parent session to heartbeat session when triggering heartbeat:

function requestHeartbeatNow(options) {
  const baseSessionKey = options.sessionKey;
  const heartbeatSessionKey = `${baseSessionKey}:heartbeat`;
  
  // Copy events to heartbeat session
  const events = peekSystemEventEntries(baseSessionKey);
  for (const event of events) {
    enqueueSystemEvent(event.text, {
      sessionKey: heartbeatSessionKey,
      deliveryContext: event.deliveryContext,
      trusted: event.trusted
    });
  }
  
  // Trigger heartbeat
  runHeartbeat(heartbeatSessionKey);
}

Solution 2: Fix Event Check Logic

Check parent session's event queue in heartbeat:

function runHeartbeat(isolatedSessionKey) {
  const baseSessionKey = isolatedSessionKey.replace(/:heartbeat$/, '');
  
  // Check events from parent session
  const pendingEventEntries = peekSystemEventEntries(baseSessionKey);
  
  if (pendingEventEntries.length > 0) {
    // Inject events into current context
    injectSystemMessages(pendingEventEntries);
  }
}

Solution 3: Fix Prompt Building Logic

Verify events exist in current session before building prompt:

const pendingEventEntries = peekSystemEventEntries(session.sessionKey);
const hasExecCompletion = pendingEventEntries.some(isExecCompletionEvent);

// Only build prompt if current session actually has events
if (hasExecCompletion && pendingEventEntries.length > 0) {
  prompt = buildExecEventPrompt();
}

Workaround

Added exception handling in HEARTBEAT.md:

### Exception Handling
- **When receiving "An async command you ran earlier has completed" but no system messages in context**:
  - This is a known OpenClaw bug (sessionKey mismatch in event routing)
  - Reply with `HEARTBEAT_OK` directly
  - Do not attempt to explain, ask, or relay non-existent output
  - Do not create noise

This prevents the model from generating confusion messages, but doesn't fix the underlying routing issue.

Additional Context

• This issue only affects isolated heartbeat sessions (:heartbeat suffix)
• Parent sessions receive and process exec completion events correctly
• The issue is deterministic and reproducible with background exec commands
• No data loss occurs; events remain in parent session queue

Related Files

• dist/bash-tools.exec-runtime-DNTWYnIA.js
• dist/heartbeat-runner-CInrztfM.js
• dist/system-events-Dq_M0n12.js

Logs

Example session showing the issue:

{
  "type": "message",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "An async command you ran earlier has completed. The result is shown in the system messages above. Please relay the command output to the user in a helpful way."
      }
    ]
  }
}

But peekSystemEventEntries(heartbeatSessionKey) returns [].

Would appreciate any guidance on the preferred fix approach! Happy to submit a PR if you can point me to the right direction.