dsh-cherry-bridge 0.1.10 → 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". */
@@ -4881,6 +5422,59 @@ const MESSAGE_CACHE_ENTRY_BYTES = 1048576;
 */
 const MESSAGE_CACHE_BYTES_PER_DEVICE = 33554432;
 /**
+* How many command bodies the engine remembers PER DEVICE, keyed by the
+* CALLER-SUPPLIED `commandId` (issues #115, #118).
+*
+* Why a memory exists at all: a command's recovery path is RECEIPT. A reply
+* lost on the wire is answered by re-sending the ORIGINAL body under the
+* original id, and the desktop's ledger replays the recorded outcome. That
+* promise was impossible for `cherry_send`, whose body carries a DERIVED field
+* (`expectedIdleRevision`) that moves with every successful send: the retry
+* quoted a fresh baseline, the body differed from the recorded one, and the peer
+* answered IDEMPOTENCY_CONFLICT — on the one path where the caller cannot tell
+* what already landed. So the engine remembers the EXACT body it emitted, per
+* (device, caller id, method), and a same-id retry replays it verbatim. The
+* same defect had a harder shape in `cherry_respond` / `cherry_cancel` (issue
+* #118): their DERIVED fields were re-derived, and the retry usually met a
+* pre-check (`unknown-interaction`, `no-active-execution`) before the body was
+* ever compared — the memory is consulted before those, which is why it holds
+* the whole issued body rather than a way to rebuild one.
+*
+* What an entry holds is one short body: a session id, the caller's text (at
+* most the protocol's 32,768 characters, pre-validated before it is ever
+* stored), one revision string — or, for respond/cancel, the interaction's
+* staleness triple / the execution to abort, plus the caller-owned arguments
+* the fingerprint compares. 128 is "more than any live retry window needs,
+* small enough to be trivial": a caller retries a handful of command ids around
+* a lost reply, and each is recoverable while it stays in this FIFO.
+* Eviction costs a REQUEST, never correctness — an evicted id has NO entry, so
+* a same-id retry re-derives a fresh baseline. For a SEND the re-derived body
+* reaches the peer, which refuses the differing body exactly as it would
+* without this memory; for a RESPOND or CANCEL the retry usually dies earlier,
+* at the LOCAL pre-checks (`unknown-interaction`, `no-active-execution`,
+* `execution-mismatch`) — the pre-fix failure mode, which names real state.
+*
+* PER DEVICE, like every engine cache: the id is the caller's, but the peer
+* that settled it is not, and a second desktop must never be sent a body minted
+* against the first.
+*
+* INJECTABLE for tests (`commandBodyEntriesPerDevice`), because the production
+* value needs 129 live command ids before it evicts.
+*/
+const COMMAND_BODY_ENTRIES_PER_DEVICE = 128;
+/**
+* The three command methods whose bodies the engine remembers (see
+* {@link COMMAND_BODY_ENTRIES_PER_DEVICE}).
+*
+* Named once, because they are used twice each by design: as the remembered
+* entry's `method`, and as the method the entry is compared against on lookup.
+* Spelling them at both ends is how a lookup could start matching the wrong
+* tool without any type noticing.
+*/
+const SEND_METHOD = "agent.messages.send";
+const RESPOND_METHOD = "agent.interactions.respond";
+const CANCEL_METHOD = "agent.executions.cancel";
+/**
 * EMPTY-PAGE RUN limit for every aggregate walk. The desktop's pinned-list walk
 * legally answers ONE empty page with an advancing cursor (the pin→entity
 * section transition, `{items: [], nextCursor: 'entity:'}`), so a single empty
@@ -5053,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).
 *
@@ -5093,6 +5725,79 @@ function unavailableReason(error) {
 */
 const IDEMPOTENCY_HINT = "the peer already recorded this commandId with a different body; regenerate the commandId for a retry whose parameters changed — never reuse an id with a different body (re-send the ORIGINAL body to replay the original receipt).";
 /**
+* The peer's own wording for `IDEMPOTENCY_CONFLICT` (its `agentHandlers` throws
+* exactly this), used when the ENGINE is the one that knows the body differs —
+* a caller-supplied `commandId` it has already emitted with other arguments
+* (issue #115).
+*
+* The refusal is LOCAL because the outcome is already decided: the peer's ledger
+* holds the recorded body, so a forwarded body would come back as this same
+* conflict, one round trip later, at the cost of a wire call that can never
+* succeed. Reusing the sentence keeps ONE vocabulary for one condition; callers
+* (and the existing conflict tests) match on the prefix.
+*/
+const COMMAND_BODY_DIFFERS_MESSAGE = "Command body differs from the recorded command";
+/**
+* The JSON-RPC error code the transport reserves for protocol failures (the
+* server answers every peer-refused request with it). Used for the LOCAL
+* {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal so it is the same currency a
+* forwarded one would have been: a `JsonRpcRequestError` carrying
+* `{reason: 'IDEMPOTENCY_CONFLICT'}`, distinguishable only by the fact that no
+* request was ever sent.
+*
+* A LOCAL twin of the literal `src/rpc/jsonRpcClient.ts` documents in its own
+* `JsonRpcRequestError` docblock: that module exports no code constant, and
+* adding one only to name this number would widen the published surface for it.
+*/
+const JSON_RPC_PROTOCOL_ERROR_CODE = 1e3;
+/**
+* The LOCAL {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal — the peer's own
+* reason and sentence, wrapped with the same hints a forwarded conflict earns,
+* and never sent anywhere.
+*
+* ONE constructor for every command that remembers its body (send, respond,
+* cancel): the caller must not have to learn a second vocabulary for one
+* condition, and a test matches the prefix `Command body differs` whichever
+* tool produced it.
+*/
+function commandBodyDiffers() {
+	const conflict = new JsonRpcRequestError(JSON_RPC_PROTOCOL_ERROR_CODE, COMMAND_BODY_DIFFERS_MESSAGE, {
+		reason: "IDEMPOTENCY_CONFLICT",
+		message: COMMAND_BODY_DIFFERS_MESSAGE
+	});
+	withRateLimitHint(withIdempotencyHint(conflict));
+	return conflict;
+}
+/**
+* DEEP structural equality, for the caller-owned half of a remembered command
+* body (issue #118).
+*
+* `cherry_respond`'s `response.answers` is a RECORD: two callers sending the
+* same answers in a different KEY ORDER are sending the SAME answer, and a
+* plain `!==` (or a JSON string comparison) would refuse the retry as a
+* different body — turning the receipt recovery into a local conflict on the
+* exact shapes it exists for. Arrays stay ORDERED: `questions` is a list, and
+* reordering it really is a different value.
+*
+* Deliberately small: the values compared here are tool arguments decoded from
+* JSON, so only JSON's two container kinds, the primitives, and `undefined`
+* (an omitted optional argument) need to be understood.
+*/
+function sameCommandValue(left, right) {
+	if (left === right) return true;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (!Array.isArray(left) || !Array.isArray(right)) return false;
+		if (left.length !== right.length) return false;
+		return left.every((value, index) => sameCommandValue(value, right[index]));
+	}
+	if (isRecord(left) && isRecord(right)) {
+		const leftKeys = Object.keys(left);
+		if (leftKeys.length !== Object.keys(right).length) return false;
+		return leftKeys.every((key) => Object.hasOwn(right, key) && sameCommandValue(left[key], right[key]));
+	}
+	return false;
+}
+/**
 * Passes a command failure through UNCHANGED, except that `IDEMPOTENCY_CONFLICT`
 * gets {@link IDEMPOTENCY_HINT} appended to its message.
 *
@@ -5275,17 +5980,52 @@ const CHERRY_TOOL_NAMES = [
 * those tasks add mutating tools without touching the host seam.
 */
 function registerCherryTools(ctx, deps, options = {}) {
+	return registerCherryToolsWithEngine(ctx, deps, options).dispose;
+}
+/**
+* The same registration, with the ENGINE it built handed back.
+*
+* Exists for TESTS: the engine's memory bookkeeping (the remembered command
+* bodies, the bounds they obey) is private to it on purpose, and the only
+* honest way to pin "bounded" and "dropped with the device" is to observe it
+* through this one seam instead of inferring it from retry outcomes that are
+* identical for an evicted entry and for one that never existed.
+*
+* Both this function and `export class CherryToolEngine` are SHIPPED names
+* (`src` is published on purpose, see AGENTS.md → Build facts), so they are a
+* compatibility commitment — which is why this seam is kept minimal.
+*/
+function registerCherryToolsWithEngine(ctx, deps, options = {}) {
 	const tools = ctx.tools;
 	if (tools === void 0) {
 		console.warn("[cherry-remote] ctx.tools is unavailable; the cherry_* tools were not registered");
-		return () => {};
+		return {
+			dispose: () => {},
+			engine: void 0
+		};
 	}
-	const disposers = new CherryToolEngine(deps, options).definitions().map((definition) => tools.register(definition));
-	return () => {
-		for (const dispose of disposers) dispose();
+	const engine = new CherryToolEngine(deps, options);
+	const disposers = engine.definitions().map((definition) => tools.register(definition));
+	return {
+		engine,
+		dispose: () => {
+			for (const dispose of disposers) dispose();
+		}
 	};
 }
-/** 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,
@@ -5378,6 +6118,12 @@ var CherryToolEngine = class {
 	*/
 	#contentGate;
 	/**
+	* The `maxBytes` one `agent.content.read` slice asks for
+	* ({@link CONTENT_READ_MAX_BYTES} in production; injectable so a test can
+	* reach a walk's second slice, see `CherryToolEngineOptions`).
+	*/
+	#contentReadSliceBytes;
+	/**
 	* The parts pages already walked, keyed `<deviceId>\0<messageId>`.
 	*
 	* WHAT IS HELD is the RESULT of `agent.parts.list` — the raw part records plus
@@ -5444,6 +6190,49 @@ var CherryToolEngine = class {
 	* not pinned by bookkeeping.
 	*/
 	#watchedConnections = /* @__PURE__ */ new WeakSet();
+	/**
+	* The EXACT command body emitted for each (device, caller id, method), so a
+	* lost reply can be recovered by receipt (issues #115, #118).
+	*
+	* Keyed `<deviceId>\0<commandId>`, exactly like every other engine cache. The
+	* value is a {@link RememberedCommand}: the METHOD it was minted for, the
+	* caller-owned FINGERPRINT a retry must match, and the BODY the retry
+	* replays verbatim. The fingerprint is what must MATCH — a same-id call whose
+	* arguments differ is not a retry of this command at all, and is refused
+	* locally rather than sent. The body is what must be REPLAYED, derived
+	* fields included: that is the whole point, because those fields are the ones
+	* a retry cannot re-derive the same way.
+	*
+	* Three tools remember: `agent.messages.send` (the baseline it quoted),
+	* `agent.interactions.respond` (the staleness triple) and
+	* `agent.executions.cancel` (the execution it was told to abort). Two of
+	* them run PRE-CHECKS before composing a body — respond's
+	* `unknown-interaction`, cancel's `no-active-execution`/`execution-mismatch` —
+	* and after a lost reply those pre-checks are usually the first thing the
+	* retry meets, because the first attempt is what SETTLED the interaction and
+	* ENDED the run. So a caller-supplied id is consulted BEFORE any derivation:
+	* a remembered retry is an answer, not a fresh call.
+	*
+	* WHAT IS REMEMBERED: only CALLER-SUPPLIED ids. An auto-generated uuid is a
+	* one-shot identity — nobody can retry it, so an entry for it is pure leak.
+	* The entry is written the moment the command is ISSUED, before the reply is
+	* awaited: a reply lost on the wire must not cost the only copy of the bytes
+	* the peer's ledger will accept.
+	*
+	* Which body an id holds: the LATEST attempt issued for it — the first
+	* attempt, or the self-heal's fresh-uuid retry when one ran. After a heal, a
+	* same-id retry is therefore answered with the peer's conflict, deliberately:
+	* replaying the ledger's rejected receipt would re-run the healed admission
+	* and duplicate the run, and a conflict is the safer failure.
+	*
+	* Bounded FIFO, per device; dropped when the PAIRING is invalidated (unpair,
+	* identity-mismatch) but KEPT across an ordinary reconnect — see
+	* {@link COMMAND_BODY_ENTRIES_PER_DEVICE} and
+	* {@link CherryToolEngine.#forgetDevice}.
+	*/
+	#commandBodies = /* @__PURE__ */ new Map();
+	/** The per-device cap on {@link CherryToolEngine.#commandBodies}. */
+	#commandBodyEntriesPerDevice;
 	constructor(deps, options = {}) {
 		this.#deps = deps;
 		this.#partsSafetyBound = Math.max(1, Math.floor(options.partsSafetyBound ?? DEFAULT_PARTS_SAFETY_BOUND));
@@ -5452,7 +6241,9 @@ var CherryToolEngine = class {
 		this.#cacheEntriesPerDevice = Math.max(1, Math.floor(options.cacheEntriesPerDevice ?? CACHE_ENTRIES_PER_DEVICE));
 		this.#messageCacheEntryBytes = Math.max(1, Math.floor(options.messageCacheEntryBytes ?? MESSAGE_CACHE_ENTRY_BYTES));
 		this.#messageCacheBytesPerDevice = Math.max(1, Math.floor(options.messageCacheBytesPerDevice ?? MESSAGE_CACHE_BYTES_PER_DEVICE));
+		this.#commandBodyEntriesPerDevice = Math.max(1, Math.floor(options.commandBodyEntriesPerDevice ?? COMMAND_BODY_ENTRIES_PER_DEVICE));
 		this.#contentGate = new ContentReadGate(options.contentReadConcurrency ?? DEFAULT_CONTENT_READ_CONCURRENCY);
+		this.#contentReadSliceBytes = Math.max(1, Math.floor(options.contentReadSliceBytes ?? CONTENT_READ_MAX_BYTES));
 	}
 	definitions() {
 		return [
@@ -5702,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`);
@@ -6015,7 +6806,7 @@ var CherryToolEngine = class {
 	#readTool() {
 		return defineCherryTool({
 			name: "cherry_read",
-			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. A binary attachment is reported as `kind: \"file\"` with `name`/`mediaType`/`byteLength` and an EMPTY `content` — the bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A failed message (`status: \"error\"`) may carry `failure: {reasonCode, retryable, message}` when the peer sent one — its classification, whether it judged a retry worthwhile, and a bounded summary; the peer's `source` and `context.responseBody` are never projected. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the stop point can be named — absent when it cannot, e.g. an empty or malformed position, a token past the length ceiling, or no anchor id — and passing it back as `messagesResumeCursor` continues the walk from there (`limit` then bounds how many messages are returned FROM that point). The two token forms are `\"cursor:<peer position>\"` (the walk consumed its whole page window) and `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
+			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. An attachment is reported as METADATA, never as its bytes: a `kind: \"file\"` part, or a legacy `data` part named `file` (the metadata as JSON in `content.text`), comes back as `name`/`mediaType` (plus `byteLength` for the `file` kind) with `content` emptied — or kept verbatim when that record carries a key this projection does not report. The bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A failed message (`status: \"error\"`) may carry `failure: {reasonCode, retryable, message}` when the peer sent one — its classification, whether it judged a retry worthwhile, and a bounded summary; the peer's `source` and `context.responseBody` are never projected. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the stop point can be named — absent when it cannot, e.g. an empty or malformed position, a token past the length ceiling, or no anchor id — and passing it back as `messagesResumeCursor` continues the walk from there (`limit` then bounds how many messages are returned FROM that point). The two token forms are `\"cursor:<peer position>\"` (the walk consumed its whole page window) and `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6113,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
@@ -6276,38 +7069,115 @@ var CherryToolEngine = class {
 				releaseSlot?.();
 			}
 		} else text = "";
+		const legacy = this.#legacyAttachment(kind, raw, text);
 		return {
 			partId,
 			kind,
 			revision,
-			content: text,
-			...this.#attachmentFace(kind, raw, content),
+			content: legacy === void 0 ? text : legacy.remainder,
+			...legacy === void 0 ? this.#attachmentFace(kind, raw, content) : this.#attachmentFace(kind, raw, content, legacy.record),
 			...typeof raw["state"] === "string" ? { state: raw["state"] } : {},
 			...typeof raw["toolName"] === "string" ? { toolName: raw["toolName"] } : {},
 			...typeof raw["toolCallId"] === "string" ? { toolCallId: raw["toolCallId"] } : {}
 		};
 	}
 	/**
+	* The ONE place a legacy `data` part is recognised as an attachment: the
+	* structural discriminator, the JSON parse, and the lossless CONTENT rule.
+	*
+	* The legal legacy face is `{kind: 'data', name: 'file', content: {text:
+	* '{\"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.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.
+	*
+	* WHY THE NAME IS THE DISCRIMINATOR, and why it is not a heuristic: the
+	* desktop labels every `data` part with its data KIND in `name` — an
+	* attachment is `'file'`, a task event is `'data-compaction-anchor'`, an
+	* error is `'data-error'` — and the protocol types that field as an
+	* `opaqueId`. This lift therefore REQUIRES the label to be the literal
+	* `'file'` rather than ASSUMING every peer sets one: a `data` part that
+	* carries no name reads as no name, is not lifted, and passes through
+	* untouched. Several of those payloads are JSON too, so "the text parses"
+	* proves nothing; `'file'` is the one label that means "this is an
+	* attachment".
+	*
+	* NOTHING IS EVER DEGRADED: a text that does not parse, parses to a
+	* non-record, or carries neither `mediaType` nor `filename` as a string is
+	* not an attachment, and the part passes through COMPLETELY unchanged
+	* (`remainder` is the raw text, no field is lifted) — this runs on every
+	* `data` part of every read, so a throw here would take down the whole
+	* snapshot.
+	*
+	* THE CONTENT RULE: `remainder` is EMPTY when every key of the record is one
+	* this face projects (`mediaType`, `filename`) — the metadata is fully
+	* represented, and a model sees structure rather than a blob. A record
+	* carrying ANY other key keeps its raw text, so a field we do not project is
+	* never silently dropped (lossless by default). That promise is about KEYS: a
+	* key we DO project whose value is not a string (say `mediaType: 123`) is
+	* counted as represented — the key survives — and reports no field, because
+	* this face lifts strings only. Emptied text therefore means "every key was
+	* one of ours", not "every value produced a field".
+	*/
+	#legacyAttachment(kind, raw, text) {
+		if (kind !== "data" || optionalString(raw["name"]) !== "file") return void 0;
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return;
+		}
+		if (!isRecord(parsed)) return void 0;
+		if (optionalString(parsed["filename"]) === void 0 && optionalString(parsed["mediaType"]) === void 0) return;
+		const everythingLifted = Object.keys(parsed).every((key) => key === "mediaType" || key === "filename");
+		return {
+			record: parsed,
+			remainder: everythingLifted ? "" : text
+		};
+	}
+	/**
 	* The descriptive metadata of an attachment part — and deliberately NOT a
 	* way to reach its bytes.
 	*
-	* Two peer generations are covered, because both are inside the verified
-	* range and they disagree about where the metadata lives:
+	* Two legal faces are covered, because both are inside the verified range and
+	* they disagree about where the metadata lives:
 	*
 	*  - **Cherry ≥ 2.1.5** — `{kind: 'file', name, ref}`, ref at the TOP level.
-	*  - **Cherry 2.1.4** — `{kind: 'data', name, content: {mediaType, filename}}`.
+	*  - **legacy** — `{kind: 'data', name: 'file', content: {text: '<JSON>'}}`,
+	*    the metadata as JSON TEXT. {@link CherryToolEngine.#legacyAttachment}
+	*    parses it and passes the record in here.
+	*
+	* A THIRD arm — a `data` part carrying `{mediaType, filename}` as an OBJECT
+	* inside `content` — is schema-ILLEGAL under the pinned protocol (see the
+	* docblock above) and stays as a DEFENSIVE lift for a peer that violates it.
+	* It is not the 2.1.4 projection: that story was wrong, and a misbehaving
+	* peer's parts are not re-validated client-side, so the guarded arm costs
+	* nothing and covers exactly the peer it was written for.
 	*
 	* Only string fields are lifted: a null `filename` (the peer's explicit "no
 	* name") stays absent rather than becoming the string "null". Anything a
 	* caller needs beyond this — the bytes — stays behind `agent.content.read`,
 	* which this plugin does not call for a file part.
-	*/
-	#attachmentFace(kind, raw, content) {
+	*
+	* WHEN A PARSED `metadata` RECORD IS PRESENT IT IS AUTHORITATIVE. A legacy
+	* attachment's record can arrive externalized as `{ref}`, and that ref is the
+	* peer's serialization ENVELOPE, not the attachment's description: its
+	* `mediaType` is the literal `'text/plain'` the envelope is labelled with and
+	* its `byteLength` is the JSON metadata's own byte count. Letting either
+	* outrank the record would report `text/plain` as an image's media type and a
+	* size that is not the file's — so the record wins the media type, and this
+	* face reports NO `byteLength` at all (a legacy `data` part carries none). The
+	* `file` arm is untouched: there the ref IS the file's own description.
+	*/
+	#attachmentFace(kind, raw, content, metadata) {
 		if (kind !== "file" && kind !== "data") return {};
 		const ref = isRecord(raw["ref"]) ? raw["ref"] : isRecord(content["ref"]) ? content["ref"] : {};
