dsh-cherry-bridge 0.2.0 → 0.2.1

package/src/AGENTS.md

@@ -21,8 +21,9 @@ Pinned at **exact versions**, no `^`, with contract assertions on the pins:
 | `ws` | `8.22.0` |
 | `zod` | `4.3.4` |
 
-These are the versions Cherry Studio **desktop 2.1.8** ships (verified at
-tag `v2.1.8`). Upgrading either protocol package means re-running
+These are the versions Cherry Studio **desktop 2.1.8** ships, and 2.1.9/2.1.10
+still ship the same pair (verified at tags `v2.1.8`, `v2.1.9`, `v2.1.10`).
+Upgrading either protocol package means re-running
 `tests/contract/contract.test.ts` against schema drift — the suite models the
 **six behavioral differences** between our loopback fake peer and a real
 desktop, each mapped to a manual step
@@ -65,6 +66,25 @@ sends `partsMode: 'paged'` only at exactly `1`. Parts keep their clamp; only
 the message page widens (to the negotiated `pageItems`); a
 `RESOURCE_EXHAUSTED` with `details.retryable: false` says retrying cannot help.
 
+**Advertised endpoints (#143).** The hello `connectionEndpointsVersion` bit
+(strictly `1`; absent through 2.1.3 — 2.1.4 already answers both the bit and
+the method) unlocks ONE best-effort
+`connection.endpoints` (`{domain:'agent'}` → `{desktopIdentity, endpoints}`) per
+handshake, awaited INSIDE it after authenticate and bounded by
+`ENDPOINTS_LEARN_TIMEOUT_MS` (2 s). That bound is derived in ONE narrow sense:
+this wait alone stays below `DEVICE_SETTLE_WAIT_MS` (5 s), so a peer that hangs
+on this one call cannot by itself outlive the window a tool waits for
+`connecting` — the handshake's other waits (a 10 s dial, hello/authenticate on
+the 60 s rpc default) already can, and are not this constant's business. The
+desktop gates the call on the authenticated session and can refuse it (gateway
+not running), so EVERY failure is silent — structurally: `#learnEndpoints` wraps
+everything after the capability gate in one `catch` (a refused or wedged call, a
+malformed answer, a throwing assembly hook), and cannot reject. The answer is discarded
+WHOLE when it does not name the pinned `desktopIdentity`, and each entry is
+filtered by the peer's own `advertisedEndpointSchema` (rejects loopback,
+normalizes the host). Learned hosts join the archive as candidates — see
+[Device archive](#device-archive-schemeport-per-host).
+
 **Pacing: two tiers against the desktop's allowances.**
 
 | Tier | Methods | Desktop allowance | Default |
@@ -628,10 +648,13 @@ fallback. The steady-state dial uses `directEndpointUrl` + both maps (`??`):
 candidate's own host/port/scheme, never the record. v2→v3 backfills `ws`,
 v3→v4 `ports` from `port`, atomic on read. Scheme loss breaks a TLS proxy;
 port loss dials the right scheme at the wrong port. Re-typing keeps scheme
-(`securityFor`)/port (`portsFor`); whole-replace `hosts` defaults new hosts to
+(`securityFor`)/port (`portsFor`) CASE-INSENSITIVELY — a re-typed spelling is
+the same address (#189), and a PATCH refuses a list holding two spellings of
+one host; whole-replace `hosts` defaults new hosts to
 `ws`/port; a CHANGED `port` re-points EVERY final host, the current value a map
-no-op (the settings UI sends both on save). `GET /devices` reports both maps
-(addresses, not credentials); tools/diagnostics show only `port`. The settings
+no-op (the settings UI sends both on save). `GET /devices` reports both maps and
+`forgottenHosts` (addresses and intent, not credentials); tools/diagnostics show
+only `port`. The settings
 page shows the per-host ports only when they differ from the record-level one.
 TLS trust is operator config (`wsTls`: FLAT `tls.connect` `rejectUnauthorized`/
 `ca` only), forwarded to both dial sites (pool, pairing). `resolveBridgeConfig`
@@ -639,6 +662,55 @@ validates it: unknown key or unusable value warns by FIELD NAME, WHOLE object
 ignored (half-applied trust reaches some peers, not others). Never persisted,
 logged or reported; `ca` is PEM text.
 
+Addresses a peer ADVERTISES (`connection.endpoints`, #143) are ADD-ONLY
+(`mergeAdvertisedEndpoints`): only hosts the record does not already dial are
+appended, each with its OWN port and scheme (the one-entry-per-host invariant is
+never split), capped at `MAX_CANDIDATE_HOSTS` = 32 — what a pairing QR can
+produce (BOTH arms cap at 32), so learning cannot build a record no pairing
+could have. An existing entry — the operator's port, a TLS proxy — is never
+re-pointed and never removed by LEARNING; comparison is CASE-INSENSITIVE (a
+PATCHed record keeps the operator's spelling), and an IPv6 literal in another
+expansion is not reconciled — the PATCH path owns that spelling. A PATCH that
+drops a host therefore still lets a later handshake re-learn it (the peer is the
+source of truth for its own addresses); the operator's answer is **forgetting**
+(#185): `DeviceStore.forgetEndpoints` (through `cherry_devices`
+`action: "forget"`) removes each named host from `hosts`/`security`/`ports` as
+one unit and records it in the record's OPTIONAL `forgottenHosts`, which the
+merge skips in every case — so a desktop that keeps advertising the address
+cannot put it back. `action: "remember"` lifts the mark (the next handshake may
+then re-add it), and a PATCH whose `hosts` names a forgotten host clears that
+host's mark in the same write: an explicit operator list is intent to dial, and
+`hosts`/`forgottenHosts` are disjoint (`assertValidRecord` refuses the overlap).
+Forgetting the LAST candidate is refused (`LastCandidateHostError`) and writes
+nothing — a record with nothing to dial answers `offline` until a re-pair or a
+PATCH writes a fresh `hosts` list.
+`forgottenHosts` is optional and versionless on purpose: absence means "nothing
+forgotten", an older build ignores the key instead of refusing the archive, and
+no migration (or `schemaVersion` 5) was needed. TWO consequences of that
+compatibility are stated, not implied: a RE-PAIR replaces the record wholesale,
+so it clears every mark (a fresh pairing is a fresh decision — the QR's own
+candidates may reintroduce the address), and a DOWNGRADE can produce the overlap
+the write paths refuse, because the older build preserves the key but cannot
+honour it — the READ path repairs that one state
+(`reconcileForgottenMarks`: keeps the dial list, drops the mark, warns), since
+refusing it would brick every device tool until a 0600 file was hand-edited,
+while `upsert`/`forgetEndpoints`/`rememberEndpoints` stay strict. Both write
+actions EVICT the pooled connection ON A CHANGE, exactly like a PATCH's address
+maintenance, because a `DeviceConnection` captures its record at construction.
+`GET /devices` reports `forgottenHosts` beside the address maps, and since issue
+#204 the settings page shows the marks with a 恢复 each, plus a 忘记 beside every
+dialed host: both ride the two POST routes in the table, call the SAME store
+methods the `cherry_devices` action does, and answer the PATCH's projection. A
+PATCH that includes a marked host still clears its mark, so re-admitting an
+address immediately stays the PATCH's job (恢复 only lifts the mark).
+The write goes through
+`DeviceStore.learnEndpoints`, which merges a clone of the STORED record (never
+the connection's: that one mirrors the live `accessToken`, which this archive
+deliberately does not keep), refuses when the record's `desktopIdentity` is no
+longer the pin the answer was validated against (a re-pair), and writes only
+when a host was added, so a stable desktop costs no archive write per
+reconnect.
+
 ### Pairing: one dial budget across candidates
 
 `desktopIdentity` is decoded at PARSE time with the transport's own
@@ -698,6 +770,8 @@ listener, no LAN exposure, no separate credentials**:
 | --- | --- |
 | `GET /devices` | Device list. |
 | `PATCH /devices/:id` | Update display name / enabled / addresses / port (`hosts` is **whole-replace**). |
+| `POST /devices/:id/forget` | Drop these `hosts` and record the forget marks (the `cherry_devices` action's face, #204). |
+| `POST /devices/:id/remember` | Lift these marks; `hosts` is untouched, so the address returns on the next advertisement. |
 | `DELETE /devices/:id` | Remove the device and tear down its connection. |
 | `GET /scope` | The whole scope state in one body (see below). |
 | `PUT /scope` | Save the scope — read-modify-write, `expectedRevision` required. |
@@ -705,6 +779,17 @@ listener, no LAN exposure, no separate credentials**:
 | `GET /events` | SSE: `device-state` / `pairing-progress`. |
 | `GET /diagnostics` | Operations report (below). |
 
+Device-route refusals (`{error}`; the page branches on the CODE): `forbidden` 403
+(the fence, before routing) · `invalid-request` 400 (malformed body, or a device id
+that is not valid URL encoding) · `last-address` 400 (the action would leave nothing
+to dial; nothing written) · `invalid-device` 400 (the store refused) · `not-found`
+404 (unknown device OR action — also what a QUARANTINED archive answers, its view
+being empty) · `method-not-allowed` 405 (before the body) · `archive-quarantined`
+503 (`{file, corrupt, recovery}`; a damaged archive empties its view and 404s first,
+so this arm only covers a store that refuses after that read — unreachable for the
+shipped store, kept so the arm exists); anything else is the generic 500
+`internal-error`.
+
 > The minimal `pairing-progress` frame shape is `{stage, detail?}`; this plugin
 > **additionally** attaches the optional `claimId` (a cross-run isolation
 > extension, not in the minimal set) — consumers must tolerate its absence.
@@ -816,20 +901,25 @@ refuse; (3) `Origin` present and not same-origin with `Host` → refuse;
 Neither reference is published with this repository.
 
 - **`.scratch-csa`** (gitignored) — the official Cherry Studio **app**
-  (`CherryHQ/cherry-studio-app` @ v0.5.0, read 2026-10-27), the **same role we
+  (`CherryHQ/cherry-studio-app` @ v0.5.2, read 2026-10-31), the **same role we
   play** (protocol *client* against the desktop's server). Its remote layer is
   `src/backend/services/remoteAgent/`; "what the official client does" comes
-  from there. v0.5.0 moved onto our pins (0.7.0 / 0.2.5), whose one behavioural
-  change is the versioned pairing QR.
-- **`_research/cherry-studio`** — the **desktop** source at v2.1.6 (`90b234e`),
-  read alongside v2.1.7, the protocol **server** of record. The faces we depend
-  on are `src/main/services/remoteAccess/` and
+  from there. v0.5.0 moved onto the pinned generation, whose one behavioural
+  change is the versioned pairing QR; v0.5.1 and v0.5.2 changed NOTHING on that
+  face — `git rev-parse <tag>:src/backend/services/remoteAgent` is
+  `16e505fe…` at all three tags, and the pins are still 0.7.0 / 0.2.5. Check
+  that tree hash before believing a new app version changed the wire.
+- **`_research/cherry-studio`** — the **desktop** source, the protocol **server**
+  of record: a shallow `blob:none` clone carrying tags `v2.1.6` (`90b234e`)
+  through `v2.1.10` (`c60cd41a6`). Diff TREES between tags; attribute a change
+  with the GitHub API, not `git log` (the graft hides the range). The faces we
+  depend on are `src/main/services/remoteAccess/` and
   `packages/remote-{protocol,transport}`; `RemoteAccessService.ts` carries both
   rate lines. Gitignored; treated as read-only research.
 - `node_modules/@cherrystudio/remote-protocol` / `remote-transport` are the
   protocol schema source of truth for what we send and decode.
 
-**Verified desktop range: 2.1.4 → 2.1.8.** mDNS, protocol versions (`[1]`) and
+**Verified desktop range: 2.1.4 → 2.1.10.** mDNS, protocol versions (`[1]`) and
 Noise saw **zero changes**; pairing only ADDED the v3 QR arm (below). Notable
 faces:
 
@@ -843,6 +933,7 @@ faces:
 | 2.1.5 keychain-less Linux stores the identity as plaintext 0600; identity is never regenerated | Upgrades need **no re-pairing** |
 | 2.1.7 raises the shared allowance to 256/s and refuses an over-budget request (`RATE_LIMITED` + `retryAfterMs`) instead of closing 1011 | No schema change; our 32/s default already sits far below it |
 | 2.1.8: v3 pairing QR (`bc570d2b9`, PR #21387) — `pairingQrSchema` v2|v3 with custom host/port/security `endpoints`, tightened IPv6; paged message summaries (`54736dc9`/`8bf2fe28d`, PR #21992) advertised by the `agentMessageSummariesVersion` hello capability; server `PAGE_ITEM_BYTES = 62_279` per-item budget | Pairing consumes the published union (#124); summaries are consumed behind the hello capability (#105); a byte-budgeted page may come back SHORTER, which our walk already follows |
+| 2.1.9/2.1.10: **only** `RemoteConnection.send()`'s write chain changed (`16d9487a9`, PR #22593) — `this.writes` keeps its links resolved, so one rejected send no longer makes every later send skip `channel.write`; every other remote-access file and both protocol packages are byte-identical to 2.1.8 | No client change: our answers never depend on the notification stream (list snapshots are the authority), and our own serialized queue (`SecondWindowRateLimiter`) cannot reject |
 | `5db8ab7` (agent runtime DSH → Pi, deleting `packages/dsh-bridge`) | The **opposite** bridge (Cherry driving DSH); unrelated to the remote-access face |
 
 **Traps in the official app (a cautionary list, not a spec).**
@@ -855,6 +946,4 @@ faces:
   plus the cumulative arm.
 - Its read path never replays a read; we replay reads **once** (deliberate
   enhancement) while both sides keep commands receipt-recovered.
-- Its command journal backs command recovery, which is why our commands are
-  never replayed.
 

package/src/connection.ts

@@ -2,7 +2,8 @@ import { randomUUID } from 'node:crypto'
 import { WebSocket } from 'ws'
 import { connectSecureChannel, RemoteSocketStream } from '@cherrystudio/remote-transport'
 import type { ChannelOptions, SecureChannel } from '@cherrystudio/remote-transport'
-import { directEndpointUrl } from '@cherrystudio/remote-protocol'
+import { directEndpointUrl, advertisedEndpointSchema } from '@cherrystudio/remote-protocol'
+import type { DirectEndpoint } from '@cherrystudio/remote-protocol'
 import { isChannelClosedError, JsonRpcClient, JsonRpcRequestError } from './rpc/jsonRpcClient.js'
 import type { JsonRpcRequestOptions } from './rpc/jsonRpcClient.js'
 import { toRemoteSocket } from './rpc/wsAdapter.js'
@@ -14,6 +15,7 @@ import {
   RATE_LIMIT_MAX_WAIT_MS,
 } from './defaults.js'
 import type { DeviceRecord } from './deviceStore.js'
+import { mergeAdvertisedEndpoints } from './deviceStore.js'
 import { clipText, LOG_TEXT_MAX } from './text.js'
 
 /**
@@ -138,6 +140,19 @@ export interface DeviceConnectionOptions {
    * (up to 60s per attempt) to find the desktop again.
    */
   transportRetryWaitMs?: number
+  /**
+   * Where the endpoints a peer ADVERTISES are handed to the assembly for
+   * persistence (issue #143). Called at most once per successful handshake,
+   * with the entries that passed the identity pin and the peer's destination
+   * schema; the connection has ALREADY merged them into `record` (so this
+   * instance's next reconnect dials them) — this hook is the write-back, and the
+   * assembly owns it because the store is not this layer's to touch.
+   *
+   * Absent (tests, or a future caller that only wants the in-memory merge) just
+   * means nothing is persisted. The callback must not throw; one that does is
+   * swallowed with the rest of the enrichment's failures.
+   */
+  onAdvertisedEndpoints?: (endpoints: readonly DirectEndpoint[]) => void
 }
 
 /**
@@ -269,6 +284,35 @@ const DEFAULT_BACKOFF_MAX_MS = 60_000
 const DEFAULT_REFRESH_GRACE_MS = 30_000
 const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
 const DEFAULT_PROTOCOL_VERSIONS: readonly number[] = [1]
+
+/**
+ * How long the optional `connection.endpoints` enrichment (issue #143) may hold
+ * up ONE handshake before the connection gives up on it.
+ *
+ * The call runs INSIDE the handshake, so without a bound of its own it would
+ * inherit the rpc layer's 60 s default: a peer that advertises
+ * `connectionEndpointsVersion: 1` and then never answers (a wedged API gateway)
+ * would keep the device in `connecting` for a minute, and every reconnect would
+ * pay it again. THIS layer bounds it because the enrichment is worth
+ * milliseconds, not a retry.
+ *
+ * WHY 2 s. The peer's handler is a local computation
+ * (`getRemoteEndpoint()`: `networkInterfaces()` plus two config reads), so a
+ * round trip is sub-millisecond on a LAN and 2 s is ~4 orders of magnitude of
+ * slack.
+ *
+ * The UPPER bound is NOT derived from a claim about the whole handshake: a dial
+ * already burns up to `DEFAULT_CONNECT_TIMEOUT_MS` (10 s) and hello/authenticate
+ * ride the rpc layer's 60 s default, so `connected` can arrive long after a
+ * tool's `DEVICE_SETTLE_WAIT_MS` (5 s) wait whatever this constant is. What is
+ * derived is narrower and true: THIS wait alone must stay below that window, so
+ * a peer that advertises the capability and then hangs on this one call cannot
+ * by itself push the state flip past the window a tool already waited out. A
+ * timeout costs one reconnect's worth of enrichment and says nothing about the
+ * device.
+ */
+export const ENDPOINTS_LEARN_TIMEOUT_MS = 2_000
+
 /** Ping-silence multiplier: 2×heartbeatMs without a pong judges the line dead. */
 const SILENCE_FACTOR = 2
 const RATE_WINDOW_MS = 1_000
@@ -378,7 +422,13 @@ class SecondWindowRateLimiter {
     // released strictly after the one before it reached the head.
     let release!: () => void
     const ahead = this.#queue
-    this.#queue = ahead.then(() => new Promise<void>((resolve) => (release = resolve)))
+    // Both arms hand off the same way: a rejected link must still open a slot
+    // for the next waiter. Today no link can reject (each is settled only by
+    // its own `release()` in the `finally` below), so this is a guard rather
+    // than a fix — the desktop learned the shape the hard way when one failed
+    // write silenced every later send on the connection (2.1.9, PR #22593).
+    const next = (): Promise<void> => new Promise<void>((resolve) => (release = resolve))
+    this.#queue = ahead.then(next, next)
     await ahead
     try {
       for (;;) {
@@ -592,6 +642,8 @@ interface HelloResult {
   heartbeatMs?: number
   /** The paged-message-summaries capability (issue #105), when advertised. */
   agentMessageSummariesVersion?: number
+  /** The advertised-endpoints capability (issue #143), when advertised. */
+  connectionEndpointsVersion?: number
 }
 
 interface AuthResult {
@@ -638,6 +690,51 @@ function businessWindowFor(reportedInFlightRequests: number): number {
   return Math.max(1, Math.min(BUSINESS_MAX_IN_FLIGHT, Math.floor(reportedInFlightRequests / 2)))
 }
 
+/**
+ * The destinations a `connection.endpoints` answer may contribute, in the order
+ * the peer listed them (issue #143). Empty when the answer must be discarded.
+ *
+ * TWO answers are refused WHOLE:
+ *
+ *  - **the identity pin.** The answer must name the very desktop this record is
+ *    pinned to (`DeviceRecord.desktopIdentity`). Noise already pins the peer's
+ *    static key, so this is not the adversarial case it protects against — it
+ *    is the defence against a CONFUSED answer (a proxy, a desktop whose identity
+ *    was regenerated, a future protocol that answers for more than one host):
+ *    the list decides where this client dials, so a list that cannot be
+ *    attributed to our own desktop may not change it;
+ *  - a MISSING or NON-STRING `desktopIdentity`: `undefined !== pin`, and a
+ *    number is not the pin either, so both fall out of the same comparison.
+ *
+ * One refusal is per ENTRY: `advertisedEndpointSchema`, the peer's own
+ * destination schema, rejects a LOOPBACK destination (a shared address that
+ * resolves to our own machine would send the next reconnect to the wrong host)
+ * and normalizes the host (case, IPv6), so the archive never stores a spelling
+ * the dial cannot use. One unusable row must not discard its neighbours.
+ *
+ * NOT total on the wire shape, deliberately: a non-object answer or a non-array
+ * `endpoints` throws here, and `#learnEndpoints`' one structural `catch` is what
+ * turns that into the silent no-op the contract promises. Defending each shape
+ * twice would look safer and be worse: the redundancy masks which guard a test
+ * actually pins (issue #114's lesson), and the whole ANSWER is untrusted
+ * anyway, so the boundary belongs at the caller, where the handshake can see
+ * it. `endpoints ?? []` is the one shape that needs no throw: it is the legal
+ * "no addresses right now" answer (the desktop's `addresses` can be empty).
+ *
+ * No length bound is needed here: one JSON-RPC record is capped at 64 KiB by
+ * the transport, and the desktop's own snapshot is `addresses.slice(0, 32)`.
+ */
+function advertisedEndpoints(result: unknown, desktopIdentity: string): DirectEndpoint[] {
+  const answer = result as { desktopIdentity?: unknown; endpoints?: readonly unknown[] | null }
+  if (answer.desktopIdentity !== desktopIdentity) return []
+  const accepted: DirectEndpoint[] = []
+  for (const raw of answer.endpoints ?? []) {
+    const parsed = advertisedEndpointSchema.safeParse(raw)
+    if (parsed.success) accepted.push(parsed.data)
+  }
+  return accepted
+}
+
 /**
  * The desktop's content-read allowance: 512/s, and the SAME in both generations
  * (`RemoteAccessService.ts` counts `agent.content.read` on its own counter,
@@ -738,6 +835,7 @@ export class DeviceConnection {
   readonly #protocolVersions: readonly number[]
   readonly #helloProtocolVersions: readonly number[]
   readonly #transportRetryWaitMs: number
+  readonly #onAdvertisedEndpoints: ((endpoints: readonly DirectEndpoint[]) => void) | undefined
   readonly #stateListeners = new Set<(state: DeviceState) => void>()
   /**
    * Callers parked in {@link waitForSettled}. Separate from the state listeners
@@ -806,6 +904,7 @@ export class DeviceConnection {
     this.#protocolVersions = opts.protocolVersions ?? DEFAULT_PROTOCOL_VERSIONS
     this.#helloProtocolVersions = opts.helloProtocolVersions ?? this.#protocolVersions
     this.#transportRetryWaitMs = opts.transportRetryWaitMs ?? DEFAULT_TRANSPORT_RETRY_WAIT_MS
+    this.#onAdvertisedEndpoints = opts.onAdvertisedEndpoints
   }
 
   /**
@@ -1329,6 +1428,14 @@ export class DeviceConnection {
       throw error instanceof Error ? error : new Error(String(error))
     }
 
+    // The peer's own view of its addresses (issue #143), learned while the link
+    // is AUTHENTICATED — the desktop gates `connection.endpoints` on the
+    // capability of the authenticated session — and BEFORE the epoch gate
+    // below, so a close() landing during the call is caught by that same gate
+    // instead of publishing `connected` on a dead link. Bounded and
+    // failure-tolerant: everything about it lives in `#learnEndpoints`.
+    await this.#learnEndpoints(link, hello.connectionEndpointsVersion)
+
     if (epoch !== this.#epoch) {
       // close() raced the handshake: drop the link quietly (close() already
       // tore down what it could see; this catches the just-dialed socket).
@@ -1381,6 +1488,71 @@ export class DeviceConnection {
     )
   }
 
+  /**
+   * Best-effort enrichment of the dial list from the peer's advertised
+   * endpoints (issue #143).
+   *
+   * WHAT THIS BUYS: candidates the pairing never saw — a VPN or second-NIC
+   * address that appeared after the QR was minted. It does NOT heal a total
+   * address change (the list is captured on the old path) and can never carry
+   * TLS (the desktop's snapshot is `security: 'ws'`), so a `wss` route still
+   * comes from the QR or the operator.
+   *
+   * EVERY failure here is SILENT and non-fatal, because this is an enrichment,
+   * not a verdict: a peer that does not advertise the capability (`connection`
+   * through 2.1.3 has neither the hello bit nor this method), one advertising a
+   * version this client cannot speak (strictly `1` — a higher number is not
+   * evidence that it speaks 1, the same rule the paged-summaries bit took), a
+   * refused call (the desktop throws when its gateway is not running), a wedged
+   * one (bounded by {@link ENDPOINTS_LEARN_TIMEOUT_MS}), an unattributable
+   * answer, or a store that cannot write. None of them is a CONNECTION failure:
+   * the link comes up either way, and only the archive is left without the new
+   * addresses — this instance's own record may already carry them, because the
+   * merge runs before the callback (see the paragraph below).
+   *
+   * The MERGE happens in two places on purpose: here (this instance's record,
+   * so its next reconnect dials the new address) and through the callback (the
+   * assembly's archive, so a restart keeps it). They are the same pure rule
+   * against two copies of the record, and each is idempotent.
+   *
+   * ONE `catch` covers everything after the gate, and that is the contract, not
+   * laziness: a refused call, a wedged one (bounded by
+   * {@link ENDPOINTS_LEARN_TIMEOUT_MS}), an answer of the wrong SHAPE (the
+   * parser throws rather than defending every field twice), a throwing assembly
+   * hook (an unwritable archive), or a bug in the merge must all land here —
+   * none of them may fail the handshake. The observable promise is therefore
+   * structural: this method cannot reject.
+   */
+  async #learnEndpoints(link: LiveLink, capability: number | undefined): Promise<void> {
+    if (capability !== 1) return
+    try {
+      const answer = await this.#houseCall<unknown>(
+        link,
+        'connection.endpoints',
+        { domain: 'agent' },
+        ENDPOINTS_LEARN_TIMEOUT_MS,
+      )
+      const endpoints = advertisedEndpoints(answer, this.record.desktopIdentity)
+      if (endpoints.length === 0) return
+      const added = mergeAdvertisedEndpoints(this.record, endpoints)
+      if (added > 0) {
+        // Count only: a host is peer-supplied text, and the logging rule clips
+        // peer text at the render site (src/AGENTS.md). deviceId is exempt.
+        console.info(
+          `[cherry-remote] device ${this.record.deviceId} learned ${added} advertised endpoint(s)`,
+        )
+      }
+      this.#onAdvertisedEndpoints?.(endpoints)
+    } catch {
+      // Silent by contract. The failure modes are all "this desktop does not
+      // want to tell us today" (or "this archive cannot take it"), and a log
+      // line per reconnect would be noise on a device that is otherwise
+      // perfectly healthy. One bounded line cannot be produced here anyway: the
+      // cause may be the peer's own answer text, which src/AGENTS.md clips at
+      // the render site — and this line would have to run on every connect.
+    }
+  }
+
   /**
    * authenticate with the stored token; a stale token (TOKEN_EXPIRED /
    * UNAUTHENTICATED) is retried exactly once without it before the pairing