fix(agent/discovery): populate agentAddress on findAgentByPeerId so #700 drain works in production

[branarakic]

TL;DR

This is a live production bug, not just a test gap. Found during the #716 review-consolidation deep-dive audit. PR #700's drainPendingSenderKeyForPeer is a permanent no-op on release/rc.12 because the discovery method it relies on never populates the field it gates on.

3-line fix in discovery.ts + 3 regression tests that would have caught the original bug.

The bug

PR #700 ("Agents Context Graph as distributed phonebook") shipped DKGAgent.drainPendingSenderKeyForPeer (packages/agent/src/dkg-agent.ts:6089-6138) as the recovery loop that replays queued SWM sender keys once a previously-unknown agent's peerId resolves on connection:open. This is the entire point of the pending-by-agent path landed by #700 — without it, sender keys queued for not-yet-resolved agents would never be delivered.

The drain gates on profile?.agentAddress:

```ts
const profile = await this.discovery.findAgentByPeerId(peerId);
if (profile?.agentAddress) {
agentAddresses = [profile.agentAddress.toLowerCase()];
}
...
if (agentAddresses.length === 0) return 0;
```

But DiscoveryClient.findAgentByPeerId (packages/agent/src/discovery.ts:147-218) never populates that field:

• Its scalar SELECT clause omits the `?agentAddress` column (line 163).
• Its return object (lines 209-218) doesn't set the field.

Compare to the sibling `findAgents()` on the same file — that one DOES select and return `agentAddress` (lines 71, 78, 92). The asymmetry between the two discovery entrypoints meant in production:

1. Every `connection:open` → drain attempt early-returned `0`.
2. `pendingSenderKeyByAgent` grew but never replayed.
3. The recovery feature shipped as a permanent no-op.

How CI missed this

`swm-sender-key-pending-by-agent.test.ts` stubbed `discovery.findAgentByPeerId` to return `agentAddress` explicitly (lines 202-209 of the existing file), so the stubbed-discovery tests were green even though the real discovery layer never returns that field.

The fix

3 lines in `discovery.ts`:

• Add `?agentAddress` to the scalar `SELECT`.
• Add the matching `OPTIONAL { ... <${DKG}agentAddress> ... }` clause.
• Populate the field on the returned object.

Now both `findAgents()` and `findAgentByPeerId()` resolve the same identity for the same peer.

Regression tests

1. `test/agent.test.ts` — Discovery Client suite

New test "returns agentAddress on findAgentByPeerId — keeps both discovery entrypoints in lockstep" that:

• Inserts an agent profile with an explicit `agentAddress`.
• Asserts both `findAgents()` AND `findAgentByPeerId()` return the (lowercased) address.
• Pins the legacy-profile-without-agentAddress fallback path (`undefined`, not a throw).

2. `test/swm-sender-key-pending-by-agent.test.ts` — new "real discovery + agent registry CG" `describe` block

Two integration tests that exercise the drain path without stubbing discovery:

a. Boot agent → enqueue pending sender key via the no-peerId path → publish the recipient's profile (real `buildAgentProfile` output → `agent.store.insert`) → call `drainPendingSenderKeyForPeer` with the real `DiscoveryClient` → assert messenger.sendReliable was called and the queue is empty.

b. Same flow but the recipient profile omits `dkg:agentAddress` (legacy profile) → assert drain returns 0, queue stays in place, messenger is never called.

Test (b) would have caught the original bug — every assertion in the all-stubbed path was satisfied even with the broken implementation.

Verification

```
pnpm --filter @origintrail-official/dkg-agent build # clean (tsc no errors)
pnpm --filter @origintrail-official/dkg-agent test # 18/18 SWM sender-key tests pass
# 7/7 Discovery Client tests pass
```

Risk

Low. The discovery query change is additive (one new OPTIONAL clause + one new return field). The drain code was already reading `profile?.agentAddress` — populating that field is what the code already expects.

Source of finding

#716 review-consolidation deep-dive audit (the same audit that surfaced #720's missing call-site coverage that became #735). This bug had no symptom in CI; production would have silently lost sender-key recovery for any agent that wasn't already connected at publish time.

Made with Cursor

[github-actions]

Codex review completed — no issues found.