-		const name = kind === "file" ? optionalString(raw["name"]) : optionalString(content["filename"]);
-		const mediaType = optionalString(ref["mediaType"]) ?? optionalString(content["mediaType"]);
-		const byteLength = optionalString(ref["byteLength"]);
+		const name = kind === "file" ? optionalString(raw["name"]) : optionalString(metadata?.["filename"]) ?? optionalString(content["filename"]);
+		const mediaType = kind === "data" && metadata !== void 0 ? optionalString(metadata["mediaType"]) ?? optionalString(content["mediaType"]) : optionalString(ref["mediaType"]) ?? optionalString(metadata?.["mediaType"]) ?? optionalString(content["mediaType"]);
+		const byteLength = kind === "file" ? optionalString(ref["byteLength"]) : void 0;
 		return {
 			...name === void 0 ? {} : { name },
 			...mediaType === void 0 ? {} : { mediaType },
@@ -6395,7 +7265,7 @@ var CherryToolEngine = class {
 		const declaredBytes = Number(ref["byteLength"]);
 		const refusal = this.#externalizedRefusal(ref);
 		if (refusal !== void 0) throw refusal;
-		const maxSlices = Number.isSafeInteger(declaredBytes) ? Math.max(1, Math.ceil(declaredBytes / CONTENT_READ_MAX_BYTES)) : DEFAULT_CONTENT_SLICE_BOUND;
+		const maxSlices = Number.isSafeInteger(declaredBytes) ? Math.max(1, Math.ceil(declaredBytes / this.#contentReadSliceBytes)) : DEFAULT_CONTENT_SLICE_BOUND;
 		let offset = "0";
 		let sha;
 		let complete = false;
@@ -6408,7 +7278,7 @@ var CherryToolEngine = class {
 				contentId,
 				revision,
 				offset,
-				maxBytes: CONTENT_READ_MAX_BYTES
+				maxBytes: this.#contentReadSliceBytes
 			}, deadline === void 0 ? void 0 : { deadline: deadline.instant });
 			const data = typeof slice["dataBase64"] === "string" ? slice["dataBase64"] : "";
 			const cap = this.#externalizedByteCap;
@@ -6492,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 {
@@ -6701,11 +7571,29 @@ var CherryToolEngine = class {
 	*/
 	async #admitSend(connection, subscriptions, deviceId, sessionId, request) {
 		const { args, text } = request;
+		const callerId = optionalString(args["commandId"]);
 		const attempt = async (commandId, revisionOverride) => {
-			const expectedIdleRevision = revisionOverride ?? await this.#idleRevision(connection, subscriptions, deviceId, sessionId);
+			const remembered = callerId === void 0 || commandId !== callerId ? void 0 : this.#recallCommandBody(deviceId, callerId);
+			if (remembered !== void 0 && remembered.method !== SEND_METHOD) throw commandBodyDiffers();
+			const rememberedBody = remembered?.body;
+			if (remembered !== void 0 && (rememberedBody?.["sessionId"] !== sessionId || rememberedBody["text"] !== text)) throw commandBodyDiffers();
+			const expectedIdleRevision = optionalString(rememberedBody?.["expectedIdleRevision"]) ?? revisionOverride ?? await this.#idleRevision(connection, subscriptions, deviceId, sessionId);
 			const baselineSeq = this.#newestSeq(subscriptions, sessionId);
+			if (callerId !== void 0) this.#rememberCommandBody(deviceId, callerId, {
+				method: SEND_METHOD,
+				fingerprint: {
+					sessionId,
+					text
+				},
+				body: {
+					commandId,
+					sessionId,
+					text,
+					expectedIdleRevision
+				}
+			});
 			return {
-				receipt: await this.#command(connection, "agent.messages.send", {
+				receipt: await this.#command(connection, SEND_METHOD, {
 					commandId,
 					sessionId,
 					text,
@@ -6956,6 +7844,19 @@ var CherryToolEngine = class {
 						message: "`response` must be {kind:\"answer\", answers:{<question text>: <answer>}}"
 					};
 				}
+				const callerId = optionalString(args["commandId"]);
+				const answer = response === void 0 ? { decision } : { response };
+				const remembered = callerId === void 0 ? void 0 : this.#recallCommandBody(record.deviceId, callerId);
+				if (remembered !== void 0 && remembered.method !== RESPOND_METHOD) throw commandBodyDiffers();
+				if (remembered !== void 0) {
+					const fingerprint = {
+						sessionId,
+						interactionId,
+						...answer
+					};
+					if (!sameCommandValue(remembered.fingerprint, fingerprint)) throw commandBodyDiffers();
+					return this.#command(connection, RESPOND_METHOD, remembered.body);
+				}
 				await this.#ensureSubscription(record.deviceId, sessionId);
 				const subscriptions = this.#deps.subs(record.deviceId);
 				const snapshot = await this.#interactionSnapshot(connection, subscriptions, record.deviceId, sessionId, interactionId);
@@ -6963,15 +7864,25 @@ var CherryToolEngine = class {
 					error: "unknown-interaction",
 					message: `no interaction ${interactionId} is known for session ${sessionId}`
 				};
-				return this.#command(connection, "agent.interactions.respond", {
+				const body = {
 					commandId: this.#commandId(args),
 					sessionId,
 					interactionId,
 					expectedRevision: snapshot.revision,
 					expectedExecutionId: snapshot.executionId,
 					inputDigest: snapshot.inputDigest,
-					...response === void 0 ? { decision } : { response }
+					...answer
+				};
+				if (callerId !== void 0) this.#rememberCommandBody(record.deviceId, callerId, {
+					method: RESPOND_METHOD,
+					fingerprint: {
+						sessionId,
+						interactionId,
+						...answer
+					},
+					body
 				});
+				return this.#command(connection, RESPOND_METHOD, body);
 			}
 		});
 	}
