dsh-cherry-bridge 0.1.11 → 0.2.1

package/src/deviceStore.ts

@@ -11,6 +11,7 @@ import {
   writeSync,
 } from 'node:fs'
 import { dirname } from 'node:path'
+import type { DirectEndpoint } from '@cherrystudio/remote-protocol'
 
 /**
  * Crash-durable, corruption-safe archive of paired Cherry Studio desktop
@@ -45,8 +46,51 @@ 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>
+  /**
+   * Addresses the operator has FORGOTTEN (issue #185): never dialed and never
+   * learned again, matched CASE-INSENSITIVELY and disjoint from `hosts` — a
+   * record may not dial what it has forgotten, and `assertValidRecord` refuses
+   * the overlap rather than picking a winner at read time.
+   *
+   * OPTIONAL on purpose, and therefore not in {@link REQUIRED_KEYS}. Absence is
+   * the total default ("nothing forgotten"); no invariant depends on the key
+   * being present, unlike `security`/`ports` whose absence would make a host
+   * undialable; and an older build ignores an unknown key instead of refusing
+   * the archive. A `schemaVersion` bump would invalidate every v4 archive (and
+   * every fixture built from the v4 shape) for a list whose empty value needs
+   * no migration.
+   */
+  forgottenHosts?: string[]
   desktopIdentity: string
   grants: 'agent'[]
   /** Paired with `tokenExpiresAt`: present together or absent together. */
@@ -77,7 +121,81 @@ 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
+
+/**
+ * The most candidate hosts one record may carry (issue #143).
+ *
+ * `hosts` is a DIAL list, not a table: every reconnect walks it with one
+ * `connectTimeoutMs` per address, so its LENGTH is a time cost — a 32-host
+ * record already allows a 320 s pass, which is the number the pairing walk's
+ * aggregate budget exists for. Pairing can only ever produce 32
+ * (`pairingQrSchema`'s `.max(32)`), and learning is held to the same bound: an
+ * enrichment may not build a record that no pairing could have produced.
+ */
+export const MAX_CANDIDATE_HOSTS = 32
+
+/**
+ * Adds the candidate addresses a peer ADVERTISED that this record does not
+ * already dial, returning how many hosts were added (issue #143).
+ *
+ * The rule is ADD-ONLY, deliberately:
+ *
+ *  - a host already in `hosts` is left exactly as it is, INCLUDING its port and
+ *    its scheme. The peer's snapshot describes where it listens NOW, while a
+ *    record entry may be an operator's choice (a pinned port, a TLS proxy) that
+ *    every reconnect must keep honouring; re-pointing it would silently rewrite
+ *    the operator's address book on a schedule. "Already dials" is judged
+ *    CASE-INSENSITIVELY: a hostname is case-insensitive, the peer's schema
+ *    lowercases what it advertises, and a PATCHed record stores what the
+ *    operator typed — without this, `MyNAS.example` and `mynas.example` would
+ *    both hold a dial slot. (An IPv6 literal in a different EXPANSION is NOT
+ *    reconciled here; the PATCH path owns the archive's spelling, and it does
+ *    not canonicalize either.)
+ *  - nothing is removed HERE: a host the peer still advertises is re-learned
+ *    after an operator PATCH drops it, because the peer is the source of truth
+ *    for where it listens. The operator's answer to that is `forgetEndpoints`
+ *    (issue #185), whose mark this function honours — addition stays add-only,
+ *    and forgetting is a separate, explicit decision;
+ *  - host, port and scheme are appended TOGETHER, which is what keeps the v4
+ *    one-entry-per-host invariant true. That invariant is enforced on the READ
+ *    path by `assertValidSecurity`/`assertValidPorts`, and a semantic failure
+ *    there is NOT a quarantine (that class covers unreadable bytes): the throw
+ *    escapes `parseArchive` out of `list()`, so a split entry would break every
+ *    tool until an operator repaired the file;
+ *  - past {@link MAX_CANDIDATE_HOSTS} nothing is added, and the loop stops
+ *    rather than scanning the rest.
+ *
+ * `endpoints` must already have passed the peer's own `advertisedEndpointSchema`
+ * (which bounds the port to 1..65535, the scheme to `ws`/`wss`, and rejects a
+ * loopback destination), so every value written here is archive-valid without a
+ * second validation pass.
+ */
+export function mergeAdvertisedEndpoints(
+  record: DeviceRecord,
+  endpoints: readonly DirectEndpoint[],
+): number {
+  // One comparison rule, applied to what the record already dials AND to what
+  // this answer has added so far: a duplicate inside one answer must not take a
+  // second slot either.
+  const dialed = new Set(record.hosts.map((host) => host.toLowerCase()))
+  // A FORGOTTEN address is skipped here, not removed afterwards: the operator's
+  // decision outranks the peer's snapshot, and an answer that names it must not
+  // even spend a dial slot on it.
+  const forgotten = new Set((record.forgottenHosts ?? []).map((host) => host.toLowerCase()))
+  let added = 0
+  for (const endpoint of endpoints) {
+    const key = endpoint.host.toLowerCase()
+    if (dialed.has(key) || forgotten.has(key)) continue
+    if (record.hosts.length >= MAX_CANDIDATE_HOSTS) break
+    record.hosts.push(endpoint.host)
+    record.ports[endpoint.host] = endpoint.port
+    record.security[endpoint.host] = endpoint.security
+    dialed.add(key)
+    added += 1
+  }
+  return added
+}
 
 const FILE_MODE = 0o600
 
