dsh-cherry-bridge 0.1.11 → 0.2.1

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 { remoteConnectPath } 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'
@@ -13,8 +14,9 @@ import {
   DEFAULT_TRANSPORT_RETRY_WAIT_MS,
   RATE_LIMIT_MAX_WAIT_MS,
 } from './defaults.js'
-import { urlHost } from './urlHost.js'
 import type { DeviceRecord } from './deviceStore.js'
+import { mergeAdvertisedEndpoints } from './deviceStore.js'
+import { clipText, LOG_TEXT_MAX } from './text.js'
 
 /**
  * Per-device persistent connection: the M1 capstone that owns the WebSocket,
@@ -36,13 +38,59 @@ export interface EffectiveLimits {
   subscriptions: number
   pageItems: number
   inFlightRequests: number
+  /**
+   * The peer's hello-advertised `agentMessageSummariesVersion` (issue #105),
+   * stored BESIDE the limits because it is re-read by that same handshake.
+   *
+   * ABSENT, never defaulted: through desktop 2.1.7 the field does not exist,
+   * and 0.5.0's `agent.messages.list` params are a STRICT object with no
+   * `partsMode` — sending it to such a peer is a protocol violation, so absence
+   * has to be distinguishable from every number. `1` (2.1.8, where
+   * `RemoteConnection.ts:69` sets it unconditionally) is the only version that
+   * means "the summary arm is available"; any other number is stored verbatim
+   * and read as not-yet-known, because a version this client cannot speak is
+   * not evidence that it speaks 1.
+   *
+   * Re-read on EVERY hello, so a desktop upgraded between two handshakes is
+   * picked up on the reconnect that follows.
+   */
+  messageSummaries?: number
 }
 