@@ -7011,6 +7922,17 @@ var CherryToolEngine = class {
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
+				const callerId = optionalString(args["commandId"]);
+				const supplied = optionalString(args["expectedExecutionId"]);
+				const remembered = callerId === void 0 ? void 0 : this.#recallCommandBody(record.deviceId, callerId);
+				if (remembered !== void 0 && remembered.method !== CANCEL_METHOD) throw commandBodyDiffers();
+				if (remembered !== void 0) {
+					if (!sameCommandValue(remembered.fingerprint, {
+						sessionId,
+						expectedExecutionId: supplied
+					})) throw commandBodyDiffers();
+					return this.#command(connection, CANCEL_METHOD, remembered.body);
+				}
 				await this.#ensureSubscription(record.deviceId, sessionId);
 				const subscriptions = this.#deps.subs(record.deviceId);
 				const expectedExecutionId = await this.#activeExecutionId(connection, subscriptions, record.deviceId, sessionId);
@@ -7018,18 +7940,26 @@ var CherryToolEngine = class {
 					error: "no-active-execution",
 					message: `session ${sessionId} has no in-flight execution to cancel`
 				};
-				const supplied = optionalString(args["expectedExecutionId"]);
 				if (supplied !== void 0 && supplied !== expectedExecutionId) return {
 					error: "execution-mismatch",
 					expectedExecutionId,
 					supplied,
 					message: `the cached active execution is ${expectedExecutionId}, not ${supplied}; re-read the session before cancelling`
 				};
-				return this.#command(connection, "agent.executions.cancel", {
+				const body = {
 					commandId: this.#commandId(args),
 					sessionId,
 					expectedExecutionId
+				};
+				if (callerId !== void 0) this.#rememberCommandBody(record.deviceId, callerId, {
+					method: CANCEL_METHOD,
+					fingerprint: {
+						sessionId,
+						expectedExecutionId: supplied
+					},
+					body
 				});
