dsh-cherry-bridge 0.1.11 → 0.2.1

package/dist/index.mjs

@@ -5,7 +5,60 @@ import { chmod, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { RemoteSocketStream, connectSecureChannel, createDeviceIdentity, deviceIdentityId } from "@cherrystudio/remote-transport";
 import { createHash, randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
-import { jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, remoteConnectPath, remoteFailureSchema } from "@cherrystudio/remote-protocol";
+import { advertisedEndpointSchema, directEndpointUrl, jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, pairingQrSchema, remoteFailureSchema } from "@cherrystudio/remote-protocol";
+import { peerIdFromString } from "@libp2p/peer-id";
+/**
+* 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.
+*/
+function mergeAdvertisedEndpoints(record, endpoints) {
+	const dialed = new Set(record.hosts.map((host) => host.toLowerCase()));
+	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 >= 32) 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 = 384;
 /**
 * Version-to-version migrations, keyed by the version they upgrade from.
@@ -13,15 +66,70 @@ const FILE_MODE = 384;
 * `{ 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`.
-*/
-const MIGRATIONS = { 1: (record) => ({
-	...record,
-	schemaVersion: 2
-}) };
+*
+* `{ 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 = {
+	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) {
+	const hosts = Array.isArray(disk.hosts) ? disk.hosts : [];
+	const existing = disk.security ?? {};
+	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) {
+	const hosts = Array.isArray(disk.hosts) ? disk.hosts : [];
+	const existing = disk.ports ?? {};
+	const fallback = disk.port;
+	return Object.fromEntries(hosts.map((host) => [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",
@@ -32,7 +140,18 @@ const V1_KEYS = [
 	"grants",
 	"enabled"
 ];
-const REQUIRED_KEYS = [...V1_KEYS, "schemaVersion"];
+/**
+* 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"
+];
 /**
 * A version-less entry reads as the legacy (v1) shape only when every v1 field
 * is present. A missing `schemaVersion` alone means v1; a missing
@@ -44,14 +163,116 @@ function hasCompleteFieldSet(disk) {
 }
 /** Asserts the required `DeviceRecord` shape. The read path's exit. */
 function assertValidRecord(disk) {
-	if (disk.schemaVersion !== 2) throw new Error(`device archive entry has unsupported schemaVersion ${String(disk.schemaVersion)}; expected 2`);
+	if (disk.schemaVersion !== 4) throw new Error(`device archive entry has unsupported schemaVersion ${String(disk.schemaVersion)}; expected 4`);
 	const missing = REQUIRED_KEYS.filter((key) => disk[key] === void 0);
 	if (missing.length > 0) throw new Error(`device archive entry is missing required field(s): ${missing.join(", ")}`);
 	if (!Array.isArray(disk.hosts)) throw new Error("device archive entry field hosts must be an array");
+	if (typeof disk.port !== "number" || !Number.isInteger(disk.port) || disk.port < 1 || disk.port > 65535) 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);
 	if (disk.accessToken !== void 0 !== (disk.tokenExpiresAt !== void 0)) throw new Error("device archive entry must carry accessToken and tokenExpiresAt together or not at all");
 	return disk;
 }
 /**
+* 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, security) {
+	if (security === void 0) 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;
+	const wanted = new Set(hosts);
+	const unknownHost = Object.keys(map).find((host) => !wanted.has(host));
+	if (unknownHost !== void 0) 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, ports) {
+	if (ports === void 0) 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;
+	const wanted = new Set(hosts);
+	const unknownHost = Object.keys(map).find((host) => !wanted.has(host));
+	if (unknownHost !== void 0) 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 > 65535) 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, forgotten) {
+	if (forgotten === void 0) 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 = /* @__PURE__ */ new Set();
+	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) {
+	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.
 *
@@ -74,18 +295,18 @@ function parseRecord(raw, archiveVersion) {
 	if (declared === void 0 && archiveVersion > 1) throw new Error(`device archive entry has no schemaVersion but its archive is schemaVersion ${archiveVersion}; legacy (v1) entries are only valid inside a schemaVersion-1 archive`);
 	if (declared !== void 0 && declared !== archiveVersion) throw new Error(`device archive entry declares schemaVersion ${declared} but its archive is schemaVersion ${archiveVersion}; the archive version is authoritative`);
 	let migrated = disk;
-	for (let step = archiveVersion; step < 2; step += 1) {
+	for (let step = archiveVersion; step < 4; step += 1) {
 		const migrate = MIGRATIONS[step];
 		if (migrate === void 0) throw new Error(`no migration registered from device archive schemaVersion ${step}`);
 		migrated = migrate(migrated);
 	}
-	return assertValidRecord(migrated);
+	return assertValidRecord(reconcileForgottenMarks(migrated));
 }
 function parseArchive(parsed) {
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("device archive must be a JSON object");
 	const archive = parsed;
 	if (typeof archive.schemaVersion !== "number") throw new Error("device archive is missing a numeric schemaVersion");
-	if (archive.schemaVersion > 2) throw new Error(`device archive declares schemaVersion ${archive.schemaVersion}, newer than supported 2; refusing to read it`);
+	if (archive.schemaVersion > 4) throw new Error(`device archive declares schemaVersion ${archive.schemaVersion}, newer than supported 4; refusing to read it`);
 	if (!Array.isArray(archive.devices)) throw new Error("device archive is missing a devices array");
 	const archiveVersion = archive.schemaVersion;
 	return {
@@ -95,7 +316,7 @@ function parseArchive(parsed) {
 }
 function serializeArchive(devices) {
 	return `${JSON.stringify({
-		schemaVersion: 2,
+		schemaVersion: 4,
 		devices
 	}, null, 2)}\n`;
 }
@@ -197,6 +418,26 @@ var QuarantinedArchiveError = 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.
+*/
+var LastCandidateHostError = class extends Error {
+	deviceId;
+	constructor(deviceId) {
+		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.
 */
@@ -363,6 +604,137 @@ var DeviceStore = class {
 		const devices = this.#load().filter((record) => record.deviceId !== deviceId);
 		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, endpoints, desktopIdentity) {
+		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, hosts) {
+		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 = [];
+		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, hosts) {
+		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() {
 		if (this.#devices !== void 0) return this.#devices;
 		let archive;
@@ -376,7 +748,7 @@ var DeviceStore = class {
 		}
 		const devices = archive === void 0 ? [] : archive.devices;
 		this.#devices = devices;
-		if (archive !== void 0 && archive.schemaVersion < 2) this.#persist(devices);
+		if (archive !== void 0 && archive.schemaVersion < 4) this.#persist(devices);
 		return devices;
 	}
 	#persist(devices) {
@@ -471,6 +843,124 @@ async function generateIdentity(dataDir, path) {
 	return parseIdentity(key);
 }
 //#endregion
+//#region src/text.ts
+/**
+* Bounded rendering for peer- and payload-controlled text (issue #155).
+*
+* The ONE helper this audit STANDARDISED ON — not the first attempt at the
+* idea: `src/diagnostics.ts`'s `truncateErrorMessage` (the diagnostics error
+* digest) and `src/rpc/jsonRpcClient.ts`'s `bounded()` (the frame-drop
+* warning's classification fields) predate it and stay where they are, for
+* their own callers. #155 is where the rendering rule was stated once and
+* applied to the SIX sites the audit found — four files: pairing's unknown-key
+* warning and stage verdict, the link-recovery line, the two connection error
+* lines, and the JSON-RPC notification-handler line. Each was unbounded for a
+* different "why not" (a 10 KiB payload cap, a hello-advertised field, the
+* 64 KiB record budget), which is exactly how the class of defect recurs: each
+* site answered the question for itself.
+*
+* The rule these helpers establish is stated once, here: bound the text where
+* it is RENDERED (never where it is carried — an error message is a value
+* until a log line or a verdict makes it text), name the amount removed with
+* the `… (+N chars)` marker, and never drop a list ENTRY silently (the
+* `(+K more)` count is explicit).
+*
+* Issue #161 swept the SAME SHAPE at the sites #155 did not name — a catch
+* handing an error OBJECT to `console.warn`'s second argument — on the paths
+* PEER traffic reaches. One renderer states the answer there, {@link
+* failureText}: the message alone, bounded. A purely LOCAL catch keeps the
+* object print, deliberately: its stack is the useful part and no peer text
+* can reach it (fs quarantine, the host registry, our own listener / settle
+* fan-out, a REST route's synchronous construction). The two earlier forms it
+* did NOT absorb — `truncateErrorMessage` (the diagnostics digest) and
+* `bounded()` (the frame-drop path) — are left alone: each emits a different
+* marker (`…[truncated]`, a bare `…`) that callers and docs depend on, so
+* folding would change output rather than converge on the rule.
+*/
+/**
+* Clips `text` into `max` characters, the `… (+N chars)` marker included in
+* the count. `kept` is a fixed point — the number of removed characters sets
+* the marker's own digits — and it is the LARGEST prefix that fits, so a
+* caller's ceiling is used without ever being exceeded.
+*
+* The final guard never ends the kept prefix between a UTF-16 surrogate pair: a
+* clip there would emit a lone surrogate, which is not valid unicode text (the
+* peer's `unicodeText` params face refuses it) and would travel in a
+* user-visible verdict. Dropping one char pays for a marker that can grow by
+* one digit at a 9→10 boundary, and the marker is re-derived from the new
+* dropped count. Pinned by `tests/unit/text.test.ts` — the branch used to be a
+* declared coverage gap while the clip point was private to pairing.
+*/
+function clipText(text, max) {
+	if (text.length <= max) return text;
+	let kept = max;
+	for (;;) {
+		const next = max - `… (+${text.length - kept} chars)`.length;
+		if (next === kept) break;
+		if (next < 0) return "…".slice(0, max);
+		kept = next;
+	}
+	const before = text.charCodeAt(kept - 1);
+	const after = text.charCodeAt(kept);
+	if (kept > 0 && before >= 55296 && before <= 56319 && after >= 56320 && after <= 57343) kept -= 1;
+	return `${text.slice(0, kept)}… (+${text.length - kept} chars)`;
+}
+/**
+* Renders `items` as a comma-joined list under `limits.max`, each item clipped
+* to `limits.itemMax` FIRST. When anything is left out the list says so:
+* ` (+K more)` where K is the number of items NOT named.
+*
+* Caller contract: `itemMax <= max`, so the first item always fits and a list
+* carrying a single over-long entry never renders an empty one. The marker
+* rides ON TOP of `limits.max` — it is a count, not an item, so the named text
+* never has to absorb its length. `[]` renders as `''`.
+*
+* Pairing's progress line (`stageHosts`) deliberately does NOT use this helper:
+* it always shows the FIRST host in full even above its own budget, because
+* that host is the run's identity. That is not an oversight, and it is not a
+* reason to weaken the contract here.
+*/
+function boundedJoin(items, limits) {
+	const rendered = items.map((item) => clipText(item, limits.itemMax));
+	const first = rendered[0];
+	if (first === void 0) return "";
+	let text = first;
+	let shown = 1;
+	for (; shown < rendered.length; shown += 1) {
+		if (text.length + 2 + rendered[shown].length > limits.max) break;
+		text += `, ${rendered[shown]}`;
+	}
+	const omitted = items.length - shown;
+	return omitted > 0 ? `${text} (+${omitted} more)` : text;
+}
+/**
+* Renders ONE caught failure for a log line: the message alone, clipped to
+* {@link LOG_TEXT_MAX}.
+*
+* This is the ONE form a caught failure takes in a PEER-TRIGGERED catch (issue
+* #161): a catch reached from peer traffic or a peer-triggered callback. The
+* old shape — `console.warn(prefix, error)` — handed the console the OBJECT.
+* On Node the console prints the error's name, message and stack (own
+* properties only when inspected), so the peer-controlled message and the
+* stack were both unbounded; for a defensive catch the stack is the noise.
+*
+* A caught failure from a purely LOCAL path (an fs copy, the host registry, our
+* own observers) keeps the object print: its stack is the useful part and no
+* peer text can reach it.
+*
+* TOTAL by construction: it runs INSIDE catch blocks, so a captured value whose
+* `toString` (or an Error subclass whose `message` getter) throws must not
+* escape the catch. The extraction is guarded and falls back to the fixed token
+* `<unrenderable failure>`.
+*/
+function failureText(error) {
+	try {
+		return clipText(error instanceof Error ? error.message : String(error), 240);
+	} catch {
+		return "<unrenderable failure>";
+	}
+}
+//#endregion
 //#region src/rpc/jsonRpcClient.ts
 /** Default cap on business requests in flight on a single connection. */
 const DEFAULT_MAX_IN_FLIGHT = 8;
@@ -896,7 +1386,7 @@ var JsonRpcClient = class {
 			for (const handler of [...this.handlers]) try {
 				handler(method, params);
 			} catch (error) {
-				console.warn(`[cherry-remote] notification handler for "${method}" threw`, error);
+				console.warn(`[cherry-remote] notification handler for "${bounded(method)}" threw: ${failureText(error)}`);
 			}
 			return;
 		}
@@ -1887,12 +2377,15 @@ function sanitizeDevice(record, state, limits) {
 		hosts: [...record.hosts],
 		port: record.port,
 		desktopIdentity: digestIdentity(record.desktopIdentity),
-		...limits === void 0 ? {} : { limits: {
-			heartbeatMs: limits.heartbeatMs,
-			subscriptions: limits.subscriptions,
-			pageItems: limits.pageItems,
-			inFlightRequests: limits.inFlightRequests
-		} }
+		...limits === void 0 ? {} : {
+			limits: {
+				heartbeatMs: limits.heartbeatMs,
+				subscriptions: limits.subscriptions,
+				pageItems: limits.pageItems,
+				inFlightRequests: limits.inFlightRequests
+			},
+			...limits.messageSummaries === void 0 ? {} : { messageSummaries: limits.messageSummaries }
+		}
 	};
 }
 /** Narrows an unknown bag to the report's own shapes, dropping everything else. */
@@ -1907,10 +2400,20 @@ function projectDevice(raw) {
 		hosts: Array.isArray(value["hosts"]) ? value["hosts"].map((host) => String(host)) : [],
 		port: typeof value["port"] === "number" ? value["port"] : 0,
 		desktopIdentity: desktopIdentity === "unknown" || /^[0-9a-f]{12}$/.test(desktopIdentity) ? desktopIdentity : digestIdentity(desktopIdentity),
-		...projectLimits(value["limits"])
+		...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) {
+	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
 * shape is rebuilt field by field rather than spread, so a future addition to
@@ -2305,21 +2808,6 @@ const INTERACTIONS_LIST_PAGE_CLAMP = Math.floor(RECORD_BUDGET_BYTES / 25088);
 */
 const MAX_RESUME_TOKEN_CHARS = 4096;
 //#endregion
-//#region src/urlHost.ts
-/**
-* Renders a host as a URL authority component. The device archive and pairing
-* flow store BARE hosts (plan-mandated normalization), so a bare IPv6 literal
-* must be bracketed before it is spliced into a URL — `ws://::1:35543/...`
-* is not a valid URL and `new WebSocket(...)` throws synchronously on it.
-*
-* Shared home for the dial sites: both `connection.ts` (per-device dial) and
-* `pairing.ts` (candidate dial) splice hosts into URLs and must bracket the
-* same way.
-*/
-function urlHost(host) {
-	return host.includes(":") ? `[${host}]` : host;
-}
-//#endregion
 //#region src/connection.ts
 /**
 * The transport call the dial hands a socket to (see
@@ -2417,6 +2905,33 @@ const DEFAULT_BACKOFF_MAX_MS = 6e4;
 const DEFAULT_REFRESH_GRACE_MS = 3e4;
 const DEFAULT_CONNECT_TIMEOUT_MS$1 = 1e4;
 const DEFAULT_PROTOCOL_VERSIONS = [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.
+*/
+const ENDPOINTS_LEARN_TIMEOUT_MS = 2e3;
 /** Ping-silence multiplier: 2×heartbeatMs without a pong judges the line dead. */
 const SILENCE_FACTOR = 2;
 /** The deliberate local-shutdown face of a disposed client (see the replay path). */
@@ -2505,7 +3020,8 @@ var SecondWindowRateLimiter = class {
 	async acquire() {
 		let release;
 		const ahead = this.#queue;
-		this.#queue = ahead.then(() => new Promise((resolve) => release = resolve));
+		const next = () => new Promise((resolve) => release = resolve);
+		this.#queue = ahead.then(next, next);
 		await ahead;
 		try {
 			for (;;) {
@@ -2690,6 +3206,50 @@ function businessWindowFor(reportedInFlightRequests) {
 	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, desktopIdentity) {
+	const answer = result;
+	if (answer.desktopIdentity !== desktopIdentity) return [];
+	const accepted = [];
+	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,
 * 512 in v2.1.6 and v2.1.7 alike; only the shared line moved, 64 ⇒ 256).
@@ -2770,6 +3330,7 @@ var DeviceConnection = class {
 	#protocolVersions;
 	#helloProtocolVersions;
 	#transportRetryWaitMs;
+	#onAdvertisedEndpoints;
 	#stateListeners = /* @__PURE__ */ new Set();
 	/**
 	* Callers parked in {@link waitForSettled}. Separate from the state listeners
@@ -2818,8 +3379,10 @@ var DeviceConnection = class {
 	#pendingPings = /* @__PURE__ */ new Set();
 	#token;
 	#tokenExpiresAt;
+	#wsOptions;
 	constructor(opts) {
 		this.record = opts.record;
+		this.#wsOptions = opts.wsOptions;
 		this.#identity = opts.identity;
 		this.#limiter = new TieredRateLimiter(opts.rateBudgetPerSecond ?? 32, contentBudgetFor(opts.rateBudgetPerSecond));
 		this.#backoffInitialMs = opts.backoffInitialMs ?? DEFAULT_BACKOFF_INITIAL_MS;
@@ -2830,6 +3393,7 @@ var DeviceConnection = class {
 		this.#protocolVersions = opts.protocolVersions ?? DEFAULT_PROTOCOL_VERSIONS;
 		this.#helloProtocolVersions = opts.helloProtocolVersions ?? this.#protocolVersions;
 		this.#transportRetryWaitMs = opts.transportRetryWaitMs ?? 5e3;
+		this.#onAdvertisedEndpoints = opts.onAdvertisedEndpoints;
 	}
 	/**
 	* The business RPC surface: rate-smoothed and gated on `connected`. Typed
@@ -2997,7 +3561,7 @@ var DeviceConnection = class {
 		if (error instanceof ProtocolVersionError) {
 			this.#running = false;
 			this.#setState("offline");
-			console.error(`[cherry-remote] device ${this.record.deviceId}: protocol version incompatible (${error.message}); upgrade Cherry Studio / the plugin`);
+			console.error(`[cherry-remote] device ${this.record.deviceId}: protocol version incompatible (${clipText(error.message, 240)}); upgrade Cherry Studio / the plugin`);
 			this.#cycle.reject(/* @__PURE__ */ new Error(`device ${this.record.deviceId}: protocol version incompatible`));
 			return;
 		}
@@ -3015,7 +3579,8 @@ var DeviceConnection = class {
 		if (!this.#running) return;
 		const delay = this.#backoffDelay();
 		const hint = isAllHostsUnreachable(error) ? " — all candidate addresses were unreachable; if the desktop moved, update them via the device card 地址维护 (address maintenance)" : "";
-		console.warn(`[cherry-remote] device ${this.record.deviceId} offline (${error instanceof Error ? error.message : String(error)}); reconnecting in ${delay}ms${hint}`);
+		const detail = error instanceof Error ? error.message : String(error);
+		console.warn(`[cherry-remote] device ${this.record.deviceId} offline (${clipText(detail, 240)}); reconnecting in ${delay}ms${hint}`);
 		this.#setTimer("backoff", setTimeout(() => this.#tryEstablish(), delay));
 	}
 	#backoffDelay() {
@@ -3029,6 +3594,12 @@ var DeviceConnection = class {
 	* 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
@@ -3046,7 +3617,8 @@ var DeviceConnection = class {
 			if (!this.#running || epoch !== this.#epoch) throw new CancelledError();
 			let link;
 			try {
-				link = await this.#dial(host, this.record.port, epoch);
+				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));
@@ -3067,8 +3639,11 @@ var DeviceConnection = class {
 		throw new AllHostsUnreachableError(this.record.deviceId, this.record.hosts, lastError);
 	}
 	async #dial(host, port, epoch) {
-		const url = `ws://${urlHost(host)}:${port}${remoteConnectPath}`;
-		const ws = new WebSocket(url);
+		const ws = new WebSocket(directEndpointUrl({
+			host,
+			port,
+			security: this.record.security?.[host] ?? "ws"
+		}), this.#wsOptions);
 		const controller = new AbortController();
 		const opened = new Promise((resolve) => ws.once("open", () => resolve()));
 		const failure = new Promise((_, reject) => {
@@ -3133,7 +3708,8 @@ var DeviceConnection = class {
 			heartbeatMs: positive$2(hello.heartbeatMs) ?? FALLBACK_LIMITS.heartbeatMs,
 			subscriptions: positive$2(hello.limits?.["subscriptions"]) ?? FALLBACK_LIMITS.subscriptions,
 			pageItems: positive$2(hello.limits?.["pageItems"]) ?? FALLBACK_LIMITS.pageItems,
-			inFlightRequests: positive$2(hello.limits?.["inFlightRequests"]) ?? FALLBACK_LIMITS.inFlightRequests
+			inFlightRequests: positive$2(hello.limits?.["inFlightRequests"]) ?? FALLBACK_LIMITS.inFlightRequests,
+			...typeof hello.agentMessageSummariesVersion === "number" ? { messageSummaries: hello.agentMessageSummariesVersion } : {}
 		};
 		link.client.updateMaxInFlight(businessWindowFor(this.#limits.inFlightRequests));
 		let auth;
@@ -3144,6 +3720,7 @@ var DeviceConnection = class {
 			if (reason === "GRANT_REVOKED" || reason === "UNAUTHENTICATED") throw new AuthRejectedError(reason);
 			throw error instanceof Error ? error : new Error(String(error));
 		}
+		await this.#learnEndpoints(link, hello.connectionEndpointsVersion);
 		if (epoch !== this.#epoch) {
 			client.dispose();
 			link.channel.close().catch(noop$1);
@@ -3167,6 +3744,51 @@ var DeviceConnection = class {
 		console.info(`[cherry-remote] device ${this.record.deviceId} connected (${digestIdentity(link.channel.remoteIdentity)})`);
 	}
 	/**
+	* 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, capability) {
+		if (capability !== 1) return;
+		try {
+			const endpoints = advertisedEndpoints(await this.#houseCall(link, "connection.endpoints", { domain: "agent" }, ENDPOINTS_LEARN_TIMEOUT_MS), this.record.desktopIdentity);
+			if (endpoints.length === 0) return;
+			const added = mergeAdvertisedEndpoints(this.record, endpoints);
+			if (added > 0) console.info(`[cherry-remote] device ${this.record.deviceId} learned ${added} advertised endpoint(s)`);
+			this.#onAdvertisedEndpoints?.(endpoints);
+		} catch {}
+	}
+	/**
 	* authenticate with the stored token; a stale token (TOKEN_EXPIRED /
 	* UNAUTHENTICATED) is retried exactly once without it before the pairing
 	* is declared invalid.
@@ -3498,24 +4120,56 @@ var PairingError = class extends Error {
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 };
-const PAYLOAD_TYPE = "cherry-studio-pair";
-const PAYLOAD_VERSION = 2;
 /** Overall payload ceiling: a QR code never approaches this. */
 const MAX_PAYLOAD_BYTES = 10240;
-/** `opaqueId` cap for invitationId/invitationSecret/desktopIdentity. */
-const OPAQUE_ID_MAX = 256;
+/**
+* Bounds the unknown-key WARNING (issue #155). The keys in that warning are
+* payload-CONTROLLED NAMES, and `MAX_PAYLOAD_BYTES` is no bound at all on the
+* line: a 10 KiB payload carrying 32 unknown keys of ~256 characters used to
+* join into ~8.2 KB of attacker-chosen text (the measured fixture is 8,192
+* characters of keys and an 8,312-character line) on the operator's log.
+*
+* `UNKNOWN_FIELDS_MAX` is the joined list's budget — the same 240-character
+* working budget as `LOG_TEXT_MAX`, so "one bounded peer detail" means one
+* number for one detail-sized face (pairing's `FAILURE_SEGMENT_MAX` is the
+* same NUMBER bounding a different quantity: a whole `<label>: <detail>`).
+* `UNKNOWN_FIELD_MAX` clips ONE
+* key: 64 characters is longer than any field name the protocol defines, so a
+* clipped key is always a malformed or hostile payload, never a real typo the
+* operator needs whole. A list that stops early names the count (`(+K more)`);
+* entries are never dropped silently.
+*/
+const UNKNOWN_FIELDS_MAX = 240;
+const UNKNOWN_FIELD_MAX = 64;
 /** The claim's deviceName cap; a hostname may reach 253, so it is truncated. */
 const DEVICE_NAME_MAX = 64;
 /** Bounds a single candidate host string (IPv6 literals are ~45). */
 const HOST_MAX$1 = 256;
 /** Matches the protocol's unicodeText: no lone UTF-16 surrogates. */
 const LONE_SURROGATE_RE$1 = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
-/** Fields the implementation consumes; everything else in the payload is ignored. */
-const KNOWN_FIELDS = /* @__PURE__ */ new Set([
+/**
+* The keys each QR ARM consumes (selected by `v`). A payload field outside
+* the MATCHED arm's set is ignored with a warning — the desktop names hosts
+* the design does not use. One union set would silently swallow a v2 payload
+* carrying a spurious `endpoints` (or v3 carrying `ips`/`port`); the arm
+* split keeps the pre-schema warning behavior.
+*/
+const V2_KEYS = /* @__PURE__ */ new Set([
 	"v",
 	"t",
-	"port",
+	"name",
 	"ips",
+	"port",
+	"invitationId",
+	"invitationSecret",
+	"desktopIdentity",
+	"protocolVersions"
+]);
+const V3_KEYS = /* @__PURE__ */ new Set([
+	"v",
+	"t",
+	"name",
+	"endpoints",
 	"invitationId",
 	"invitationSecret",
 	"desktopIdentity",
@@ -3537,12 +4191,12 @@ function invalid(message) {
 function isUnicodeText(value) {
 	return !LONE_SURROGATE_RE$1.test(value);
 }
-function checkString(value, field, max) {
-	if (typeof value !== "string") invalid(`payload field "${field}" must be a string`);
-	if (value.length === 0) invalid(`payload field "${field}" must not be empty`);
-	if (value.length > max) invalid(`payload field "${field}" exceeds ${max} characters`);
-	if (!isUnicodeText(value)) invalid(`payload field "${field}" is not valid unicode text`);
-	return value;
+/** Rejections quote issue PATHS (deduplicated, sorted). The "never inputs"
+* promise is the CALL SITE's property — only `issue.path` is read here; an
+* editor reaching for `issue.message` or `String(error)` must re-check what
+* zod embeds there before keeping that promise. */
+function schemaIssuePaths(error) {
+	return [...new Set(error.issues.map((issue) => issue.path.join(".") || "payload"))].sort().join(", ");
 }
 /**
 * Normalizes one candidate host (ruling 2). The QR may carry IPv6 literals in
@@ -3566,9 +4220,9 @@ function normalizeHost$1(raw) {
 	return inner;
 }
 /**
-* Parses and validates the pairing payload. Unknown fields are ignored (with a
-* warning) — the payload carries host naming the design does not consume — but
-* the fields on the manifest are judged against their protocol caps.
+* Parses and validates the pairing payload against the published
+* `pairingQrSchema` (v2 or v3). Unknown fields are ignored (with a warning);
+* every field judgement is the schema's, capped by the local size rule.
 */
 function parsePayload(payload) {
 	if (Buffer.byteLength(payload, "utf8") > MAX_PAYLOAD_BYTES) invalid(`payload exceeds the ${MAX_PAYLOAD_BYTES}-byte limit`);
@@ -3580,38 +4234,100 @@ function parsePayload(payload) {
 	}
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) invalid("payload must be a JSON object");
 	const raw = parsed;
-	if (raw["v"] !== PAYLOAD_VERSION) invalid(`payload version must be ${PAYLOAD_VERSION}`);
-	if (raw["t"] !== PAYLOAD_TYPE) invalid(`payload type must be "${PAYLOAD_TYPE}"`);
-	const ignored = Object.keys(raw).filter((key) => !KNOWN_FIELDS.has(key));
-	if (ignored.length > 0) console.warn(`[cherry-remote] pairing payload ignored unknown field(s): ${ignored.join(", ")}`);
-	const port = raw["port"];
-	if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) invalid("payload field \"port\" must be an integer in 1..65535");
 	const ips = raw["ips"];
-	if (!Array.isArray(ips) || ips.length === 0) invalid("payload field \"ips\" must be a non-empty array");
-	const hosts = ips.map((entry, index) => normalizeHost$1(checkString(entry, `ips[${index}]`, HOST_MAX$1)));
-	const invitationId = checkString(raw["invitationId"], "invitationId", OPAQUE_ID_MAX);
-	const invitationSecret = checkString(raw["invitationSecret"], "invitationSecret", OPAQUE_ID_MAX);
-	const desktopIdentity = checkString(raw["desktopIdentity"], "desktopIdentity", OPAQUE_ID_MAX);
-	const versions = raw["protocolVersions"];
-	if (!Array.isArray(versions) || versions.length === 0) invalid("payload field \"protocolVersions\" must be a non-empty array");
+	const input = Array.isArray(ips) ? {
+		...raw,
+		ips: ips.map((entry) => typeof entry === "string" ? normalizeHost$1(entry) : entry)
+	} : raw;
+	const result = pairingQrSchema.safeParse(input);
+	if (!result.success) invalid(`payload rejected by the pairing QR schema (v2 or v3): ${schemaIssuePaths(result.error)}`);
+	const qr = result.data;
+	const ignored = Object.keys(raw).filter((key) => !(qr.v === 2 ? V2_KEYS : V3_KEYS).has(key));
+	if (ignored.length > 0) console.warn(`[cherry-remote] pairing payload ignored unknown field(s): ${boundedJoin(ignored, {
+		max: UNKNOWN_FIELDS_MAX,
+		itemMax: UNKNOWN_FIELD_MAX
+	})}`);
+	const candidates = qr.v === 2 ? qr.ips.map((host) => ({
+		host,
+		port: qr.port,
+		security: "ws"
+	})) : qr.endpoints.map((endpoint) => ({
+		host: endpoint.host,
+		port: endpoint.port,
+		security: endpoint.security
+	}));
+	const seenHosts = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		if (!Number.isInteger(candidate.port) || candidate.port < 1 || candidate.port > 65535) invalid(`payload endpoint "${candidate.host}": port must be an integer in 1..65535`);
+		if (seenHosts.has(candidate.host)) invalid(`payload endpoints must not repeat host "${candidate.host}"`);
+		seenHosts.add(candidate.host);
+	}
+	for (const field of [
+		"invitationId",
+		"invitationSecret",
+		"desktopIdentity"
+	]) if (!isUnicodeText(qr[field])) invalid(`payload field "${field}" is not valid unicode text`);
+	try {
+		peerIdFromString(qr.desktopIdentity);
+	} catch {
+		invalid("payload field \"desktopIdentity\" is not a peer id");
+	}
 	return {
-		hosts,
-		port,
-		invitationId,
-		invitationSecret,
-		desktopIdentity,
-		protocolVersions: versions.map((version) => {
-			if (typeof version !== "number" || !Number.isInteger(version)) invalid("payload field \"protocolVersions\" must contain integers");
-			return version;
-		})
+		candidates,
+		invitationId: qr.invitationId,
+		invitationSecret: qr.invitationSecret,
+		desktopIdentity: qr.desktopIdentity,
+		protocolVersions: qr.protocolVersions
 	};
 }
 const DEFAULT_SUPPORTED_PROTOCOL_VERSIONS = [1];
 const DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+/**
+* ONE aggregate budget for the candidate DIAL walk (issue #141). A v3 QR admits
+* up to 32 endpoints, so 32 serial `connectTimeoutMs` dials could spend 320 s
+* on an invitation that lives 120 s. It bounds the SUM, never one attempt.
+*/
+const DEFAULT_DIAL_BUDGET_MS = 3e4;
 const DEFAULT_POLL_INTERVAL_MS = 1e3;
 /** The protocol invitationMs: 120s of invitation, and our poll race guard. */
 const DEFAULT_POLL_TIMEOUT_MS = 12e4;
 const VERIFICATION_CODE_RE = /^[0-9]{6}$/;
+/** Bounds the close frame's reason text quoted into a candidate failure. */
+const CLOSE_REASON_MAX = 200;
+/**
+* Bounds ONE candidate failure segment of the joined `unreachable` verdict
+* (issue #148). Unbounded, a v3 QR's 32 endpoints × a 253-char host — repeated
+* again inside the dial error — reached ~17-18 KB in one tool result that
+* `cherry_pair` passes through whole. The bound is per SEGMENT, never a
+* "first N + and M more" cut: issue #141's contract is that every candidate,
+* attempted or not, is NAMED.
+*
+* `FAILURE_LABEL_MAX` clips an over-long `host:port` in the HOST and keeps the
+* PORT (`<host prefix>…:<port>`) — a prefix without its port names no address.
+* `FAILURE_SEGMENT_MAX` bounds the whole `<label>: <detail>`: the detail is
+* clipped to the room the label leaves, and the `… (+N chars)` marker's own
+* length is charged to the bound. 32 candidates then join to at most
+* 32 × 240 + 31 × 2 = 7,742 characters.
+*/
+const FAILURE_LABEL_MAX = 128;
+const FAILURE_SEGMENT_MAX = 240;
+/**
+* Bounds the progress line's HOST TEXT (issue #152). `report()` runs once per
+* stage transition and used to join every candidate host: a v3 QR admits 32
+* endpoints and a host name may be 253 characters, so one stage wrote ~8 KB.
+*
+* The FIRST host is always shown — a line with no host at all would lose the
+* run's identity — then further hosts are appended while the host NAMES fit
+* this budget; a truncated list carries an explicit `(+K more)` marker that
+* rides ON TOP of the budget (the marker is a COUNT, not a host name).
+*
+* Invariant: the host names consume ≤ `STAGE_HOSTS_CHARS`, with ONE exception
+* — a FIRST host that alone exceeds it, still shown because the identity rule
+* outranks the bound. A LATER over-long host can never enter the bounded
+* section (`used` already holds the first host, so it fails the fit test) and
+* is omitted into the marker.
+*/
+const STAGE_HOSTS_CHARS = 160;
 const noop = () => {};
 /** A callable silent libp2p logger (same shape as the connection layer's). */
 function makeSilentLogger() {
@@ -3626,8 +4342,75 @@ const silentComponentLogger = { forComponent: () => makeSilentLogger() };
 function sleep$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+* Tags a PRE-OPEN `ws` error as a candidate-dial failure (issue #142). The
+* `websocket:` prefix is the KIND: the operator's fix is this address or its
+* TLS, not the network — the contrast with `timeout:` is the whole point of the
+* prefix, and it is what the joined `unreachable` verdict shows. The `ws` error
+* carries the discriminator a bare message drops — an OS `code`
+* (`ECONNREFUSED`, `ENOTFOUND`, a TLS code) or a numeric ws code — so it is
+* appended, and only when it is actually a string or a number (never
+* `undefined`/`null`).
+*/
+function webSocketFailure(error) {
+	const code = error.code;
+	const suffix = typeof code === "string" || typeof code === "number" ? ` (code ${code})` : "";
+	return /* @__PURE__ */ new Error(`websocket: ${error.message}${suffix}`);
+}
+/**
+* Tags a POST-OPEN channel failure as a candidate-dial failure (issue #147).
+* `channel:` is the THIRD kind, deliberately not `websocket:`: the upgrade
+* completed, so the address works and only the channel's establishment failed
+* (Noise handshake, remote identity proof, protocol offer). Blaming the
+* address would send the operator to inspect something that demonstrably
+* answered. No code suffix is appended: a Noise-stage error can carry its own
+* string code (`ERR_INVALID_CRYPTO_EXCHANGE`), but that is an internal label
+* rather than the ws/OS discriminator the other kinds keep, so it is
+* deliberately dropped.
+*/
+function channelFailure(error) {
+	return /* @__PURE__ */ new Error(`channel: ${error.message}`);
+}
+/**
+* The ONE text form of a candidate failure (issue #148). All three
+* `failures.push` sites render through it, so the segment bound cannot hold on
+* one arm (budget-exhausted, dial failure, claim fall-through) and fail on
+* another. A short label and a short detail are returned BYTE FOR BYTE; the
+* enforcement is never a rewrite of ordinary text.
+*
+* The detail goes through the SHARED {@link clipText} (issue #155), the same
+* `… (+N chars)` form every other peer-controlled log detail uses; the clip
+* point is no longer private to pairing.
+*/
+function failureSegment(label, detail) {
+	const boundedLabel = clipFailureLabel(label);
+	const room = FAILURE_SEGMENT_MAX - boundedLabel.length - 2;
+	if (room <= 0) return boundedLabel.slice(0, FAILURE_SEGMENT_MAX);
+	return `${boundedLabel}: ${clipText(detail, room)}`;
+}
+/**
+* Clips a `host:port` label in the HOST, keeping the port (see
+* {@link FAILURE_LABEL_MAX}).
+*
+* Identification here is PREFIX + PORT, not uniqueness: two schema-distinct
+* 253-char hosts that agree on their first ~121 characters AND on the port clip
+* to identical labels (ports may repeat — only hosts are deduped). Each still
+* contributes its own segment, so #141's per-candidate count is intact.
+*/
+function clipFailureLabel(label) {
+	if (label.length <= FAILURE_LABEL_MAX) return label;
+	const colon = label.lastIndexOf(":");
+	if (colon < 0) return `${label.slice(0, 127)}…`;
+	const suffix = `…${label.slice(colon)}`;
+	const hostRoom = FAILURE_LABEL_MAX - suffix.length;
+	return hostRoom > 0 ? `${label.slice(0, hostRoom)}${suffix}` : suffix.slice(0, FAILURE_LABEL_MAX);
+}
 /** Dials one candidate address and completes the Noise handshake.
 *
+* The URL is the published `directEndpointUrl` — it brackets IPv6 literals,
+* appends the fixed `/v1/remote/connect` path, and selects `ws:` or `wss:`
+* from the candidate's own `security` (v3 TLS-proxy endpoints dial TLS).
+*
 * Both halves start concurrently (`Promise.all`): the peer's accept half is
 * already running on its side, so a sequential dial would deadlock the
 * prelude.
@@ -3638,28 +4421,54 @@ function sleep$1(ms) {
 * rather than assumed: the payload's `desktopIdentity` is the peer the Noise
 * XX handshake must prove, so a swapped-in impostor fails the handshake
 * instead of being pinned as the desktop.
-*/
-async function dial(host, port, identity, desktopIdentity, protocolVersions, timeoutMs) {
-	const ws = new WebSocket(`ws://${urlHost(host)}:${port}${remoteConnectPath}`);
+*
+* A failure carries one of THREE kinds into the joined `unreachable` verdict,
+* because each names the operator's next check: `timeout:` (the per-attempt
+* timer won its race — check the network), `websocket:` (the socket failed
+* BEFORE the upgrade — check this address or its TLS), and `channel:` (the
+* socket came up and the channel failed AFTER it — check the peer's identity
+* or the protocol offer). A stalled handshake stays `timeout:`: the dial
+* promise's own timer settles first, so the abort it triggers cannot win.
+*/
+async function dial(candidate, identity, desktopIdentity, protocolVersions, timeoutMs, wsOptions) {
+	const { host, port } = candidate;
+	const ws = new WebSocket(directEndpointUrl(candidate), wsOptions);
 	const controller = new AbortController();
 	let timer;
 	const timedOut = new Promise((_, reject) => {
-		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`connect to ${host}:${port} timed out`)), timeoutMs);
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`timeout: connect to ${host}:${port} timed out`)), timeoutMs);
 	});
 	try {
 		const connecting = (async () => {
 			await new Promise((resolve, reject) => {
-				ws.once("open", () => resolve());
-				ws.once("error", (error) => reject(error));
-			});
-			const stream = new RemoteSocketStream(toRemoteSocket(ws), silentComponentLogger.forComponent("pairing"), "outbound");
-			return connectSecureChannel(stream, {
-				identity,
-				logger: silentComponentLogger,
-				protocolVersions: [...protocolVersions],
-				signal: controller.signal,
-				remoteIdentity: desktopIdentity
+				const settle = (outcome) => {
+					ws.off("open", onOpen);
+					ws.off("error", onError);
+					ws.off("close", onClose);
+					outcome();
+				};
+				const onOpen = () => settle(resolve);
+				const onError = (error) => settle(() => reject(webSocketFailure(error)));
+				const onClose = (code, reason) => {
+					const text = reason.toString("utf8").slice(0, CLOSE_REASON_MAX);
+					settle(() => reject(/* @__PURE__ */ new Error(`websocket: closed before open (code ${code})${text === "" ? "" : ` ${text}`}`)));
+				};
+				ws.once("open", onOpen);
+				ws.once("error", onError);
+				ws.on("close", onClose);
 			});
+			try {
+				const stream = new RemoteSocketStream(toRemoteSocket(ws), silentComponentLogger.forComponent("pairing"), "outbound");
+				return await connectSecureChannel(stream, {
+					identity,
+					logger: silentComponentLogger,
+					protocolVersions: [...protocolVersions],
+					signal: controller.signal,
+					remoteIdentity: desktopIdentity
+				});
+			} catch (error) {
+				throw channelFailure(error instanceof Error ? error : new Error(String(error)));
+			}
 		})();
 		const channel = await Promise.race([connecting, timedOut.finally(() => controller.abort(/* @__PURE__ */ new Error("pairing connect timed out")))]);
 		return {
@@ -3692,6 +4501,27 @@ function rpcReason(error) {
 	}
 }
 /**
+* Renders the progress line's host list under {@link STAGE_HOSTS_CHARS} (the
+* invariant lives on that constant). A truncated list names the first host,
+* then says how many candidates it is NOT naming — the count is explicit so a
+* reader can tell a short host list from a bounded one.
+*/
+function stageHosts(hosts) {
+	const [first, ...rest] = hosts;
+	if (first === void 0) return "";
+	let text = first;
+	let used = first.length;
+	let shown = 1;
+	for (const host of rest) {
+		if (used + host.length + 2 > STAGE_HOSTS_CHARS) break;
+		text += `, ${host}`;
+		used += host.length + 2;
+		shown += 1;
+	}
+	const omitted = hosts.length - shown;
+	return omitted > 0 ? `${text} (+${omitted} more)` : text;
+}
+/**
 * Pairs this DSH profile with a Cherry Studio desktop from its pairing payload,
 * returning the PERSISTED record (ruling 6).
 *
@@ -3712,35 +4542,45 @@ async function pairWithPayload(opts) {
 	const payload = parsePayload(opts.payload);
 	const onStatus = opts.onStatus ?? noop;
 	const report = (stage) => {
-		console.info(`[cherry-remote] pairing stage ${stage} (hosts: ${payload.hosts.join(", ")})`);
+		console.info(`[cherry-remote] pairing stage ${stage} (hosts: ${stageHosts(payload.candidates.map((candidate) => candidate.host))})`);
 		onStatus(stage);
 	};
 	report("validate");
 	const supported = opts.supportedProtocolVersions ?? DEFAULT_SUPPORTED_PROTOCOL_VERSIONS;
 	const offered = payload.protocolVersions.filter((version) => supported.includes(version));
 	const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+	const dialBudgetMs = typeof opts.dialBudgetMs === "number" && Number.isFinite(opts.dialBudgetMs) ? opts.dialBudgetMs : DEFAULT_DIAL_BUDGET_MS;
+	const dialDeadline = performance.now() + dialBudgetMs;
 	report("connect");
 	const failures = [];
-	for (const host of payload.hosts) {
+	let approved;
+	for (const candidate of payload.candidates) {
+		const label = `${candidate.host}:${candidate.port}`;
+		const remaining = dialDeadline - performance.now();
+		if (remaining <= 0) {
+			failures.push(failureSegment(label, `not attempted (the ${dialBudgetMs} ms dial budget was exhausted before this candidate)`));
+			continue;
+		}
 		let temp;
 		try {
-			temp = await dial(host, payload.port, opts.identity, payload.desktopIdentity, offered, connectTimeoutMs);
+			temp = await dial(candidate, opts.identity, payload.desktopIdentity, offered, Math.min(connectTimeoutMs, remaining), opts.wsOptions);
 		} catch (error) {
-			failures.push(`${host}: ${error instanceof Error ? error.message : String(error)}`);
+			failures.push(failureSegment(label, error instanceof Error ? error.message : String(error)));
 			continue;
 		}
 		try {
-			const record = await claimAndAwait(temp.client, payload, offered, opts, report);
+			approved = await claimAndAwait(temp.client, payload, offered, opts, report, candidate);
 			destroy(temp);
-			opts.store.upsert(record);
-			return record;
+			break;
 		} catch (error) {
 			destroy(temp);
 			if (error instanceof PairingError) throw error;
-			failures.push(`${host}: ${error instanceof Error ? error.message : String(error)}`);
+			failures.push(failureSegment(label, error instanceof Error ? error.message : String(error)));
 		}
 	}
-	throw new PairingError("unreachable", `no candidate address could complete pairing (${failures.join("; ")})`);
+	if (approved === void 0) throw new PairingError("unreachable", `no candidate address could complete pairing (${failures.join("; ")})`);
+	opts.store.upsert(approved);
+	return approved;
 }
 /**
 * The RPC half of one candidate: confirm the protocol, claim, present the code,
@@ -3748,7 +4588,7 @@ async function pairWithPayload(opts) {
 * deviceId, grants and token (ruling 3) — the claim receipt carries the code
 * and nothing else.
 */
-async function claimAndAwait(client, payload, protocolVersions, opts, onStatus) {
+async function claimAndAwait(client, payload, protocolVersions, opts, onStatus, candidate) {
 	const deviceName = (opts.name ?? hostname()).slice(0, DEVICE_NAME_MAX);
 	try {
 		await client.request("connection.hello", { protocolVersions: [...protocolVersions] });
@@ -3782,7 +4622,7 @@ async function claimAndAwait(client, payload, protocolVersions, opts, onStatus)
 		}
 		if (result.status === "rejected") throw new PairingError("rejected", "the desktop rejected this pairing request — verify that the 6-digit code shown on the desktop side matches the code this harness displayed, then generate a fresh pairing payload and try again");
 		if (result.status === "expired") throw new PairingError("expired", "the pairing invitation has expired — regenerate the pairing code in Cherry Studio (the remote-access QR/payload) and retry");
-		if (result.status === "approved") return recordFrom(payload, result, deviceName);
+		if (result.status === "approved") return recordFrom(payload, result, deviceName, candidate);
 		if (Date.now() >= deadline) throw new PairingError("expired", "the pairing invitation expired while waiting for approval — regenerate the pairing code in Cherry Studio and retry");
 		await sleep$1(interval);
 	}
@@ -3793,18 +4633,34 @@ async function claimAndAwait(client, payload, protocolVersions, opts, onStatus)
 * `displayName` is the name the claim actually carried — the record must not
 * disagree with what the desktop shows for this device, and re-deriving it
 * here would lose the 64-char truncation.
-*/
-function recordFrom(payload, approved, deviceName) {
+*
+* The address projection: every candidate host is kept (the v2 record always
+* did, and reconnect re-walks them), and `port` is the one the pairing actually
+* completed on — the WINNER's port, and the record-level fallback. A mixed-port
+* v3 payload is now persisted FAITHFULLY, per host, through `ports` (issue
+* #135): the 2.1.8 generation side emits one endpoint per custom-address
+* invitation (`ApiGatewayService.getRemoteEndpoint`:
+* `advertisedEndpoint ? [advertisedEndpoint] : …`), but a QR that does carry a
+* mixed list must still reconnect each host on its own port. `security` IS
+* persisted (issue #126), one entry per host, taken from the very candidates the
+* walk dialed — so a schemaVersion-4 record remembers the scheme the pairing
+* actually used, and the steady-state dial (src/connection.ts) rebuilds the
+* same URL instead of a plain `ws://`. Before that, #124 paired a TLS endpoint
+* and made it unreachable on every reconnect.
+*/
+function recordFrom(payload, approved, deviceName, winner) {
 	const grants = (approved.authorization?.grants ?? []).map((grant) => grant.domain).filter((domain) => domain === "agent");
 	if (grants.length === 0) throw new PairingError("rejected", "the desktop approved no agent capability for this device");
 	const tokenExpiresAt = Date.parse(approved.expiresAt);
 	if (!Number.isFinite(tokenExpiresAt)) throw new PairingError("rejected", `the desktop approved the pairing with an unreadable token expiry (${JSON.stringify(approved.expiresAt)}); re-pair the device`);
 	return {
-		schemaVersion: 2,
+		schemaVersion: 4,
 		deviceId: approved.deviceId,
 		displayName: deviceName,
-		hosts: [...payload.hosts],
-		port: payload.port,
+		hosts: payload.candidates.map((candidate) => candidate.host),
+		port: winner.port,
+		security: Object.fromEntries(payload.candidates.map((candidate) => [candidate.host, candidate.security])),
+		ports: Object.fromEntries(payload.candidates.map((candidate) => [candidate.host, candidate.port])),
 		desktopIdentity: payload.desktopIdentity,
 		grants,
 		accessToken: approved.accessToken,
@@ -3822,7 +4678,7 @@ function asPairingError(error, stage) {
 	if (error instanceof PairingError) return error;
 	const reason = rpcReason(error);
 	if (reason !== void 0) return new PairingError("rejected", `the desktop refused the pairing ${stage} (${reason})`);
-	return new PairingError("unreachable", `pairing ${stage} failed: ${error instanceof Error ? error.message : String(error)}`);
+	return new PairingError("unreachable", failureSegment(`pairing ${stage} failed`, error instanceof Error ? error.message : String(error)));
 }
 //#endregion
 //#region src/subscriptions.ts
@@ -4345,7 +5201,7 @@ var SessionSubscriptions = class {
 		try {
 			await this.#rpc.request("agent.subscriptions.close", { subscriptionId });
 		} catch (error) {
-			console.warn(`[cherry-remote] closing subscription ${subscriptionId} failed`, error);
+			console.warn(`[cherry-remote] closing subscription ${subscriptionId} failed: ${failureText(error)}`);
 		}
 	}
 	/**
@@ -4680,6 +5536,42 @@ const TERMINAL_EXECUTION_STATUSES = [
 ];
 /** The protocol's single-page hard cap, used only as the pre-hello ceiling. */
 const PAGE_ITEMS_FALLBACK = 100;
+/**
+* The page this bridge asks for when the peer's hello advertised
+* `agentMessageSummariesVersion: 1` (issue #105).
+*
+* WHY IT IS NOT {@link LIST_PAGE_CLAMP} (16): that clamp is metadata-BLIND. It
+* exists because `AgentMessage` carries `partIds` — up to 4,096 entries of
+* schema-capped ids each — so a count-only peer can answer a page the 65,536-byte
+* record cannot hold and the transport kills the connection (`defaults.ts`).
+* What `partsMode: 'paged'` returns is `AgentMessageSummary`: identity,
+* revision, role, status and optional usage/model/failure, and NO `partIds`.
+*
+* WHY THE PAGE BOUND IS THE PEER'S, NOT OURS: the ONLY verified advertiser of
+* the capability (desktop 2.1.8) budgets the ACCUMULATED page — `pageOf`
+* prefix-truncates at `PAGE_ITEM_BYTES` = 62,279 bytes and `queryPage` re-asks
+* at a halved limit, so its reply records stay under `recordBytes` = 65,536
+* whatever our `limit` says, answering with a SHORT page + `nextCursor` (the
+* shape our walk already tolerates) instead of a killed link. The single-item
+* `RESOURCE_EXHAUSTED {ITEM_TOO_LARGE, retryable: false}` refusal is the
+* exception arm, and a schema-valid summary row cannot reach it: measured
+* against the 0.7.0 schema, the worst row (ids at 256 units, `model` fields at
+* 2,048 chars each, 32 `costs` entries, `failure` refined to ≤4,096 bytes) is
+* ≈37 KB — under the 62,279 budget, so the refusal exists for full
+* `partIds`-bearing rows, not summaries.
+*
+* 100 is the protocol's own `pageItems` cap, i.e. the ceiling a walk can use at
+* all: `#aggregate` still intersects this with the peer's NEGOTIATED
+* `pageItems`, so a peer advertising less keeps its size. Residual exposure —
+* a hypothetical peer advertising the capability WITHOUT a page budget —
+* contains no verified desktop (≤2.1.7 never advertises and keeps the clamp),
+* the same "pragmatic, not provable" class `defaults.ts` already scopes.
+*
+* The PARTS walk keeps {@link PARTS_LIST_PAGE_CLAMP} unconditionally: nothing
+* in protocol 0.7.0 proves `agent.parts.list` is byte-aware, and a part is the
+* fattest item there is.
+*/
+const MESSAGE_SUMMARIES_PAGE_ITEMS = PAGE_ITEMS_FALLBACK;
 /** The largest MESSAGE aggregate a caller may ask for; the per-page clamp still applies. */
 const MAX_AGGREGATE_LIMIT = 1e3;
 /**
@@ -4768,6 +5660,33 @@ const DEFAULT_PARTS_SAFETY_BOUND = 1e4;
 * returning a partial (or empty) result as though it were complete.
 */
 const MAX_AGGREGATE_PAGES = 1e4;
+/**
+* The `agent.messages.list` request for ONE message walk, and the page size to
+* ask for — the ONE place the paged-summaries dialect is decided (issue #105).
+*
+* THE INVARIANT: `partsMode` is sent ONLY to a peer whose own hello advertised
+* `agentMessageSummariesVersion: 1`. 0.5.0's params schema — what every desktop
+* through 2.1.7 ships — is a STRICT object with no such key, so sending it
+* there is a protocol violation, not a wasted field. Both message-walk faces
+* (`cherry_read` and the terminal/timeout/idle aggregate) come through HERE for
+* the same reason the resume token has one helper: two call sites spelling the
+* dialect would eventually disagree about which peer may hear it.
+*
+* With the capability, the page size is {@link MESSAGE_SUMMARIES_PAGE_ITEMS} —
+* summary rows are metadata, so the byte-safe clamp no longer bounds anything
+* they can carry. Without it, the clamp stays exactly as it was: the
+* count-paged peer still returns `partIds`-bearing rows.
+*/
+function messageListRequest(connection) {
+	if (connection.limits.messageSummaries === 1) return {
+		params: { partsMode: "paged" },
+		maxPerPage: MESSAGE_SUMMARIES_PAGE_ITEMS
+	};
+	return {
+		params: {},
+		maxPerPage: 16
+	};
+}
 /** Token prefix for a peer page position; the one `#aggregate` can send back. */
 const RESUME_CURSOR_PREFIX = "cursor:";
 /** Token prefix for "strictly older than this message id". */
@@ -5106,6 +6025,44 @@ function failureReason(error) {
 	if (isRecord(data) && typeof data["reason"] === "string") return data["reason"];
 }
 /**
+* The phrase this hint leaves behind, so applying it twice reads once.
+*/
+const PEER_REFUSAL_FINAL_MARK = "retrying the same request cannot help";
+/**
+* The recovery advice a PERMANENT peer refusal grows — `RESOURCE_EXHAUSTED`
+* carrying `details.retryable === false`, which is the desktop's per-item byte
+* budget (`PAGE_ITEM_BYTES` = 62,279; `details.kind` is `ITEM_TOO_LARGE` with
+* `itemBytes` / `budgetBytes`), issue #105.
+*
+* WHY THE WARNING HAS TO BE ADDED: the official client marks every
+* `RESOURCE_EXHAUSTED` RETRYABLE and re-asks at the same page size on an
+* exponential backoff, so a byte-budget refusal never converges — and the
+* condition really is permanent: the same item over the same budget will be
+* over it again. A caller (or a model reading the error) that retries learns
+* nothing but spends the peer's rate window.
+*
+* The sentence is deliberately narrower than the reason: only the
+* `retryable === false` shape grows it. Every other `RESOURCE_EXHAUSTED` —
+* the upload window, the subscription cap, a legacy refusal with no `details` —
+* keeps its own text, because some of those ARE worth a later retry.
+*
+* Like {@link withIdempotencyHint} this EXTENDS `message` only: the reason, the
+* structured `data` and the {@link JsonRpcRequestError} identity stay the
+* peer's, so branching callers see exactly what it sent.
+*/
+function withPeerRefusalHint(error) {
+	if (!(error instanceof JsonRpcRequestError)) return error;
+	if (failureReason(error) !== "RESOURCE_EXHAUSTED") return error;
+	const data = error.data;
+	if (!isRecord(data) || !isRecord(data["details"]) || data["details"]["retryable"] !== false) return error;
+	if (error.message.includes(PEER_REFUSAL_FINAL_MARK)) return error;
+	const kind = optionalString(data["details"]["kind"]);
+	const cause = kind === "ITEM_TOO_LARGE" ? "an ITEM_TOO_LARGE page item over its byte budget" : "the same item";
+	const tail = kind === "ITEM_TOO_LARGE" ? "the item ITSELF exceeds the peer’s per-item budget, so no page size or request shape can fetch it (nor the items behind it — upstream #21951)" : "ask for FEWER items per page (a smaller `limit`), which is the only change that can fit the budget";
+	error.message = `${error.message} — the peer marked this refusal permanent (\`details.retryable: false\`: ${cause}); retrying the same request cannot help — ${tail}`;
+	return error;
+}
+/**
 * One `{ref}`'s content could not be TRUSTED: the bytes served do not match the
 * digest the ref advertises (or there was no digest to check against).
 *
@@ -5313,6 +6270,54 @@ function optionalString(value) {
 	return typeof value === "string" && value !== "" ? value : void 0;
 }
 /**
+* The `hosts` argument of `cherry_devices`' write actions (issue #185): a
+* non-empty list of non-empty host names, with no case-variant duplicate.
+*
+* Each rule is a state the store would have to interpret: an empty name can
+* never match a dialed host, and two spellings of one host would make "is this
+* address forgotten?" depend on which entry a comparison hit first. Values are
+* TRIMMED here (the model-facing surface is where a stray space is caught);
+* the archive then stores the spelling it already had for a dialed host.
+*/
+function hostListArgument(value) {
+	if (!Array.isArray(value) || value.length === 0) return {
+		error: "invalid-hosts",
+		message: "`hosts` must be a non-empty array of host names"
+	};
+	const hosts = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of value) {
+		if (typeof entry !== "string" || entry.trim() === "") return {
+			error: "invalid-hosts",
+			message: "`hosts` entries must be non-empty strings"
+		};
+		let host = entry.trim();
+		if (host.startsWith("[") && host.endsWith("]")) {
+			try {
+				new URL(`http://${host}/`);
+			} catch {
+				return {
+					error: "invalid-hosts",
+					message: `\`hosts\` entry "${host}" is not a valid IPv6 literal`
+				};
+			}
+			host = host.slice(1, -1);
+		}
+		if (host.length > 256) return {
+			error: "invalid-hosts",
+			message: "`hosts` entry exceeds 256 characters"
+		};
+		const key = host.toLowerCase();
+		if (seen.has(key)) return {
+			error: "invalid-hosts",
+			message: `\`hosts\` names "${host}" more than once (host names are case-insensitive)`
+		};
+		seen.add(key);
+		hosts.push(host);
+	}
+	return hosts;
+}
+/**
 * The peer's `agent.messages.send` refusal for a STALE `expectedIdleRevision`,
 * in the exact shape Cherry Studio answers it: a `rejected` receipt whose
 * `error` is `{reason: 'CONFLICT', message: 'Session is not idle at the
@@ -5434,7 +6439,19 @@ function registerCherryToolsWithEngine(ctx, deps, options = {}) {
 		}
 	};
 }
-/** One tool declaration, in the exact shape the host registry consumes. */
+/**
+* One tool declaration, in the exact shape the host registry consumes.
+*
+* This helper adds no result WRAPPER and this ticket adds no result-side
+* truncation (issue #161): a tool result is the MODEL's signal, and the peer is
+* the user's own Noise-authenticated desktop, so shortening the peer's
+* explanation costs the caller the text it acts on. The two result-text clamps
+* that DO exist are per-field product choices, not a log rule — `aggregateError`
+* (`message.slice(0, 200)` in `#assemblyFailed`) and `truncateErrorMessage`'s
+* 200-character diagnostics digest used by `projectMessageFailure`. The LOG
+* face is where boundedness is required (`failureText` / `clipText` in `src/text.ts`);
+* this ticket's sweep does not change tool output.
+*/
 function defineCherryTool(definition) {
 	return {
 		name: definition.name,
@@ -5902,7 +6919,7 @@ var CherryToolEngine = class {
 				result = await connection.rpc.request(method, request, deadline === void 0 ? void 0 : { deadline: deadline.instant });
 			} catch (error) {
 				if (deadline !== void 0 && deadlineExhaustion(error)) return this.#truncated(items, "deadline", cursor);
-				throw error;
+				throw withPeerRefusalHint(error);
 			}
 			const extracted = extract(result);
 			if (extracted.notAnArray !== void 0) throw new Error(`${method}: peer answered a page whose \`items\` is not an array (\`items\` is ${extracted.notAnArray}) for ${JSON.stringify(params)}; refusing a silently short result — every page of a paged list must carry an items array`);
@@ -5981,26 +6998,86 @@ var CherryToolEngine = class {
 	#devicesTool() {
 		return defineCherryTool({
 			name: "cherry_devices",
-			description: "List every paired Cherry Studio desktop with its connection state (connected/connecting/offline/disabled/identity-mismatch). An optional `device` narrows the list to one device (display name prefix or deviceId).",
+			description: "List every paired Cherry Studio desktop with its connection state (connected/connecting/offline/disabled/identity-mismatch). An optional `device` narrows the list to one device (display name prefix or deviceId). `action: \"forget\"` removes the named `hosts` from that device's dial candidates AND stops the desktop's advertisements from adding them back; `action: \"remember\"` lifts that mark, so the next handshake may learn them again. Both write actions require `device` and `hosts`.",
 			parameters: {
 				type: "object",
-				properties: { device: {
-					type: "string",
-					description: "Optional device selector: exact deviceId, or a unique prefix of a deviceId or display name."
-				} },
+				properties: {
+					device: {
+						type: "string",
+						description: "Optional device selector: exact deviceId, or a unique prefix of a deviceId or display name."
+					},
+					action: {
+						type: "string",
+						enum: [
+							"list",
+							"forget",
+							"remember"
+						],
+						description: "What to do: `list` (the default) reads the devices; `forget`/`remember` edit ONE device's forgotten addresses and require `device` and `hosts`."
+					},
+					hosts: {
+						type: "array",
+						items: { type: "string" },
+						description: "For `forget`/`remember`: the host names to act on, matched case-insensitively. `forget` refuses to remove the last remaining address."
+					}
+				},
 				additionalProperties: false
 			},
 			execute: async (args) => {
+				const action = optionalString(args["action"]) ?? "list";
+				if (action !== "list" && action !== "forget" && action !== "remember") return {
+					error: "invalid-action",
+					message: "`action` accepts exactly \"list\", \"forget\" or \"remember\""
+				};
 				const selector = optionalString(args["device"]);
+				if (action === "list") {
+					const quarantined = this.#quarantineVerdict();
+					if (quarantined !== void 0) return quarantined;
+					if (selector === void 0) {
+						const records = this.#deps.store.list();
+						return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) };
+					}
+					const selected = this.#selectRecords(selector);
+					if (!Array.isArray(selected)) return selected;
+					return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) };
+				}
+				if (selector === void 0) return {
+					error: "device-required",
+					message: "`action` \"forget\"/\"remember\" needs `device`: a selector that names exactly one device"
+				};
+				const hosts = hostListArgument(args["hosts"]);
+				if (!Array.isArray(hosts)) return hosts;
 				const quarantined = this.#quarantineVerdict();
 				if (quarantined !== void 0) return quarantined;
-				if (selector === void 0) {
-					const records = this.#deps.store.list();
-					return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) };
-				}
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
-				return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) };
+				const record = selected[0];
+				let removed = [];
+				let marked = [];
+				let restored = [];
+				try {
+					if (action === "forget") ({removed, marked} = this.#deps.store.forgetEndpoints(record.deviceId, hosts));
+					else ({restored} = this.#deps.store.rememberEndpoints(record.deviceId, hosts));
+				} catch (error) {
+					if (error instanceof LastCandidateHostError) return {
+						error: "last-address",
+						device: record.deviceId,
+						message: error.message
+					};
+					throw error;
+				}
+				if (removed.length > 0 || marked.length > 0 || restored.length > 0) await this.#deps.evict(record.deviceId);
+				const fresh = this.#deps.store.list().find((entry) => entry.deviceId === record.deviceId);
+				if (fresh === void 0) return this.#notFoundVerdict(selector);
+				const device = await this.#deviceView(fresh);
+				return action === "forget" ? {
+					device,
+					removed,
+					marked
+				} : {
+					device,
+					restored
+				};
 			}
 		});
 	}
@@ -6054,7 +7131,8 @@ var CherryToolEngine = class {
 			state,
 			enabled: record.enabled,
 			hosts: record.hosts,
-			port: record.port
+			port: record.port,
+			forgottenHosts: record.forgottenHosts ?? []
 		};
 	}
 	#agentsTool() {
@@ -6313,16 +7391,18 @@ var CherryToolEngine = class {
 		const session = isRecord(sessionResult["session"]) ? sessionResult["session"] : {};
 		const historyRevision = session["historyRevision"];
 		if (typeof historyRevision !== "string") throw new Error(`agent.sessions.get returned no historyRevision for session ${sessionId}`);
+		const messageList = messageListRequest(connection);
 		const page = await this.#aggregate(connection, "agent.messages.list", {
 			sessionId,
-			historyRevision
+			historyRevision,
+			...messageList.params
 		}, (result) => ({
 			...arrayOf(result["items"]),
 			nextCursor: result["nextCursor"]
 		}), {
 			limit,
 			safetyBound: MAX_AGGREGATE_LIMIT,
-			maxPerPage: 16,
+			maxPerPage: messageList.maxPerPage,
 			resume: resume === void 0 ? void 0 : resume.kind === "cursor" ? {
 				kind: "cursor",
 				cursor: resume.cursor
@@ -6496,7 +7576,7 @@ var CherryToolEngine = class {
 	* '{\"mediaType\":…,\"filename\":…}'}}` — the metadata SERIALIZED AS JSON in
 	* `content.text`, observed on the wire (2.1.7 desktop, image upload,
 	* 2026-10-22). An OBJECT inside `content` is not producible by a conforming
-	* peer at all: the pinned protocol 0.5.0 types `content` as a strict
+	* peer at all: the pinned protocol 0.7.0 types `content` as a strict
 	* `{text}` | `{ref}` union, so the old documentation described a shape no
 	* peer can emit — and the real one was never lifted, which is how an image
 	* upload reached a model as a JSON blob.
@@ -6769,7 +7849,7 @@ var CherryToolEngine = class {
 				try {
 					await subscriptions.ack(sessionId, result.nextCursor);
 				} catch (error) {
-					console.warn(`[cherry-remote] acknowledging session ${sessionId} at ${result.nextCursor.seq} failed`, error);
+					console.warn(`[cherry-remote] acknowledging session ${sessionId} at ${result.nextCursor.seq} failed: ` + failureText(error));
 					this.#reEnsureInBackground(record.deviceId, sessionId);
 				}
 				return {
@@ -8570,13 +9650,23 @@ var CherryToolEngine = class {
 	* identity object: the verdict is already known and true, and only the
 	* content behind it failed.
 	*
-	* `aggregateError` is BOUNDED like every other peer-echoed string in a result
-	* (the full text goes to the log): the reason is actionable at 200 characters
-	* and the log is where the operator reads the rest.
+	* `aggregateError` is a TOOL RESULT, not a log line — see
+	* {@link defineCherryTool} for the product decision (issue #161): a result is
+	* the MODEL's signal, so it is not bounded by the logging rule, and the
+	* 200-character clip here is this field's own choice.
+	*
+	* The LOG line IS the logging face, and it renders the failure as ONE bounded
+	* string through {@link failureText} (issue #161). An assembly failure is
+	* usually a peer RPC refusal — its `error.message` is the peer's own text,
+	* capped at 512 characters by the failure schema — and the old line
+	* interpolated it whole: one 512-char refusal made a 654-character line for
+	* the `timeout` / `s-1` fixture (83 fixed prefix + 512 + 59 suffix). The
+	* RESULT keeps the raw message's first 200 characters; a bound on the log
+	* does not change what the model receives.
 	*/
 	#assemblyFailed(identity, error) {
 		const message = error instanceof Error ? error.message : String(error);
-		console.warn(`[cherry-remote] the ${String(identity["status"])} answer for session ${String(identity["sessionId"])} could not assemble its content (${message}); returning the verdict with the assembly failure reported`);
+		console.warn(`[cherry-remote] the ${String(identity["status"])} answer for session ${String(identity["sessionId"])} could not assemble its content (${failureText(error)}); returning the verdict with the assembly failure reported`);
 		return {
 			...identity,
 			aggregateError: message.slice(0, 200),
@@ -8655,15 +9745,18 @@ var CherryToolEngine = class {
 	async #readTerminalMessages(connection, sessionId, session, deadline) {
 		const historyRevision = optionalString(session["historyRevision"]);
 		if (historyRevision === void 0) return { messages: [] };
+		const messageList = messageListRequest(connection);
 		const page = await this.#aggregate(connection, "agent.messages.list", {
 			sessionId,
-			historyRevision
+			historyRevision,
+			...messageList.params
 		}, (result) => ({
 			...arrayOf(result["items"]),
 			nextCursor: result["nextCursor"]
 		}), {
 			limit: TERMINAL_AGGREGATE_MESSAGES,
-			deadline
+			deadline,
+			maxPerPage: messageList.maxPerPage
 		});
 		const messages = [];
 		let projectedBytes = 0;
@@ -8721,11 +9814,11 @@ var CherryToolEngine = class {
 		try {
 			layer = this.#deps.subs(deviceId);
 		} catch (error) {
-			console.warn(`[cherry-remote] could not re-ensure session ${sessionId} of ${deviceId}`, error);
+			console.warn(`[cherry-remote] could not re-ensure session ${sessionId} of ${deviceId}: ${failureText(error)}`);
 			return;
 		}
 		layer.ensure(sessionId).catch((error) => {
-			console.warn(`[cherry-remote] re-ensuring session ${sessionId} of ${deviceId} failed`, error);
+			console.warn(`[cherry-remote] re-ensuring session ${sessionId} of ${deviceId} failed: ${failureText(error)}`);
 		});
 	}
 	/**
@@ -10257,9 +11350,20 @@ function normalizeHost(raw) {
 	return raw.slice(1, -1);
 }
 /**
-* Validates a PATCH body. `hosts` is WHOLE-REPLACE by contract, and `port` is
-* shared by every host (spec §3.2) — there is no per-host port and no merge
-* semantics to get wrong.
+* Validates a PATCH body. `hosts` is WHOLE-REPLACE by contract.
+*
+* The map semantics this face owes (the record's per-host maps are DERIVED,
+* never patched directly — there is no `ports` field in this body):
+*
+*  - neither `hosts` nor `port` patched → the maps are unchanged;
+*  - `hosts` replaced → a host that stays keeps ITS OWN scheme and port, a new
+*    host gets `ws` and the record-level port;
+*  - a CHANGED `port` (with or without `hosts`) → EVERY final host is
+*    re-pointed to it. The face has one port field, so leaving per-host
+*    entries would make the edit inert for every listed host that already had
+*    one. Sending the CURRENT value is a no-op for the maps — the settings page
+*    sends both fields on every save, and a mixed-port record must not be
+*    flattened by a save that did not change the port.
 */
 function parsePatch(body) {
 	const patch = {};
@@ -10283,6 +11387,12 @@ function parsePatch(body) {
 			if (typeof entry !== "string") throw new PatchError("hosts entries must be strings");
 			return normalizeHost(entry);
 		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const host of patch.hosts) {
+			const key = host.toLowerCase();
+			if (seen.has(key)) throw new PatchError("hosts must not contain duplicates");
+			seen.add(key);
+		}
 	}
 	const port = body["port"];
 	if (port !== void 0) {
@@ -10638,6 +11748,23 @@ async function handleRequest(req, res, route) {
 			writeError(res, 405, "method-not-allowed", "DELETE or PATCH only");
 			return;
 		}
+		if (first === "devices" && match.segments.length === 3 && second !== void 0) {
+			const deviceId = decodeSegment(second);
+			if (deviceId === void 0) {
+				writeError(res, 400, "invalid-request", "device id is not valid URL encoding");
+				return;
+			}
+			const action = match.segments[2];
+			if (action !== "forget" && action !== "remember") {
+				writeError(res, 404, "not-found", "unknown route");
+				return;
+			}
+			if (method !== "POST") {
+				writeError(res, 405, "method-not-allowed", "POST only");
+				return;
+			}
+			return await changeEndpoints(req, res, route, deviceId, action);
+		}
 		if (first === "pair" && match.segments.length === 1) {
 			if (method !== "POST") {
 				writeError(res, 405, "method-not-allowed", "POST only");
@@ -10675,14 +11802,28 @@ async function handleRequest(req, res, route) {
 	}
 }
 function listDevices(res, route) {
-	writeJson(res, 200, route.deps.store.list().map((device) => ({
+	writeJson(res, 200, route.deps.store.list().map((device) => deviceSummary(route, device)));
+}
+/**
+* One device as the browser sees it: the public archive projection, never a
+* credential.
+*
+* ONE builder, because FOUR faces answer this shape — `GET /devices`, the
+* `PATCH`, and the two endpoint actions of issue #204 — and a hand-written copy
+* per face is how a field ends up on one and not the others.
+*/
+function deviceSummary(route, device) {
+	return {
 		deviceId: device.deviceId,
 		displayName: device.displayName,
 		state: projectState(device, route.deps.connect),
 		enabled: device.enabled,
 		hosts: [...device.hosts],
-		port: device.port
-	})));
+		port: device.port,
+		security: { ...device.security },
+		ports: { ...device.ports },
+		forgottenHosts: [...device.forgottenHosts ?? []]
+	};
 }
 /**
 * The `GET /diagnostics` body (spec §5).
@@ -10851,11 +11992,13 @@ function deviceById(deps, deviceId) {
 	const found = deps.store.list().find((device) => device.deviceId === deviceId);
 	if (found !== void 0) return found;
 	return {
-		schemaVersion: 2,
+		schemaVersion: 4,
 		deviceId,
 		displayName: "",
 		hosts: [],
 		port: 0,
+		security: {},
+		ports: {},
 		desktopIdentity: "",
 		grants: [],
 		enabled: false
@@ -10905,12 +12048,21 @@ async function patchDevice(req, res, route, deviceId) {
 	const previousEnabled = existing.enabled;
 	const previousHosts = existing.hosts;
 	const previousPort = existing.port;
+	const previousSecurity = existing.security;
+	const previousPorts = existing.ports;
+	const nextPorts = patch.port !== void 0 && patch.port !== previousPort ? portsFor(patch.hosts ?? previousHosts, {}, patch.port) : patch.hosts === void 0 ? previousPorts : portsFor(patch.hosts, previousPorts, previousPort);
+	const nextForgotten = patch.hosts === void 0 || existing.forgottenHosts === void 0 ? void 0 : existing.forgottenHosts.filter((host) => !patch.hosts.some((nextHost) => nextHost.toLowerCase() === host.toLowerCase()));
 	const next = {
 		...existing,
+		...nextForgotten === void 0 ? {} : { forgottenHosts: nextForgotten },
 		...patch.displayName === void 0 ? {} : { displayName: patch.displayName },
 		...patch.enabled === void 0 ? {} : { enabled: patch.enabled },
-		...patch.hosts === void 0 ? {} : { hosts: patch.hosts },
-		...patch.port === void 0 ? {} : { port: patch.port }
+		...patch.hosts === void 0 ? {} : {
+			hosts: patch.hosts,
+			security: securityFor(patch.hosts, previousSecurity)
+		},
+		...patch.port === void 0 ? {} : { port: patch.port },
+		ports: nextPorts
 	};
 	try {
 		route.deps.store.upsert(next);
@@ -10919,7 +12071,7 @@ async function patchDevice(req, res, route, deviceId) {
 		writeError(res, 400, "invalid-device", error instanceof Error ? error.message : String(error));
 		return;
 	}
-	const addressChanged = patch.hosts !== void 0 && !sameHosts(patch.hosts, previousHosts) || patch.port !== void 0 && patch.port !== previousPort;
+	const addressChanged = patch.hosts !== void 0 && !sameHosts(patch.hosts, previousHosts) || patch.port !== void 0 && patch.port !== previousPort || !sameSecurity(next.security, previousSecurity);
 	const enabledChanged = patch.enabled !== void 0 && patch.enabled !== previousEnabled;
 	if (addressChanged) evict(route, deviceId);
 	if (enabledChanged) hibernate(route, deviceId);
@@ -10928,29 +12080,167 @@ async function patchDevice(req, res, route, deviceId) {
 	} catch (error) {
 		console.warn(`[cherry-remote] device ${deviceId} reconnect failed`, error);
 	}
-	const state = projectState(next, route.deps.connect);
+	const summary = deviceSummary(route, next);
 	if (patch.enabled !== void 0 && patch.enabled !== previousEnabled) route.hub.publish("device-state", {
 		deviceId,
-		state
-	});
-	writeJson(res, 200, {
-		deviceId: next.deviceId,
-		displayName: next.displayName,
-		state,
-		enabled: next.enabled,
-		hosts: [...next.hosts],
-		port: next.port
+		state: summary.state
 	});
+	writeJson(res, 200, summary);
 }
 function warnConnect(deviceId) {
 	return (error) => {
-		console.warn(`[cherry-remote] device ${deviceId} lifecycle change failed`, error);
+		console.warn(`[cherry-remote] device ${deviceId} lifecycle change failed: ${failureText(error)}`);
 	};
 }
 /** Order-sensitive host comparison: `hosts` is an ordered candidate list. */
 function sameHosts(a, b) {
 	return a.length === b.length && a.every((host, index) => host === b[index]);
 }
+/**
+* `POST /devices/:id/forget` and `POST /devices/:id/remember` (issue #204): the
+* settings page's door onto #185's endpoint maintenance, which until now only
+* the `cherry_devices` tool could open.
+*
+* One action per request, and the action IS the request: there is no composite
+* "patch the record AND forget a host" body whose ordering would have to be
+* defined. Every judgement is the store's — the last-candidate refusal, the
+* case-insensitive matching, the disjointness of `hosts`/`forgottenHosts` — so
+* the two doors share ONE set of STORE rules; this route only maps the verdicts
+* onto HTTP and answers the projection the PATCH answers. (The BODY PARSERS do
+* differ on purpose — see `parseEndpointHosts`.)
+*
+* EVICTION on a change, exactly like the tool's own arm and a PATCH's address
+* maintenance, and for a DIFFERENT reason on each action — which is why both
+* are stated here rather than waved through as "parity":
+*
+*  - FORGET: a pooled connection CAPTURES its record at construction, so the
+*    socket built before this write would keep dialing the host we just forgot.
+*    (The mark itself is honoured by the store's learn merge, so a reconnect is
+*    about the DIAL LIST, not about suppressing the address.)
+*  - REMEMBER: learning happens only INSIDE a handshake, against a clone of the
+*    stored record. Without the eviction a desktop that stays connected would
+*    not re-handshake for as long as the link holds, so the restored address
+*    would come back only after some later flap — the button would look inert.
+*
+* The cost is real and inherited from the tool's arm: an eviction disposes the
+* subscription layer and closes a healthy socket, so a write can drop an
+* in-flight command's link. One operator click now reaches that churn; that is
+* the price of "the archive is the truth" for a live connection.
+*/
+async function changeEndpoints(req, res, route, deviceId, action) {
+	const existing = route.deps.store.list().find((device) => device.deviceId === deviceId);
+	if (existing === void 0) {
+		writeError(res, 404, "not-found", `no device ${deviceId}`);
+		return;
+	}
+	let hosts;
+	try {
+		hosts = parseEndpointHosts(await readJsonBody(req));
+	} catch (error) {
+		writeError(res, 400, "invalid-request", error instanceof Error ? error.message : String(error));
+		return;
+	}
+	try {
+		if (action === "forget") {
+			const { removed, marked } = route.deps.store.forgetEndpoints(deviceId, hosts);
+			if (removed.length > 0 || marked.length > 0) evict(route, deviceId);
+		} else {
+			const { restored } = route.deps.store.rememberEndpoints(deviceId, hosts);
+			if (restored.length > 0) evict(route, deviceId);
+		}
+	} catch (error) {
+		if (writeQuarantineRefusal(res, route, error)) return;
+		if (error instanceof LastCandidateHostError) {
+			writeError(res, 400, "last-address", error.message);
+			return;
+		}
+		writeError(res, 400, "invalid-device", error instanceof Error ? error.message : String(error));
+		return;
+	}
+	writeJson(res, 200, deviceSummary(route, route.deps.store.list().find((device) => device.deviceId === deviceId) ?? existing));
+}
+/**
+* The body of an endpoint action: `{hosts: [...]}`, non-empty, every entry
+* normalized the same way the PATCH normalizes an address.
+*
+* The normalization is not cosmetic: an IPv6 literal is stored bare but a
+* browser copy-pastes it bracketed, and the store matches by host spelling —
+* so `[::1]` would be treated as an address the record does not dial and merely
+* marked, leaving the real `::1` in `hosts`. The PATCH's rule is reused for the
+* spelling (same `normalizeHost`), and deliberately NOT for its duplicate
+* refusal: a repeated host in an action body names one host twice, which the
+* store's own sets collapse, while the PATCH's duplicates would build an
+* ambiguous record (`hosts`, `security` and `ports` are keyed by host).
+*/
+function parseEndpointHosts(body) {
+	const hosts = body["hosts"];
+	if (!Array.isArray(hosts) || hosts.length === 0) throw new PatchError("hosts must be a non-empty array");
+	return hosts.map((entry) => {
+		if (typeof entry !== "string") throw new PatchError("hosts entries must be strings");
+		return normalizeHost(entry);
+	});
+}
+/**
+* The scheme map for a WHOLE-REPLACE host list (issue #126): each named host
+* keeps the scheme it was dialed with, a host the list just gained defaults to
+* `ws`, and hosts the list dropped leave no entry behind. An edit is an
+* address edit, not a scheme edit — re-typing the same host must not silently
+* demote a TLS-proxied desktop to a plain dial.
+*
+* "The same host" is CASE-INSENSITIVE (issue #189), the same comparison the
+* learn merge, the forget/remember actions and the mark clearing already use:
+* `NAS.example` and `nas.example` are one address, so a PATCH that re-types
+* the case keeps the remembered scheme instead of resetting it to `ws`.
+* `sameHosts`/`sameSecurity` stay EXACT on purpose — they decide whether an
+* address edit happened at all, and a new spelling IS a change to persist.
+*/
+function securityFor(hosts, previous) {
+	const remembered = indexByHost(previous);
+	return Object.fromEntries(hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? "ws"]));
+}
+/**
+* A case-insensitive index over a per-host map (issue #189).
+*
+* FIRST spelling wins on a collision. A hand-edited archive CAN hold two
+* spellings of one host (the store does not reject it, and this face does not
+* touch `previous`), so callers look their exact spelling up FIRST and consult
+* this index only as the fallback: a surviving spelling therefore keeps its
+* OWN entry, and the collision rule only decides what a THIRD spelling
+* inherits.
+*/
+function indexByHost(previous) {
+	const index = /* @__PURE__ */ new Map();
+	for (const [host, value] of Object.entries(previous)) {
+		const key = host.toLowerCase();
+		if (!index.has(key)) index.set(key, value);
+	}
+	return index;
+}
+/** The exact spelling's entry, else the case-insensitive one, else nothing. */
+function exactOrRemembered(previous, remembered, host) {
+	return Object.hasOwn(previous, host) ? previous[host] : remembered.get(host.toLowerCase());
+}
+/**
+* The port map for a host list (issue #135): each named host keeps the port it
+* was dialed with, a host the list just gained defaults to `fallback` (the
+* record-level port), and hosts the list dropped leave no entry behind.
+*
+* `previous` is empty when the caller is re-pointing EVERY host (a CHANGED
+* `port` patch): there is no remembered entry to keep, by design — one port
+* field on this face must move the whole list. Same `Object.hasOwn`/
+* case-insensitive rules as `securityFor` (issue #189): a re-typed spelling
+* keeps its own port, and an inherited function is never a remembered port.
+*/
+function portsFor(hosts, previous, fallback) {
+	const remembered = indexByHost(previous);
+	return Object.fromEntries(hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? fallback]));
+}
+/** Order-insensitive comparison for two scheme maps. */
+function sameSecurity(a, b) {
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	return keys.every((key) => a[key] === b[key]);
+}
 /** Drops the pooled connection, closing any live socket first. */
 function evict(route, deviceId) {
 	try {
@@ -11065,11 +12355,12 @@ function openEvents(req, res, route) {
 //#region src/index.ts
 const name = "cherry-remote";
 const inject = ["tools"];
-/** Applies the documented fallbacks to the plugin config's numeric keys. */
+/** Applies the documented fallbacks and validates the plugin config's keys. */
 function resolveBridgeConfig(config = {}) {
 	return {
 		rateBudgetPerSecond: positive("rateBudgetPerSecond", config.rateBudgetPerSecond, 32),
-		perSessionCacheBytes: positive("perSessionCacheBytes", config.perSessionCacheBytes, DEFAULT_PER_SESSION_CACHE_BYTES)
+		perSessionCacheBytes: positive("perSessionCacheBytes", config.perSessionCacheBytes, DEFAULT_PER_SESSION_CACHE_BYTES),
+		wsTls: dialOptions(config.wsTls)
 	};
 }
 /**
@@ -11094,6 +12385,76 @@ function positive(key, value, fallback) {
 	}
 	return value;
 }
+/** The keys {@link WsDialOptions} carries; anything else is a config mistake. */
+const WS_TLS_KEYS = /* @__PURE__ */ new Set(["rejectUnauthorized", "ca"]);
+/** The shape a non-object config value arrived as, for a value-free warning. */
+function shapeOf(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* One `ca` entry: PEM CONTENT for a string, non-empty bytes for a Buffer.
+*
+* A string is the certificate TEXT itself, NEVER a file path: `tls.connect`
+* would happily read whatever path it is handed, so accepting `'/etc/ssl/ca.pem'`
+* would load bytes the operator never inspected. The header check is a SHAPE
+* check only — whether the PEM parses beyond `-----BEGIN` is Node's business,
+* and an unparseable body fails the handshake loudly, which is the honest
+* verdict. Buffers keep the non-empty test with no header requirement: DER and
+* programmatically built PEM bytes are legitimate `ca` values.
+*/
+function certificateEntry(value) {
+	if (typeof value === "string") return value.trimStart().startsWith("-----BEGIN");
+	if (Buffer.isBuffer(value)) return value.length > 0;
+	return false;
+}
+/**
+* A configured TLS trust bag, or `undefined` when absent/unusable.
+*
+* ABSENT is the documented default (Node's trust store) and says nothing —
+* exactly like {@link positive}. A key that is PRESENT but unusable is a
+* deployment mistake that silently changes which peers are reachable, so it is
+* warned about by name rather than swallowed — but NEVER by value: a `ca` is
+* PEM CONTENT, and a certificate must not reach a log.
+*
+* FAIL CLOSED, WHOLE OBJECT. One unknown or malformed entry discards the WHOLE
+* bag rather than forwarding the parts that happen to look right. Trust must be
+* applied AS WRITTEN: a partially applied bag would reach some peers and not
+* others with nothing telling the operator which half took effect, and their
+* `ca` intention would be silently replaced by Node's default store. The
+* fallback is "no override" — the same state as absent.
+*/
+function dialOptions(value) {
+	if (value === void 0) return void 0;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		console.warn(`[cherry-remote] config "wsTls" must be a plain object of flat tls.connect options (got ${shapeOf(value)}); ignoring it`);
+		return;
+	}
+	const record = value;
+	const unknownKeys = Object.keys(record).filter((key) => !WS_TLS_KEYS.has(key));
+	if (unknownKeys.length > 0) {
+		console.warn(`[cherry-remote] config "wsTls" carries unsupported key(s) ${unknownKeys.join(", ")}; only flat rejectUnauthorized / ca are accepted — ignoring the whole object`);
+		return;
+	}
+	const rejectUnauthorized = record["rejectUnauthorized"];
+	if (rejectUnauthorized !== void 0 && typeof rejectUnauthorized !== "boolean") {
+		console.warn("[cherry-remote] config \"wsTls.rejectUnauthorized\" must be a boolean; ignoring the whole object");
+		return;
+	}
+	const ca = record["ca"];
+	if (ca !== void 0) {
+		if (!(Array.isArray(ca) ? ca.length > 0 && ca.every((entry) => certificateEntry(entry)) : certificateEntry(ca))) {
+			console.warn("[cherry-remote] config \"wsTls.ca\" must be PEM CONTENT (the certificate text itself, not a file path) — a \"-----BEGIN\" string, a non-empty Buffer, or a non-empty array of those; ignoring the whole object");
+			return;
+		}
+	}
+	if (rejectUnauthorized === void 0 && ca === void 0) return void 0;
+	return {
+		...rejectUnauthorized === void 0 ? {} : { rejectUnauthorized },
+		...ca === void 0 ? {} : { ca }
+	};
+}
 /** The data directory convention every DSH plugin follows. */
 function resolveDataDir(config = {}, env = process.env) {
 	if (config.dataDir !== void 0 && config.dataDir !== "") return config.dataDir;
@@ -11135,6 +12496,7 @@ const state = {
 	identityError: void 0,
 	rateBudgetPerSecond: 32,
 	perSessionCacheBytes: DEFAULT_PER_SESSION_CACHE_BYTES,
+	wsTls: void 0,
 	connections: /* @__PURE__ */ new Map(),
 	subscriptions: /* @__PURE__ */ new Map(),
 	deviceStateListeners: /* @__PURE__ */ new Set(),
@@ -11200,7 +12562,11 @@ function connectionFor(deviceId) {
 	const connection = new DeviceConnection({
 		identity: requireIdentity(),
 		record,
-		rateBudgetPerSecond: state.rateBudgetPerSecond
+		rateBudgetPerSecond: state.rateBudgetPerSecond,
+		...state.wsTls === void 0 ? {} : { wsOptions: state.wsTls },
+		onAdvertisedEndpoints: (endpoints) => {
+			state.store.learnEndpoints(deviceId, endpoints, record.desktopIdentity);
+		}
 	});
 	state.connectionsBuilt += 1;
 	connection.onState((deviceState) => {
@@ -11221,7 +12587,7 @@ function connectionFor(deviceId) {
 		try {
 			subsFor(deviceId).handleNotification(method, params);
 		} catch (error) {
-			console.warn(`[cherry-remote] notification "${method}" for ${deviceId} failed`, error);
+			console.warn(`[cherry-remote] notification "${method}" for ${deviceId} failed: ${failureText(error)}`);
 		}
 	});
 	state.connections.set(deviceId, connection);
@@ -11312,6 +12678,30 @@ function subsFor(deviceId) {
 	return created;
 }
 /**
+* Bounds the link-recovery line's session-id list (issue #155).
+*
+* The number of ENTRIES is bounded only by the peer-advertised hello
+* `subscriptions` — a number the peer chooses, not one this assembly can size —
+* and a session id is the protocol's `opaqueId` (≤ 256 characters). The old
+* `sessions.join(', ')` therefore emitted `entries × 258` characters into one
+* info line: the protocol's own `remoteLimits.subscriptions` = 8 still allows
+* ~2 KB, and a peer advertising more grows the line with no ceiling at all. The
+* text is peer-controlled (the ids are echoed back from what the peer accepted
+* as subscriptions), so it needs a LOCAL bound like every other such log.
+*
+* `RECOVERY_SESSIONS_MAX` = 320 is the joined ids' budget: eight normal
+* 36-char UUIDs render as 8 × 36 + 7 × 2 = 302 characters, so the protocol's
+* own subscription cap fits WHOLE — the bound bites only on a peer that
+* advertises more room, or on a malformed over-long id.
+* `RECOVERY_SESSION_ID_MAX` = 256 is that `opaqueId` cap, so a schema-valid id
+* is never clipped; only a malformed one is. A list that stops early names the
+* count (`(+K more)`) and rides ON TOP of the budget; entries are never dropped
+* silently. The bound is on the LOG only — the loop still re-ensures every
+* session.
+*/
+const RECOVERY_SESSIONS_MAX = 320;
+const RECOVERY_SESSION_ID_MAX = 256;
+/**
 * The reconnect recovery line (ruling 8): every session this device had
 * subscribed is re-ensured at its LAST cursor, so the peer replays only what
 * this harness has not yet consumed.
@@ -11325,14 +12715,17 @@ async function recoverSubscriptions(deviceId) {
 	const subscriptions = state.subscriptions.get(deviceId);
 	if (subscriptions === void 0) return;
 	const sessions = subscriptions.activeSessions();
-	if (sessions.length > 0) console.info(`[cherry-remote] recovering ${sessions.length} subscription(s) for ${deviceId}: ${sessions.join(", ")}`);
+	if (sessions.length > 0) console.info(`[cherry-remote] recovering ${sessions.length} subscription(s) for ${deviceId}: ${boundedJoin(sessions, {
+		max: RECOVERY_SESSIONS_MAX,
+		itemMax: RECOVERY_SESSION_ID_MAX
+	})}`);
 	for (const sessionId of sessions) try {
 		const result = subscriptions.read(sessionId);
 		const cursor = "events" in result ? result.nextCursor : void 0;
 		await subscriptions.ensure(sessionId, cursor);
 		console.info(`[cherry-remote] subscription recovered for ${deviceId} session ${sessionId}` + (cursor === void 0 ? "" : ` at seq ${cursor.seq}`));
 	} catch (error) {
-		console.warn(`[cherry-remote] re-subscribing session ${sessionId} of ${deviceId} failed`, error);
+		console.warn(`[cherry-remote] re-subscribing session ${sessionId} of ${deviceId} failed: ${failureText(error)}`);
 	}
 }
 /** One dep object, shared by both faces, so there is exactly ONE pool. */
@@ -11360,6 +12753,7 @@ function assemblyDeps() {
 				payload: request.payload,
 				store: state.store,
 				...request.name === void 0 ? {} : { name: request.name },
+				...state.wsTls === void 0 ? {} : { wsOptions: state.wsTls },
 				onVerificationCode: request.onVerificationCode,
 				onStatus: (stage) => publishPairingProgress({ stage })
 			});
@@ -11428,6 +12822,7 @@ function apply(ctx, config = {}) {
 	const bridgeConfig = resolveBridgeConfig(config);
 	state.rateBudgetPerSecond = bridgeConfig.rateBudgetPerSecond;
 	state.perSessionCacheBytes = bridgeConfig.perSessionCacheBytes;
+	state.wsTls = bridgeConfig.wsTls;
 	state.store = new DeviceStore(join(dataDir, "devices.json"));
 	state.recentErrors.length = 0;
 	state.connectionsBuilt = 0;