Summary

• Problem: older in-flight foreground auto-reply runs could deliver a final reply after a newer inbound message started for the same session target.
• Why it matters: messaging channels can show stale tool-turn completions as if they answered the latest user message.
• What changed: added a shared buffered-dispatch freshness guard that suppresses superseded foreground replies before delivery.
• What did NOT change (scope boundary): no provider replay/cache behavior, WhatsApp-specific routing, or background completion notification semantics were changed.

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: Stale Tool-Turn Finalization Delivered After Newer WhatsApp Message #76905
• Related #
• This PR fixes a bug or regression

Real behavior proof

• Behavior or issue addressed: older in-flight foreground auto-reply finals are suppressed when a newer inbound WhatsApp-style turn starts for the same channel/account/session/target before the older final is delivered.
• Real environment tested: Linux container in /root/mkdev11/openclaw, Node v22.22.1, pnpm 10.33.2, PR branch fix/issue-76905-whatsapp-stale-final at 92148e40c818bdca1d9e5ef3554712159eddae40.
• Exact steps or command run after this patch: Ran a local Node harness with node --import tsx -e that imported the real dispatchInboundMessageWithBufferedDispatcher, created two finalized WhatsApp-style inbound contexts for the same session target, held the older reply resolver until after the newer dispatch completed, then released the older final.
• Evidence after fix: Terminal output from the real dispatch module run:

{
  "newerResult": {
    "queuedFinal": true,
    "counts": {
      "tool": 0,
      "block": 0,
      "final": 1
    }
  },
  "olderResult": {
    "queuedFinal": false,
    "counts": {
      "tool": 0,
      "block": 0,
      "final": 0
    }
  },
  "deliveries": [
    {
      "kind": "final",
      "text": "new final"
    }
  ]
}

• Observed result after fix: The newer final was delivered, the older final was not delivered, and the older dispatch reconciled to queuedFinal=false with counts.final=0.
• What was not tested: A live WhatsApp account plus live provider race was not replayed; this proof exercises the real shared OpenClaw buffered dispatch path with local WhatsApp-style contexts and a deterministic delayed resolver.
• Before evidence (optional but encouraged): Before this patch, the shared buffered dispatch path had no foreground freshness fence, so an older final could still enter delivery after a newer same-target turn began.

Root Cause

• Root cause: buffered foreground reply delivery did not verify that the originating inbound turn was still the newest active turn for the same channel/account/session/target before delivering a final payload.
• Missing detection / guardrail: no shared freshness guard existed in the generic auto-reply delivery path.
• Contributing context (if known): active-run steering can record a newer inbound message while an older tool-backed run is still finalizing.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/auto-reply/dispatch.freshness.test.ts
• Scenario the test should lock in: an older foreground final is suppressed after a newer inbound turn starts for the same session target.
• Why this is the smallest reliable guardrail: it exercises the shared buffered dispatch path directly without requiring live WhatsApp or provider timing.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Older stale foreground replies are suppressed when a newer inbound message starts for the same channel/account/session/target before the older dispatch finalizes.

Diagram

Before:
message A -> long tool run -> message B starts -> final from A is delivered

After:
message A -> long tool run -> message B starts -> final from A is suppressed

Security Impact

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: local checkout
• Model/provider: N/A
• Integration/channel (if any): shared auto-reply dispatch; regression models WhatsApp-style foreground context
• Relevant config (redacted): default test config

Steps

1. Start a foreground buffered dispatch for one session target.
2. Start a newer foreground buffered dispatch for the same session target before the older final is delivered.
3. Let the newer final deliver, then let the older final attempt delivery.

Expected

• The newer final is delivered.
• The older final is cancelled before delivery and removed from queued final counts.

Actual

• Matches expected with the new regression test.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • stale same-session same-target final is suppressed
  • concurrent different-target finals sharing a session are not suppressed
  • existing dispatch lifecycle tests still pass
• Edge cases checked:
  • missing or different target keys do not collide
  • cancellation reconciles queued final counts
  • repo formatting and changed-file checks pass
• What you did not verify:
  • live WhatsApp plus Codex provider reproduction

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: the guard could suppress a reply that intentionally completes after a newer foreground message.
  • Mitigation: the key is scoped by channel, account, session, chat type, and target, and only applies to the shared foreground buffered delivery path.