+				return this.#command(connection, CANCEL_METHOD, body);
 			}
 		});
 	}
@@ -7120,7 +8050,7 @@ var CherryToolEngine = class {
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
 				const record = selected[0];
-				this.#forgetDevice(record.deviceId);
+				this.#forgetDevice(record.deviceId, { dropCommandBodies: true });
 				await this.#deps.evict(record.deviceId);
 				try {
 					this.#deps.store.remove(record.deviceId);
@@ -7388,7 +8318,8 @@ var CherryToolEngine = class {
 	*    the stored credential no longer describes a valid pairing. A transient
 	*    network drop ALSO lands here and clears the caches unnecessarily; that
 	*    is accepted, because the cost is one round trip per session on reuse and
-	*    the alternative is keeping snapshots across an identity change.
+	*    the alternative is keeping snapshots across an identity change. (The
+	*    remembered command BODIES are the one exception: see `#forgetDevice`.)
 	*  - `identity-mismatch` — the peer's pinned key changed: the pairing is over.
 	*
 	* {@link CherryToolEngine.#resolve} installs the watch on every tool call that
@@ -7411,7 +8342,7 @@ var CherryToolEngine = class {
 		this.#watchedConnections.add(connection);
 		watch(deviceId, (state) => {
 			if (state !== "offline" && state !== "identity-mismatch") return;
-			this.#forgetDevice(deviceId);
+			this.#forgetDevice(deviceId, { dropCommandBodies: state === "identity-mismatch" });
 		});
 	}
 	/**
@@ -7423,13 +8354,106 @@ var CherryToolEngine = class {
 	* leaves the archive (`cherry_unpair`), so a re-paired device cannot inherit
 	* the previous pairing's snapshots and a long-lived process does not
 	* accumulate entries for devices that no longer exist.
+	*
+	* The remembered command bodies obey a NARROWER seam than the read caches:
+	* `dropCommandBodies` is passed by the callers that invalidate the PAIRING
+	* (unpair, identity-mismatch), never by an ordinary `offline`. What a body
+	* replays against — the peer's command ledger — survives a reconnect, and the
+	* body is the only local copy of the exact bytes that ledger will accept, so
+	* a link drop that emptied it would cost the recovery itself, where the read
+	* caches merely pay one re-walk.
 	*/
-	#forgetDevice(deviceId) {
+	#forgetDevice(deviceId, options = {}) {
 		const prefix = `${deviceId}\u0000`;
 		for (const key of [...this.#revisionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#revisionCache, key);
 		for (const key of [...this.#executionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#executionCache, key);
 		for (const key of [...this.#interactionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#interactionCache, key);
 		for (const key of [...this.#messageCache.keys()]) if (key.startsWith(prefix)) this.#dropCachedMessage(key);
+		if (options.dropCommandBodies === true) {
+			for (const key of [...this.#commandBodies.keys()]) if (key.startsWith(prefix)) this.#forget(this.#commandBodies, key);
+		}
+	}
+	/**
+	* The command remembered for one caller-supplied `commandId`, keyed
+	* `<deviceId>\0<commandId>` — or `undefined` when this device has never
+	* emitted one (a first attempt, or an entry the FIFO evicted).
+	*
+	* The METHOD is the caller's to judge, and it is a THREE-WAY decision, never
+	* a miss:
+	*
+	*  - no entry → a fresh call;
+	*  - an entry under the caller's own method → match the fingerprint, then
+	*    replay or refuse;
+	*  - an entry under a DIFFERENT method → a MISMATCH, refused locally. An id
+	*    minted for `agent.messages.send` is not a respond retry, and collapsing
+	*    that case into "no entry" would send a respond under a send's id and
+	*    let the PEER answer the conflict one round trip later.
+	*/
+	#recallCommandBody(deviceId, commandId) {
+		return this.#commandBodies.get(this.#cacheKey(deviceId, commandId));
+	}
+	/**
+	* TEST SEAM — the remembered bodies, as one `commandId` per device.
+	*
+	* The memory itself is PRIVATE, and stays that way for callers. What a test
+	* needs to assert is its bookkeeping — that the bound evicts the oldest entry
+	* and that {@link CherryToolEngine.#forgetDevice} drops a device's entries —
+	* and neither can be observed through a real retry: a retry of an evicted id
+	* is indistinguishable from a retry of an absent one, because both are refused
+	* locally by the same rule. Keys are rendered WITHOUT the device component so
+	* a test reads ids, not cache internals.
+	*/
+	rememberedCommandIds(deviceId) {
+		const prefix = `${deviceId}${CACHE_KEY_SEPARATOR}`;
+		return [...this.#commandBodies.keys()].filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+	}
+	/**
+	* TEST SEAM — fill the memory the way a long-lived process would: one entry
+	* per id, WITHOUT spending a wire call on each. The bound and the FIFO order
+	* are the engine's own ({@link CherryToolEngine.#rememberCommandBody}), which
+	* is what makes this a test of the real policy rather than of a mock of it.
+	*/
+	rememberCommandBodyForTest(deviceId, commandId) {
+		this.#rememberCommandBody(deviceId, commandId, {
+			method: "agent.messages.send",
+			fingerprint: {
+				sessionId: "session-for-test",
+				text: "text-for-test"
+			},
+			body: {
+				commandId,
+				sessionId: "session-for-test",
+				text: "text-for-test",
+				expectedIdleRevision: "0"
+			}
+		});
+	}
+	/**
+	* Remembers the exact body one caller-supplied `commandId` was ISSUED with,
+	* evicting this device's oldest entry when it is at the bound.
+	*
+	* FIFO, per device: `Map` insertion order IS the policy, the same deliberate
+	* choice the session caches document, and a `set` on an EXISTING key keeps its
+	* position — a refresh is a rewrite, not a use, so the policy stays
+	* insert-order rather than becoming LRU. One line per eviction, naming the
+	* device and the bound only.
+	*/
+	#rememberCommandBody(deviceId, commandId, remembered) {
+		const key = this.#cacheKey(deviceId, commandId);
+		if (!this.#commandBodies.has(key)) {
+			let own = 0;
+			let oldest;
+			for (const candidate of this.#commandBodies.keys()) {
+				if (!candidate.startsWith(`${deviceId}\u0000`)) continue;
+				own += 1;
+				if (oldest === void 0) oldest = candidate;
+			}
+			if (own >= this.#commandBodyEntriesPerDevice && oldest !== void 0) {
+				this.#commandBodies.delete(oldest);
+				console.warn(`[cherry-remote] remembered command bodies for device ${deviceId} reached their ${this.#commandBodyEntriesPerDevice}-commandId bound; evicted the oldest (a retry of that commandId now re-derives its body, and the peer decides whether it replays)`);
+			}
+		}
+		this.#commandBodies.set(key, remembered);
 	}
 	/**
 	* The session's current idle revision, from the SUBSCRIPTION CACHE.
@@ -8139,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),
@@ -8224,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;
@@ -8290,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)}`);
 		});
 	}
 	/**
@@ -9826,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 = {};
@@ -9852,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) {
@@ -10250,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 }
 	})));
 }
 /**
@@ -10420,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
@@ -10474,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);
@@ -10488,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);
@@ -10508,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 {
@@ -10634,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)
 	};
 }
 /**
@@ -10663,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;
@@ -10704,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(),
@@ -10769,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) => {
@@ -10790,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);
@@ -10881,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.
@@ -10894,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. */
@@ -10929,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 })
 			});
@@ -10997,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;