+/**
+ * Options handed to every `WebSocket` dial (issue #126).
+ *
+ * FLAT `tls.connect` options — `ws` forwards its own option bag straight to
+ * `tls.connect`, so `{ rejectUnauthorized: false }` or `{ ca: <pem> }` belong
+ * at the top level rather than under a `tls:` key.
+ */
+export type WsDialOptions = { rejectUnauthorized?: boolean; ca?: string | Buffer | Array<string | Buffer> }
+
 export interface DeviceConnectionOptions {
   /** Local Ed25519 device identity (raw protobuf private key bytes). */
   identity: Uint8Array
-  /** The paired device record; `hosts`/`port` are re-read on every attempt. */
+  /**
+   * The paired device record; `hosts`/`security`/`ports`/`port` are re-read on
+   * every attempt. `security` and `ports` are REQUIRED by schemaVersion 4 (the
+   * v2→v3 and v3→v4 migrations backfill them), so the `?.` in the STEADY-STATE
+   * dial guards an in-memory record assembled without the map (or constructed
+   * before validation), not a migrated one. That dial — this class — consumes
+   * both per-host maps; the pairing dial never reads the record (it dials the
+   * QR candidate's own host/port/scheme, which is why the record can persist
+   * them). Each host dials with its OWN port; the record-level `port` is the
+   * winner's at pairing, the operator's after a PATCH, and always the fallback.
+   */
   record: DeviceRecord
+  /**
+   * Options for every dial's `WebSocket` (issue #126) — in practice
+   * `rejectUnauthorized`/`ca`, for a desktop behind a TLS proxy whose
+   * certificate is not in Node's default trust store. The assembly injects it
+   * from plugin config `wsTls` at BOTH dial sites (the pool and pairing); tests
+   * may still pass it directly. Absent means Node's defaults. NEVER derived
+   * from the record: trust is a grant the OPERATOR makes, not a fact the
+   * desktop asserts about itself.
+   */
+  wsOptions?: WsDialOptions
   /**
    * Second-level smoothed request budget for business RPCs on the SHARED tier
    * — every business RPC except `agent.content.read`, which has its own tier
@@ -92,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
 }
 
 /**
@@ -223,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
@@ -332,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 (;;) {
@@ -544,6 +640,10 @@ interface HelloResult {
   protocolVersion?: number
   limits?: Record<string, number>
   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 {
@@ -590,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,
@@ -690,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
@@ -740,8 +886,11 @@ export class DeviceConnection {
   #token: string | undefined
   #tokenExpiresAt: number | undefined
 
+  readonly #wsOptions: WsDialOptions | undefined
+
   constructor(opts: DeviceConnectionOptions) {
     this.record = opts.record
+    this.#wsOptions = opts.wsOptions
     this.#identity = opts.identity
     this.#limiter = new TieredRateLimiter(
       opts.rateBudgetPerSecond ?? DEFAULT_RATE_BUDGET_PER_SECOND,
@@ -755,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
   }
 
   /**
@@ -967,6 +1117,10 @@ export class DeviceConnection {
     if (error instanceof IdentityMismatchError) {
       this.#running = false
       this.#setState('identity-mismatch')
+      // DELIBERATELY not clipped: this message is a COMPILE-TIME LITERAL
+      // ("peer static key does not match the pinned desktopIdentity") with no
+      // peer bytes in it, so there is nothing here to bound. The other two
+      // error lines below interpolate text the peer controls.
       console.error(
         `[cherry-remote] device ${this.record.deviceId}: ${error.message}; ` +
           'marked identity-mismatch and disconnected — re-pair the device',
@@ -978,9 +1132,19 @@ export class DeviceConnection {
     if (error instanceof ProtocolVersionError) {
       this.#running = false
       this.#setState('offline')
+      // BOUNDED (issue #155): the `cause` is the peer's OWN hello-echo text —
+      // `ProtocolVersionError` is built from `String(<the peer's RPC failure>)`
+      // — so the message can carry up to a whole 64 KiB record of peer text.
+      // Ceiling: 56 fixed characters + the `deviceId` + LOG_TEXT_MAX (240,
+      // marker included) + the 37-character upgrade suffix. The id is
+      // deliberately NOT clipped (a whitelisted identifier an operator
+      // correlates on), and it is peer-assigned (`pairing.get`'s approved
+      // result, `opaqueId` ≤ 256), so the bound moves with it: 8-character
+      // fixture id → 341; a 36-char UUID → 369; the schema worst case (256) →
+      // 589.
       console.error(
         `[cherry-remote] device ${this.record.deviceId}: protocol version incompatible ` +
-          `(${error.message}); upgrade Cherry Studio / the plugin`,
+          `(${clipText(error.message, LOG_TEXT_MAX)}); upgrade Cherry Studio / the plugin`,
       )
       this.#cycle.reject(new Error(`device ${this.record.deviceId}: protocol version incompatible`))
       return
@@ -1014,9 +1178,19 @@ export class DeviceConnection {
         ? ' — all candidate addresses were unreachable; if the desktop moved, update ' +
           'them via the device card 地址维护 (address maintenance)'
         : ''
+    const detail = error instanceof Error ? error.message : String(error)
     console.warn(
       `[cherry-remote] device ${this.record.deviceId} offline ` +
-        `(${error instanceof Error ? error.message : String(error)}); reconnecting in ${delay}ms${hint}`,
+        // BOUNDED (issue #155): this text is peer-influenced — an RPC failure
+        // carries the peer's own `error.message` verbatim (an authenticate
+        // refusal, a hello fault), and a transport error carries the system's.
+        // Only the 64 KiB record budget bounded it before. Ceiling: 33 fixed
+        // characters + the `deviceId` + LOG_TEXT_MAX (240, marker included) +
+        // `); reconnecting in <delay>ms` (26 at the 60,000 ms backoff cap) +
+        // the all-hosts hint (125). The id is NOT clipped (same decision as
+        // above), so a 36-char UUID gives 460 and the schema worst case (256)
+        // gives 680, against 432 for the 8-character fixture id.
+        `(${clipText(detail, LOG_TEXT_MAX)}); reconnecting in ${delay}ms${hint}`,
     )
     this.#setTimer('backoff', setTimeout(() => this.#tryEstablish(), delay))
   }
@@ -1041,6 +1215,12 @@ export class DeviceConnection {
    * network failures fall through to the next candidate — the §6
    * 「候选地址全部不可达」 verdict only holds when EVERY host failed.
    *
+   * Each candidate dials with ITS OWN port from `record.ports`; the record-level
+   * `port` (the winner's at pairing, the operator's after a PATCH) is the
+   * fallback for an in-memory record assembled without the map (issue #135).
+   * Before that, one port was shared by every host, so a reconnect to a
+   * non-winner host dialed the right scheme at the wrong port.
+   *
    * "Per-host" covers the CHANNEL-LEVEL handshake failures as well as the dial:
    * a socket that opens and then dies mid-handshake (the peer accepted the TCP
    * connection and went away, a proxy reset it, the Noise exchange was cut) is a
@@ -1081,7 +1261,11 @@ export class DeviceConnection {
       if (!this.#running || epoch !== this.#epoch) throw new CancelledError()
       let link: LiveLink
       try {
-        link = await this.#dial(host, this.record.port, epoch)
+        // Per-host port, with the record-level (winner's) port as the fallback
+        // for an in-memory record assembled without the map — the same `?.`
+        // default the scheme gets in #dial (issue #135).
+        const port = this.record.ports?.[host] ?? this.record.port
+        link = await this.#dial(host, port, epoch)
       } catch (error) {
         if (error instanceof IdentityMismatchError) throw error
         lastError = error instanceof Error ? error : new Error(String(error))
@@ -1117,10 +1301,17 @@ export class DeviceConnection {
   }
 
   async #dial(host: string, port: number, epoch: number): Promise<LiveLink> {
-    // Bare IPv6 hosts (the archive's normalized form) must be bracketed into
-    // a URL authority or `new WebSocket` throws Invalid URL.
-    const url = `ws://${urlHost(host)}:${port}${remoteConnectPath}`
-    const ws = new WebSocket(url)
+    // (see {@link DeviceConnectionOptions.wsOptions} for TLS trust)
+    // The URL comes from the SAME helper the pairing dial uses (issue #126):
+    // it brackets bare IPv6 hosts (the archive's normalized form — splicing one
+    // raw into a URL makes `new WebSocket` throw Invalid URL) and selects
+    // `ws:`/`wss:` from the record's own scheme for this host. Persisting the
+    // scheme is what makes a TLS-proxied desktop RE-connectable: #124 paired
+    // over `wss` and this dial then rebuilt `ws://` for every later session.
+    const ws = new WebSocket(
+      directEndpointUrl({ host, port, security: this.record.security?.[host] ?? 'ws' }),
+      this.#wsOptions,
+    )
     const controller = new AbortController()
 
     const opened = new Promise<void>((resolve) => ws.once('open', () => resolve()))
@@ -1207,11 +1398,18 @@ export class DeviceConnection {
       throw error instanceof Error ? error : new Error(String(error))
     }
 
+    // REBUILT, never patched: the object is replaced on every hello, so a
+    // reconnect to a peer that no longer advertises the capability (or a
+    // downgrade) cannot inherit a stale `messageSummaries` from the previous
+    // link — the exact failure mode that would send `partsMode` to a 2.1.7 peer.
     this.#limits = {
       heartbeatMs: positive(hello.heartbeatMs) ?? FALLBACK_LIMITS.heartbeatMs,
       subscriptions: positive(hello.limits?.['subscriptions']) ?? FALLBACK_LIMITS.subscriptions,
       pageItems: positive(hello.limits?.['pageItems']) ?? FALLBACK_LIMITS.pageItems,
       inFlightRequests: positive(hello.limits?.['inFlightRequests']) ?? FALLBACK_LIMITS.inFlightRequests,
+      ...(typeof hello.agentMessageSummariesVersion === 'number'
+        ? { messageSummaries: hello.agentMessageSummariesVersion }
+        : {}),
     }
 
     // Size the admission window from the peer's OWN concurrency budget now that
@@ -1230,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).
@@ -1282,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
@@ -1764,6 +2035,9 @@ export class DeviceConnection {
       try {
         cb(next)
       } catch (error) {
+        // LOCAL observer fan-out (our own listeners), so no peer text can reach
+        // this error: the object print keeps the stack, which is the useful
+        // part here (issue #161's boundary).
         console.warn(`[cherry-remote] state listener threw for ${this.record.deviceId}`, error)
       }
     }
@@ -1771,6 +2045,8 @@ export class DeviceConnection {
       try {
         cb(next)
       } catch (error) {
+        // LOCAL: `waitForSettled`'s internal closure, no peer text — the object
+        // print (and its stack) is deliberate (issue #161's boundary).
         console.warn(`[cherry-remote] settle waiter threw for ${this.record.deviceId}`, error)
       }
     }