Fresh-link first outbound sometimes not delivered until inbound (old counter); guidance on key/session readiness?

Summary

In production linked-device usage, we observe two related behaviors:

1. LID->PN mappings exist in whatsmeow_lid_map, but app-layer clients often still expose opaque @lid identities unless they manually join/map.
2. After fresh link, first outbound message to some contacts may appear sent but is not received until recipient sends inbound first (then delivery works).

I know some LID threads already exist; this report adds a concrete field observation from a fresh deployment.

Environment

• WhatsApp linked-device session (QR)
• Client stack using whatsmeow (via wacli)
• Linux host

Repro (delivery gap)

1. Freshly link device.
2. Send outbound text to contact A.
3. Sender sees successful send/outbox entry.
4. Contact A does not receive.
5. Contact A sends any inbound message.
6. Subsequent outbound messages to A deliver successfully.

Relevant log seen

SessionCipher.go:310 Unable to get or create message keys: received message with old counter (index: 2, count: 1)

Observed

• A key/session readiness mismatch seems possible immediately after linking for some peers.
• Behavior looks like key ratchet/session repair occurs after inbound traffic.

Expected

• First outbound after successful link should reliably deliver.
• If not possible, API should expose clearer pre-send key/session status or a recommended handshake/retry flow.

LID mapping note

whatsmeow_lid_map is extremely useful and does contain real mappings in our case. A short best-practice note in docs for app developers (when/how to apply map to chat identity display) would help many downstream tools.

Ask

• Any recommended canonical flow for ensuring key/session readiness right after fresh link?
• Is the old counter condition expected transient behavior or a bug to track?
• Recommended retry/backoff/session-reset strategy?