dsh-cherry-bridge 0.1.11 → 0.2.0

package/src/connection.ts

@@ -2,7 +2,7 @@ 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 } 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 +13,8 @@ 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 { clipText, LOG_TEXT_MAX } from './text.js'
 
 /**
  * Per-device persistent connection: the M1 capstone that owns the WebSocket,
@@ -36,13 +36,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
@@ -544,6 +590,8 @@ interface HelloResult {
   protocolVersion?: number
   limits?: Record<string, number>
   heartbeatMs?: number
+  /** The paged-message-summaries capability (issue #105), when advertised. */
+  agentMessageSummariesVersion?: number
 }
 
 interface AuthResult {
@@ -740,8 +788,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,
@@ -967,6 +1018,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 +1033,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 +1079,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 +1116,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 +1162,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 +1202,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 +1299,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
@@ -1764,6 +1863,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 +1873,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)
       }
     }

package/src/deviceStore.ts

@@ -45,8 +45,36 @@ export interface DeviceRecord {
   schemaVersion: number
   deviceId: string
   displayName: string
+  /**
+   * Ordered dial candidates. `security` and `ports` are keyed by these same
+   * hosts — one scheme and one port per candidate, exactly the shape the
+   * pairing dial already carries (`PairCandidate`), so a candidate and its
+   * address are added and replaced as one unit.
+   */
   hosts: string[]
+  /**
+   * The record-level dial port: the WINNER candidate's port at pairing, the
+   * operator's after a PATCH, and always the dial's fallback. A stored v4
+   * record carries an explicit `ports` entry for every host; this value is only
+   * the fallback for an in-memory record assembled before validation. Before
+   * schemaVersion 4 it was the only port — see `ports`.
+   */
   port: number
+  /**
+   * Dial scheme per host (issue #126). Every entry of `hosts` has exactly one
+   * key here; `wss` is a TLS-proxied desktop. Introduced with schemaVersion 3:
+   * a v2 archive had `hosts` + `port` only, and the migration backfills `ws`.
+   */
+  security: Record<string, 'ws' | 'wss'>
+  /**
+   * Dial port per host (issue #135). Every entry of `hosts` has exactly one
+   * key here, and the value is the port that host was paired on. Introduced
+   * with schemaVersion 4: before it, one `port` was shared by every host (the
+   * winner candidate's), so a steady-state reconnect to a non-winner host
+   * dialed the right scheme at the WRONG port. The v3→v4 migration backfills
+   * `ports` from `port`; `port` itself stays the record-level fallback.
+   */
+  ports: Record<string, number>
   desktopIdentity: string
   grants: 'agent'[]
   /** Paired with `tokenExpiresAt`: present together or absent together. */
@@ -77,7 +105,7 @@ export interface UnresolvedDevice {
 export type DeviceResolution = DeviceRecord | AmbiguousDevice | UnresolvedDevice
 
 /** The only `schemaVersion` this build reads and writes. */
-export const CURRENT_SCHEMA_VERSION = 2
+export const CURRENT_SCHEMA_VERSION = 4
 
 const FILE_MODE = 0o600
 
@@ -105,15 +133,83 @@ type Migration = (record: DeviceRecordOnDisk) => DeviceRecordOnDisk
  * `{ 1 -> 2 }` is a mechanism sample only, mirroring the plan's convention that
  * real schema evolution starts at version 2 after release. A v1 archive is the
  * current field set minus `schemaVersion`.
+ *
+ * `{ 2 -> 3 }` (issue #126) adds the per-host `security` map. v2 had `hosts` +
+ * one `port` and no scheme at all, so every host is backfilled `ws` — the
+ * plain dial v2 always used. An archive that already carries SOME entries
+ * (a half-migrated file, or one a newer build wrote) keeps them: a scheme the
+ * record remembers is never overwritten by the default, because that would
+ * downgrade a TLS-proxied desktop to a dial that cannot connect.
+ *
+ * `{ 3 -> 4 }` (issue #135) adds the per-host `ports` map. v3 had `hosts` + one
+ * shared `port` (the winner candidate's), so the step backfills `ports` from
+ * `port` for every host — the only one v3 ever dialed. A half-migrated file
+ * keeps the entries it already carries, for the same reason the scheme step
+ * does: a remembered port is the address the pairing actually used, and
+ * overwriting it would point the host at the winner's port again.
+ *
+ * **A legacy file is read loosely, this build's own output strictly —
+ * deliberately.** Each step fills its map for the CURRENT host list and
+ * nothing else: an entry naming a host the older file no longer lists is
+ * silently DROPPED (it was unreachable anyway), a non-object `security`/`ports`
+ * degrades to "every host on `ws`"/"every host at `port`", and a junk scheme or
+ * port VALUE is not repaired here at all — the migrated entry then continues
+ * down the chain and `assertValidSecurity`/`assertValidPorts` reject the whole
+ * archive. That split is the point: a v2 or v3 file is a supported legacy shape
+ * and is normalised into one, while a v4 file is this build's own output and
+ * any deviation from it is a hand edit worth failing loudly on.
  */
 const MIGRATIONS: Record<number, Migration> = {
   1: (record) => ({ ...record, schemaVersion: 2 }),
+  2: (record) => ({ ...record, schemaVersion: 3, security: backfilledSecurity(record) }),
+  3: (record) => ({ ...record, schemaVersion: 4, ports: backfilledPorts(record) }),
+}
+
+/** Every host of a v2 record, defaulting anything it did not already say. */
+function backfilledSecurity(
+  disk: Partial<DeviceRecord>,
+): Record<string, 'ws' | 'wss'> {
+  // A hand-edited file can carry a non-array `hosts`; read it as empty here and
+  // let `assertValidRecord` name the real rule, instead of throwing a TypeError
+  // out of `.map` first.
+  const hosts = Array.isArray(disk.hosts) ? disk.hosts : []
+  const existing = disk.security ?? {}
+  // `Object.hasOwn`, never `existing[host] ?? …`: on an empty map a host named
+  // `constructor`/`__proto__`/`toString` would otherwise pick up an INHERITED
+  // function and poison the map. A remembered own entry wins even when its
+  // value is null — a junk value is the validator's to reject, not to repair.
+  return Object.fromEntries(
+    hosts.map((host) => [host, Object.hasOwn(existing, host) ? existing[host] : 'ws']),
+  )
+}
+
+/** Every host of a v3 record, defaulting anything it did not already say. */
+function backfilledPorts(disk: Partial<DeviceRecord>): Record<string, number> {
+  // Same two rules as `backfilledSecurity`: non-array hosts read as empty, and
+  // only an OWN entry is remembered (an inherited function is not a port).
+  const hosts = Array.isArray(disk.hosts) ? disk.hosts : []
+  const existing = disk.ports ?? {}
+  // The cast states this function's EXIT shape, not a guarantee about the
+  // input: a malformed entry may omit `port`, and the `undefined` that would
+  // produce is rejected by `assertValidPorts` right after the migration chain.
+  const fallback = disk.port as number
+  return Object.fromEntries(
+    hosts.map((host): [string, number] => [
+      host,
+      Object.hasOwn(existing, host) ? existing[host] : fallback,
+    ]),
+  )
 }
 
 /**
- * Every field of the *current* set except `schemaVersion` — v1 is defined as
- * the current field set minus the version key, so these are exactly the keys a
- * complete v1 archive must carry.
+ * The field set of a v1 entry: what the store wrote before it carried a
+ * version at all.
+ *
+ * FROZEN. It must not track the current record — a v1 archive predates every
+ * later field, so demanding one here (as `'security'` was, briefly) fails the
+ * completeness gate on an archive that is perfectly intact and quarantines it
+ * instead of migrating it. Later fields are the migration chain's business
+ * (`backfilledSecurity`/`backfilledPorts` supply `security`/`ports`).
  */
 const V1_KEYS = [
   'deviceId',
@@ -125,7 +221,18 @@ const V1_KEYS = [
   'enabled',
 ] as const satisfies readonly (keyof DeviceRecord)[]
 
-const REQUIRED_KEYS = [...V1_KEYS, 'schemaVersion'] as const satisfies readonly (keyof DeviceRecord)[]
+/**
+ * Every field of the CURRENT set plus `schemaVersion`. Unlike {@link V1_KEYS}
+ * this is not a historical snapshot: it grows with the record, and it is what
+ * `upsert` and the post-migration exit demand (which is why a v4 entry without
+ * `security`/`ports` never reaches its own validator).
+ */
+const REQUIRED_KEYS = [
+  ...V1_KEYS,
+  'security',
+  'ports',
+  'schemaVersion',
+] as const satisfies readonly (keyof DeviceRecord)[]
 
 /**
  * A version-less entry reads as the legacy (v1) shape only when every v1 field
@@ -153,6 +260,21 @@ function assertValidRecord(disk: DeviceRecordOnDisk): DeviceRecord {
   if (!Array.isArray(disk.hosts)) {
     throw new Error('device archive entry field hosts must be an array')
   }
+  // The record-level port is the fallback a hosts-only PATCH derives a NEW
+  // host's entry from, so it is judged like any map value: a hand-edited v4
+  // record with a valid `ports` map but a junk `port` would otherwise make that
+  // PATCH 400 (naming a field absent from its body). The message names the
+  // field, never the value. Before this it was the one unchecked record number.
+  if (
+    typeof disk.port !== 'number' ||
+    !Number.isInteger(disk.port) ||
+    disk.port < 1 ||
+    disk.port > 65_535
+  ) {
+    throw new Error('device archive entry field port must be an integer in 1..65535')
+  }
+  assertValidSecurity(disk.hosts, disk.security)
+  assertValidPorts(disk.hosts, disk.ports)
 
   // accessToken / tokenExpiresAt live and die together.
   const hasToken = disk.accessToken !== undefined
@@ -166,6 +288,81 @@ function assertValidRecord(disk: DeviceRecordOnDisk): DeviceRecord {
   return disk as DeviceRecord
 }
 
+/**
+ * The `security` map must be EXACTLY one entry per host, each a known scheme.
+ *
+ * Keyed by host, so a record can carry an entry the dial will never consult
+ * (a host it no longer lists) and a host the dial will fall back on silently.
+ * Both are hand-edited-archive states, and both are rejected rather than
+ * repaired in memory: the archive a human edits is the archive the store
+ * judges, and a silent repair would hide the very mistake. The message names
+ * the offending HOSTS (they are addresses an operator chose, not secrets).
+ */
+function assertValidSecurity(hosts: string[], security: unknown): void {
+  // NOT reached with `undefined` through the store: `REQUIRED_KEYS` rejects a
+  // missing `security` before this runs (a current-version archive is written
+  // by this build, so an absent map there is breakage, not a legacy shape). The
+  // arm exists for the OTHER entry point — `upsert`, which callers may reach
+  // with an in-memory record assembled by hand — and for the length of time a
+  // record exists between construction and its first validation.
+  if (security === undefined) return
+  if (security === null || typeof security !== 'object' || Array.isArray(security)) {
+    throw new Error('device archive entry field security must be an object keyed by host')
+  }
+  const map = security as Record<string, unknown>
+  const wanted = new Set(hosts)
+  const unknownHost = Object.keys(map).find((host) => !wanted.has(host))
+  if (unknownHost !== undefined) {
+    throw new Error(
+      `device archive entry field security names host "${unknownHost}", which is not in hosts`,
+    )
+  }
+  for (const host of hosts) {
+    const scheme = map[host]
+    if (scheme !== 'ws' && scheme !== 'wss') {
+      throw new Error(
+        `device archive entry field security["${host}"] must be "ws" or "wss"`,
+      )
+    }
+  }
+}
+
+/**
+ * The `ports` map must be EXACTLY one entry per host, each an integer port.
+ *
+ * The same reasoning as {@link assertValidSecurity}: an entry for a host the
+ * record no longer lists would never be consulted, and a missing one would
+ * leave that host on the record-level (winner's) port — the exact failure the
+ * map exists to prevent. Both are rejected rather than repaired. The
+ * message names the offending HOST, never the value (a port is not a secret, but
+ * echoing a junk value back from a hand-edited file adds nothing actionable).
+ */
+function assertValidPorts(hosts: string[], ports: unknown): void {
+  // NOT reached with `undefined` through the store: `REQUIRED_KEYS` rejects a
+  // missing `ports` before this runs. Same other-entry-point reason as
+  // `assertValidSecurity`: `upsert` and construction-to-first-validation.
+  if (ports === undefined) return
+  if (ports === null || typeof ports !== 'object' || Array.isArray(ports)) {
+    throw new Error('device archive entry field ports must be an object keyed by host')
+  }
+  const map = ports as Record<string, unknown>
+  const wanted = new Set(hosts)
+  const unknownHost = Object.keys(map).find((host) => !wanted.has(host))
+  if (unknownHost !== undefined) {
+    throw new Error(
+      `device archive entry field ports names host "${unknownHost}", which is not in hosts`,
+    )
+  }
+  for (const host of hosts) {
+    const port = map[host]
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) {
+      throw new Error(
+        `device archive entry field ports["${host}"] must be an integer in 1..65535`,
+      )
+    }
+  }
+}
+
 /**
  * Read path, fixed order: loose parse -> completeness gate -> version judgement
  * -> migration -> assert the required `DeviceRecord` type.
@@ -587,6 +784,8 @@ export class DeviceStore {
       // `list`/`resolve` keep working (RF4's spirit — a corrupt archive never
       // takes the plugin down), but nothing may write over the evidence.
       this.#quarantine = error.withCorruptPath(quarantine(error.file))
+      // LOCAL fs/parse cause, never peer text (issue #161 audit): the object
+      // print keeps the cause's stack, which is the useful part here.
       console.warn(
         `device archive ${this.#file} is unreadable and was quarantined; serving an empty ` +
           `read-only archive and refusing all writes until the bad file is moved aside:`,

package/src/diagnostics.ts

@@ -193,6 +193,21 @@ export interface DiagnosticsDevice {
    */
   desktopIdentity: string
   limits?: EffectiveLimits
+  /**
+   * The peer's hello-advertised `agentMessageSummariesVersion` (issue #105) —
+   * the capability bit that decides whether `agent.messages.list` may carry
+   * `partsMode: 'paged'`.
+   *
+   * Its own field, not a fifth key inside `limits`: it is a VERSION, not a
+   * count, and `limits` is documented as the four numeric caps. Present only
+   * when a LIVE connection reported it (the same rule as `limits`: the endpoint
+   * never dials to find out). ABSENT therefore means "not advertised **or** not
+   * connected" — every desktop through 2.1.7, and any device whose link is
+   * down at the moment of the call. One `curl` against
+   * `GET /cherry-remote/api/diagnostics` **while the device is connected**
+   * answers "does this desktop speak paged summaries?" without a packet capture.
+   */
+  messageSummaries?: number
 }
 
 /** One session's LOCAL subscription bookkeeping. */
@@ -500,6 +515,9 @@ export function sanitizeDevice(
             pageItems: limits.pageItems,
             inFlightRequests: limits.inFlightRequests,
           },
+          // Own field, own whitelist entry: a single number copied out of the
+          // hello, never the reply itself.
+          ...(limits.messageSummaries === undefined ? {} : { messageSummaries: limits.messageSummaries }),
         }),
   }
 }
@@ -522,9 +540,20 @@ function projectDevice(raw: unknown): DiagnosticsDevice {
         ? desktopIdentity
         : digestIdentity(desktopIdentity),
     ...projectLimits(value['limits']),
+    ...projectMessageSummaries(value['messageSummaries']),
   }
 }
 
+/**
+ * Re-projects the ONE capability field, dropping anything that is not a finite
+ * number: a version this report cannot read is reported as absent (not
+ * advertised), which is the safe side — the field only ever amplifies what the
+ * peer's hello said.
+ */
+function projectMessageSummaries(raw: unknown): { messageSummaries?: number } {
+  return typeof raw === 'number' && Number.isFinite(raw) ? { messageSummaries: raw } : {}
+}
+
 /**
  * Re-projects the four numeric limit keys, dropping any foreign key that a
  * caller's `limits` object might carry. A whitelist inside the whitelist: the
@@ -843,4 +872,5 @@ export const DIAGNOSTICS_DEVICE_KEYS: readonly string[] = [
   'port',
   'desktopIdentity',
   'limits',
+  'messageSummaries',
 ]