dsh-cherry-bridge 0.1.11 → 0.2.0

package/dist/index.mjs

@@ -5,7 +5,8 @@ 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 { directEndpointUrl, jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, pairingQrSchema, remoteFailureSchema } from "@cherrystudio/remote-protocol";
+import { peerIdFromString } from "@libp2p/peer-id";
 const FILE_MODE = 384;
 /**
 * Version-to-version migrations, keyed by the version they upgrade from.
@@ -13,15 +14,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 +88,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 +111,61 @@ 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);
 	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`);
+	}
+}
+/**
 * Read path, fixed order: loose parse -> completeness gate -> version judgement
 * -> migration -> assert the required `DeviceRecord` type.
 *
@@ -74,7 +188,7 @@ 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);
@@ -85,7 +199,7 @@ 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 +209,7 @@ function parseArchive(parsed) {
 }
 function serializeArchive(devices) {
 	return `${JSON.stringify({
-		schemaVersion: 2,
+		schemaVersion: 4,
 		devices
 	}, null, 2)}\n`;
 }
@@ -376,7 +490,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 +585,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 +1128,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 +2119,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 +2142,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 +2550,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
@@ -2818,8 +3048,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;
@@ -2997,7 +3229,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 +3247,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 +3262,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 +3285,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 +3307,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 +3376,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;
@@ -3498,24 +3742,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 +3813,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 +3842,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 +3856,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 +3964,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 +4043,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 +4123,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 +4164,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 +4210,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 +4244,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 +4255,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 +4300,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 +4823,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 +5158,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 +5282,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 +5647,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).
 *
@@ -5434,7 +6013,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 +6493,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`);
@@ -6313,16 +6904,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 +7089,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 +7362,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 +9163,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 +9258,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 +9327,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 +10863,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 +10900,7 @@ function parsePatch(body) {
 			if (typeof entry !== "string") throw new PatchError("hosts entries must be strings");
 			return normalizeHost(entry);
 		});
+		if (new Set(patch.hosts).size !== patch.hosts.length) throw new PatchError("hosts must not contain duplicates");
 	}
 	const port = body["port"];
 	if (port !== void 0) {
@@ -10681,7 +11299,9 @@ function listDevices(res, route) {
 		state: projectState(device, route.deps.connect),
 		enabled: device.enabled,
 		hosts: [...device.hosts],
-		port: device.port
+		port: device.port,
+		security: { ...device.security },
+		ports: { ...device.ports }
 	})));
 }
 /**
@@ -10851,11 +11471,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 +11527,19 @@ 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 next = {
 		...existing,
 		...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 +11548,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);
@@ -10939,18 +11568,49 @@ async function patchDevice(req, res, route, deviceId) {
 		state,
 		enabled: next.enabled,
 		hosts: [...next.hosts],
-		port: next.port
+		port: next.port,
+		security: { ...next.security },
+		ports: { ...next.ports }
 	});
 }
 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]);
 }
+/**
+* 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.
+*/
+function securityFor(hosts, previous) {
+	return Object.fromEntries(hosts.map((host) => [host, Object.hasOwn(previous, host) ? previous[host] : "ws"]));
+}
+/**
+* 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` rule as
+* `securityFor`: an inherited function is not a remembered port.
+*/
+function portsFor(hosts, previous, fallback) {
+	return Object.fromEntries(hosts.map((host) => [host, Object.hasOwn(previous, host) ? previous[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 +11725,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 +11755,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 +11866,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 +11932,8 @@ function connectionFor(deviceId) {
 	const connection = new DeviceConnection({
 		identity: requireIdentity(),
 		record,
-		rateBudgetPerSecond: state.rateBudgetPerSecond
+		rateBudgetPerSecond: state.rateBudgetPerSecond,
+		...state.wsTls === void 0 ? {} : { wsOptions: state.wsTls }
 	});
 	state.connectionsBuilt += 1;
 	connection.onState((deviceState) => {
@@ -11221,7 +11954,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 +12045,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 +12082,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 +12120,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 +12189,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;