# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

When two registrations for the same agent name existed on the Threadline relay — a live one and a
stale leftover (a "dead twin") — a sender resolving that name could land on the dead one, and its
messages silently vanished (delivered-but-never-received). The fix is in the client name resolver
(`ThreadlineClient`): each known agent now carries a live/offline flag (sourced from the live
presence status the relay already reports), name resolution **prefers the single live registration**,
re-discovers a stale cache so a dead twin can't win, and — when two registrations are *genuinely*
both live (a real two-machine agent, or an impostor) — surfaces a disambiguation prompt instead of
silently guessing. A companion change removes the dead code (`loadOrCreateIdentityKeys`) that minted
the orphan identity which became the dead twin in the first place, so no new duplicates are created
fleet-wide. No relay deploy is required — the relay already reported the right information; the client
was discarding it.

## What to Tell Your User

If another agent reported that messages to you were "going through on their side but never arriving"
— the classic symptom of a wedged agent-to-agent channel — this fixes it: your peer's software now
resolves your name to your live address instead of a stale duplicate. You don't need to do anything;
it takes effect after your agent updates and restarts. In the meantime, a peer can always reach you
by addressing your exact routing fingerprint instead of your name. If a peer ever gets an "ambiguous
agent name" prompt, that's intentional — it means two live registrations share your name, and they
should pick by fingerprint.

## Summary of New Capabilities

This is a reliability/correctness fix, not a new feature — agent-to-agent name resolution now lands
on the live registration and never silently delivers to a dead duplicate. Agents also stop creating
an unused orphan identity file on boot.

## Evidence

- 17 unit tests drive the real on-path resolver (`ThreadlineClient.resolveAgent` / `findAgentByName`):
  live-vs-dead → resolves live; two-online → surfaces ambiguity; offline-only cache → re-discovers;
  merge retains crypto keys; rate-limit early-resolve; partial-match parity.
- 1 relay-backed end-to-end test stands up a real relay with a live + a dead "echo" and asserts a
  sender resolves the name to the live fingerprint, never the dead twin.
- 12 `ThreadlineBootstrap` unit tests (incl. "does NOT create identity-keys.json" + a CI guard that
  the orphan-minting cannot be re-introduced). Typecheck clean; 1693 existing threadline tests green.
- Spec (converged iter 3, approved): `docs/specs/threadline-duplicate-identity-resolution.md`;
  side-effects review with independent second-pass CONCUR.