@@ -105,15 +223,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 +311,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 +350,22 @@ 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)
+  assertValidForgotten(disk.hosts, disk.forgottenHosts)
 
   // accessToken / tokenExpiresAt live and die together.
   const hasToken = disk.accessToken !== undefined
@@ -166,6 +379,147 @@ 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`,
+      )
+    }
+  }
+}
+
+/**
+ * `forgottenHosts`, when present, must be a list of non-empty strings with no
+ * case-variant duplicates and no overlap with `hosts`.
+ *
+ * Each rule refuses a state whose MEANING is ambiguous: two spellings of one
+ * host make "is this address suppressed?" depend on which entry the comparison
+ * hit first, and a host that is both dialed and forgotten makes the dial list
+ * and the suppression list disagree about the same address. The message names
+ * the offending host — these are addresses an operator chose, not secrets.
+ */
+function assertValidForgotten(hosts: string[], forgotten: unknown): void {
+  if (forgotten === undefined) return
+  if (!Array.isArray(forgotten)) {
+    throw new Error('device archive entry field forgottenHosts must be an array')
+  }
+  const dialed = new Set(hosts.map((host) => host.toLowerCase()))
+  const seen = new Set<string>()
+  for (const entry of forgotten) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      throw new Error('device archive entry field forgottenHosts must list non-empty strings')
+    }
+    const key = entry.toLowerCase()
+    if (seen.has(key)) {
+      throw new Error(`device archive entry lists host "${entry}" in forgottenHosts more than once`)
+    }
+    if (dialed.has(key)) {
+      throw new Error(`device archive entry names host "${entry}" in both hosts and forgottenHosts`)
+    }
+    seen.add(key)
+  }
+}
+
+/**
+ * Repairs ONE cross-build state on the READ path: a host listed in both
+ * `hosts` and `forgottenHosts` (issue #185).
+ *
+ * A build that predates the field PRESERVES it but cannot honour it, so a
+ * downgrade followed by a still-advertising desktop appends the host to
+ * `hosts` while the mark stays. Upgrading again then yields a record that says
+ * both "dial it" and "never dial it". Refusing it would brick every device tool
+ * until an operator hand-edits a 0600 file, so the READ path keeps the DIAL
+ * list — what the running build actually did — and drops the mark, with a
+ * warning naming the device and host (addresses are not secrets).
+ *
+ * The WRITE paths stay strict: `upsert`, `forgetEndpoints` and
+ * `rememberEndpoints` never produce the overlap, and `assertValidRecord`
+ * refuses it. This runs ONLY on the read path, before that assertion.
+ */
+function reconcileForgottenMarks(disk: DeviceRecordOnDisk): DeviceRecordOnDisk {
+  const forgotten = disk.forgottenHosts
+  if (!Array.isArray(forgotten) || !Array.isArray(disk.hosts)) return disk
+  const dialed = new Set(disk.hosts.map((host) => host.toLowerCase()))
+  const kept = forgotten.filter(
+    (host) => !(typeof host === 'string' && dialed.has(host.toLowerCase())),
+  )
+  if (kept.length === forgotten.length) return disk
+  for (const host of forgotten) {
+    if (typeof host !== 'string' || !dialed.has(host.toLowerCase())) continue
+    console.warn(
+      `device archive entry ${String(disk.deviceId)} lists host "${host}" as both dialed and ` +
+        `forgotten; keeping it dialed and dropping the mark (a plugin downgrade can produce this)`,
+    )
+  }
+  return { ...disk, forgottenHosts: kept }
+}
+
 /**
  * Read path, fixed order: loose parse -> completeness gate -> version judgement
  * -> migration -> assert the required `DeviceRecord` type.
@@ -228,7 +582,9 @@ function parseRecord(raw: unknown, archiveVersion: number): DeviceRecord {
     migrated = migrate(migrated)
   }
 
-  return assertValidRecord(migrated)
+  // A cross-build repair, never a write-path policy: see
+  // `reconcileForgottenMarks` for why the read path is the forgiving one.
+  return assertValidRecord(reconcileForgottenMarks(migrated))
 }
 
 function parseArchive(parsed: unknown): ArchiveFile {
@@ -382,6 +738,31 @@ export class QuarantinedArchiveError extends Error {
   }
 }
 
+/**
+ * Refusal raised by {@link DeviceStore.forgetEndpoints} when the operation
+ * would leave a record with NO dial candidate.
+ *
+ * A record with nothing to dial is worse than the stale address the operator
+ * wanted gone: every tool would answer `offline` until a RE-PAIR or a PATCH
+ * with a non-empty `hosts` list writes a fresh one, and the archive would look
+ * healthy the whole time. The check is ATOMIC — the whole call refuses, so a
+ * name for the last host cannot remove a different host on its way to failing.
+ * Nothing is written when this is thrown.
+ */
+export class LastCandidateHostError extends Error {
+  readonly deviceId: string
+
+  constructor(deviceId: string) {
+    super(
+      `device ${deviceId}: refusing to forget the last dial candidate — the record would have ` +
+        'nothing to dial. Keep at least one address.',
+    )
+    this.name = 'LastCandidateHostError'
+    this.deviceId = deviceId
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
 /**
  * Preserves an unreadable archive as `<file>.corrupt` (best effort — a failed
  * copy must not mask the original problem) and returns the path it landed at.
@@ -575,6 +956,135 @@ export class DeviceStore {
     this.#persist(devices)
   }
 
+  /**
+   * Merges freshly learned addresses into one record and writes ONLY when that
+   * record gained a host (issue #143), returning the number added.
+   *
+   * It exists so the enrichment is an ARCHIVE operation rather than an
+   * `upsert` the assembly assembles by hand, and so a merge that adds nothing
+   * never rewrites (and fsyncs) the archive: `connection.endpoints` is asked on
+   * every connect, and a stable desktop would otherwise pay a full atomic write
+   * per reconnect. The merge runs on a CLONE and is committed as a new list,
+   * mirroring `upsert`'s discipline — the store never adopts a caller's object
+   * graph, and a write refused at {@link #persist}'s own gate cannot have
+   * half-edited the record the archive still holds.
+   *
+   * `desktopIdentity` is the pin the answering connection belongs to: the
+   * record must still name that desktop. A RE-PAIR under the same `deviceId`
+   * (the desktop regenerated its identity) would otherwise take an address
+   * learned from the previous pairing — a stale candidate whose every dial then
+   * fails the Noise pin, permanently, because learning never removes.
+   *
+   * An unknown `deviceId` is a no-op — the record may have been removed (or
+   * re-paired) between the RPC and this write.
+   */
+  learnEndpoints(deviceId: string, endpoints: readonly DirectEndpoint[], desktopIdentity: string): number {
+    const devices = this.#load()
+    const index = devices.findIndex((record) => record.deviceId === deviceId)
+    if (index < 0) return 0
+    if (devices[index]!.desktopIdentity !== desktopIdentity) return 0
+    const merged = structuredClone(devices[index]!)
+    const added = mergeAdvertisedEndpoints(merged, endpoints)
+    if (added === 0) return 0
+    const next = [...devices]
+    next[index] = merged
+    this.#persist(next)
+    return added
+  }
+
+  /**
+   * FORGETS addresses (issue #185): drops each named host from the dial list —
+   * host, scheme and port as one unit — and records it so the next
+   * advertisement cannot put it back. Returns the hosts that left the dial list
+   * (`removed`) and the marks this call added (`marked`).
+   *
+   * This is the operation learning cannot provide. `connection.endpoints` is
+   * asked on every handshake, so an address the desktop still advertises
+   * returns after any removal the operator makes by PATCH; forgetting is the
+   * explicit decision that outranks it.
+   *
+   * - Matching is CASE-INSENSITIVE (a PATCHed record keeps the operator's
+   *   spelling, the peer's schema lowercases what it advertises), and the mark
+   *   records the ARCHIVE's spelling when the host was dialed, the caller's
+   *   otherwise.
+   * - Naming an address the record does not dial is legal and still marks it:
+   *   suppression is the point, and a pre-emptive forget must survive until
+   *   the peer advertises the address.
+   * - Removing the LAST candidate throws {@link LastCandidateHostError} and
+   *   writes NOTHING — no host, no scheme, no port, no mark.
+   * - A call that changes no byte (the host was already forgotten) does not
+   *   rewrite (or fsync) the archive.
+   *
+   * The write goes through `#persist` on a CLONE with the result re-validated,
+   * so a caller-supplied junk host can never land a record the next read would
+   * refuse. An unknown `deviceId` is a no-op, like {@link learnEndpoints}.
+   */
+  forgetEndpoints(deviceId: string, hosts: readonly string[]): { removed: string[]; marked: string[] } {
+    const devices = this.#load()
+    const index = devices.findIndex((record) => record.deviceId === deviceId)
+    if (index < 0) return { removed: [], marked: [] }
+    const merged = structuredClone(devices[index]!)
+    const wanted = new Set(hosts.map((host) => host.toLowerCase()))
+    const removed = merged.hosts.filter((host) => wanted.has(host.toLowerCase()))
+    if (removed.length > 0 && removed.length === merged.hosts.length) {
+      throw new LastCandidateHostError(deviceId)
+    }
+    for (const host of removed) {
+      delete merged.security[host]
+      delete merged.ports[host]
+    }
+    merged.hosts = merged.hosts.filter((host) => !wanted.has(host.toLowerCase()))
+    const forgotten = merged.forgottenHosts ?? []
+    const known = new Set(forgotten.map((host) => host.toLowerCase()))
+    const marked: string[] = []
+    for (const host of hosts) {
+      const key = host.toLowerCase()
+      if (known.has(key)) continue
+      const spelling = removed.find((entry) => entry.toLowerCase() === key) ?? host
+      forgotten.push(spelling)
+      known.add(key)
+      marked.push(spelling)
+    }
+    if (removed.length === 0 && marked.length === 0) return { removed: [], marked: [] }
+    merged.forgottenHosts = forgotten
+    assertValidRecord(merged)
+    const next = [...devices]
+    next[index] = merged
+    this.#persist(next)
+    return { removed, marked }
+  }
+
+  /**
+   * Lifts a forget mark (issue #185), returning the marks that were removed.
+   *
+   * It does NOT dial the host again: it only lets the next handshake's
+   * advertisement add it back through the ordinary learning path, with the
+   * port and scheme the peer reports at that moment. An operator who wants the
+   * address back immediately PATCHes it into `hosts`, which clears the mark on
+   * the same write.
+   *
+   * No-op (and no write) when the device is unknown, nothing is forgotten, or
+   * none of the named hosts is marked.
+   */
+  rememberEndpoints(deviceId: string, hosts: readonly string[]): { restored: string[] } {
+    const devices = this.#load()
+    const index = devices.findIndex((record) => record.deviceId === deviceId)
+    if (index < 0) return { restored: [] }
+    const current = devices[index]!.forgottenHosts ?? []
+    if (current.length === 0) return { restored: [] }
+    const wanted = new Set(hosts.map((host) => host.toLowerCase()))
+    const restored = current.filter((host) => wanted.has(host.toLowerCase()))
+    if (restored.length === 0) return { restored: [] }
+    const merged = structuredClone(devices[index]!)
+    merged.forgottenHosts = (merged.forgottenHosts ?? []).filter(
+      (host) => !wanted.has(host.toLowerCase()),
+    )
+    const next = [...devices]
+    next[index] = merged
+    this.#persist(next)
+    return { restored }
+  }
+
   #load(): DeviceRecord[] {
     if (this.#devices !== undefined) return this.#devices
 
@@ -587,6 +1097,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',
 ]