tai/taicpp/problem.md

# Open problem: the phone never sends the app-state sync key to a newly linked companion

Date: 2026-10-28. Client: detz 1.45.0 (`src/whatsapp/`, namespace `detz::wa`), a C++ WhatsApp companion
written from scratch after whatsmeow (Go). Device in the last test: `31630045827:54`.

## In one sentence

A newly linked companion device logs in and sends fine, but the phone never sends it the app-state sync key.
Without that key the address book (collection `critical_unblock_low`) cannot be decrypted, so no contact
names arrive.

## What works (confirmed by the user on the phone)

- QR pairing, automatic restart (`stream:error 515`), login, upload of 50 prekeys.
- Sending an image to the user's own number; it shows in "Message yourself".
- Our participant hash equals the server's (`2:TKwG4B1n`), so the device list we send to is correct.

## What does not work

Every login runs the contact sync. The log shows:

```
app state critical_unblock_low: missing app state key for the snapshot
app state critical_unblock_low: version 0, 0 patches, 0 contacts saved, 0 removed, 0 unnamed
app state keys: requesting 1 from the phone
app state: no key share arrived; contacts will sync on a later login
```

I then stayed connected for 100 to 120 seconds with a trace of every incoming node
(`DETZ_WA_TRACE=1`), after clearing our own 24-hour limit on key requests. The only nodes that arrived were
`<success>`, `<ib edge_routing>` and `<ib dirty type=account_sync>`. No `<message>` node arrived at all.
The database holds 0 app-state keys and one Signal session, with the phone's LID address
`173735822786802.0`, created by our own sends.

## What the code does

1. Login succeeds. We request the collection `critical_unblock_low`; the server's reply shows a key is needed.
2. We send a peer message (`category="peer"`, `push_priority="high"`) to the user's own account. It contains a
   protocol message of type `APP_STATE_SYNC_KEY_REQUEST` and is encrypted to the phone's LID identity.
3. We wait 20 seconds for the phone's `APP_STATE_SYNC_KEY_SHARE`. Nothing arrives.

Registration now carries `DeviceProps.historySyncConfig` with whatsmeow's values (added after a first failed
attempt; the device was re-linked afterwards).

## Checked against the reference

Pairing reply, media upload, key derivation and the key-request bytes match whatsmeow. The app-state crypto
(HKDF key expansion, LTHash, MACs) passes against an oracle built from whatsmeow's own packages. The data path
is not the problem: the key never arrives, so nothing has been decrypted from real data yet.

## Hypotheses, none confirmed

1. The phone cannot decrypt or accept our key request. The server acknowledges it, but an ack only means the
   server took it. Related reports: whatsmeow PR 1268 and Volt-Chat PR 5 describe key requests that never leave
   the process without a Signal session to the phone; WhatsApp Web ensures that session before sending.
2. The phone pushes keys only once, right after pairing, and that happened inside the link session, which I
   never traced. If messages arrived then and our handler dropped or failed them silently, the keys are lost.
   Checkable by logging everything during a fresh link.
3. The phone is not answering for another reason: in the background or battery-restricted, WhatsApp not open.
   Reports also exist of the phone answering with an empty key (openclaw/wacli PR 443).
4. A classification issue like the one in Rich627/whatsapp-claude-plugin PR 45: peer messages from the phone
   have no `recipient` attribute and were dropped as spoofed. That explains missing keys there, but here no
   `<message>` arrives at all, so it is not our case yet.

## Questions for an expert

- On a fresh link, does the primary phone always push the key share and history to the new companion without
  being asked? What does it key that on (device props, `platformType`, client version)?
- Is a peer key request encrypted to the LID identity of device 0 enough, or must a Signal session with the
  phone already exist from an earlier exchange?
- Does the phone answer key requests from a device that has not yet received the initial history sync?
- Is anything in the 2026 pairing flow, such as the `jurisdiction` and `encryption-metadata` nodes seen in
  `pair-success` for a Dutch number, related to when keys are shared?

## Sources

- https://github.com/tulir/whatsmeow/pull/1268
- https://github.com/Volt-Chat/whatsmeow/pull/5
- https://github.com/openclaw/wacli/pull/443
- https://github.com/Rich627/whatsapp-claude-plugin/pull/45
- Research archive: `research/whatsapp-automation/` (whatsmeow-appstate-sync.md, whatsmeow-key-share-and-peer-messages.md,
  whatsmeow-device-props-history-sync.md)

## Fallback

Import the contacts from a `.vcf` file exported on the phone, into the existing contact search. Built: `detz --whatsapp-import contacts.vcf` (see `WaVcf`, docs section 14).

## Resolution (2026-10-27, detz 1.46.0)

The request path was verified line by line against whatsmeow main (`send.go`, `message.go`, `appstate.go`,
`notification.go`, `client.go`, `pair.go`, `store/clientpayload.go`, fetched 2026-10-27). Registration, login,
DeviceProps, the peer node, the key-request bytes and the padding all match the reference. Eight local gaps were
fixed anyway (docs section 16 has the table): 24 h rollback on send failure (whatsmeow PR 1268), verified peer
send (Volt-Chat PR 5), pkmsg-only device-identity, LID senders accepted plus an arrival log before the filter,
empty shares distinguished from silence (openclaw/wacli PR 443), notification/receipt handling, `--whatsapp-sync`
(300 s online for a sleeping phone), and the `--whatsapp-import` fallback. `build/whatsapp_test` covers the new
behavior; the live answer still needs the phone.

Answers to the questions above, from the reference source (not from the phone, which is still unseen):

- Fresh link, unsolicited push: yes, the phone pushes the initial history sync and the key shares on its own once
  it notices the new companion (that is the initial sync `historySyncConfig` declares support for). Re-requests are
  answered too in a healthy setup (whatsmeow `requestMissingAppStateKeys` sends them on every fetch with missing
  keys); reports of "just once" come from clients that dropped the first push.
- Session before the peer request: yes, required. whatsmeow `encryptMessageForDevice` returns `ErrNoSession` when
  no session exists and the message never leaves the process. We now verify the session exists after the prekey
  fetch and say so loudly when it does not.
- Requests before the initial history sync: answered in principle (wacli sees even empty shares), but a phone that
  is asleep or battery-restricted answers nothing until it wakes; that is what `--whatsapp-sync` (300 s) is for.
- `jurisdiction` / `encryption-metadata` in `pair-success`: server-side account metadata, ignored by whatsmeow
  `handlePairSuccess` like any unknown child. Not related to key sharing.

Next step if keys still do not arrive: run `detz --whatsapp-sync` with WhatsApp open on the phone and no battery
restriction. A 300 s trace with no `<message>` proves the gate is on the phone's side; import the .vcf meanwhile.