dsh-cherry-bridge 0.2.0 → 0.2.1

package/dist/index.mjs

@@ -5,8 +5,60 @@ import { chmod, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { RemoteSocketStream, connectSecureChannel, createDeviceIdentity, deviceIdentityId } from "@cherrystudio/remote-transport";
 import { createHash, randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
-import { directEndpointUrl, jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, pairingQrSchema, remoteFailureSchema } from "@cherrystudio/remote-protocol";
+import { advertisedEndpointSchema, directEndpointUrl, jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, pairingQrSchema, remoteFailureSchema } from "@cherrystudio/remote-protocol";
 import { peerIdFromString } from "@libp2p/peer-id";
+/**
+* Adds the candidate addresses a peer ADVERTISED that this record does not
+* already dial, returning how many hosts were added (issue #143).
+*
+* The rule is ADD-ONLY, deliberately:
+*
+*  - a host already in `hosts` is left exactly as it is, INCLUDING its port and
+*    its scheme. The peer's snapshot describes where it listens NOW, while a
+*    record entry may be an operator's choice (a pinned port, a TLS proxy) that
+*    every reconnect must keep honouring; re-pointing it would silently rewrite
+*    the operator's address book on a schedule. "Already dials" is judged
+*    CASE-INSENSITIVELY: a hostname is case-insensitive, the peer's schema
+*    lowercases what it advertises, and a PATCHed record stores what the
+*    operator typed — without this, `MyNAS.example` and `mynas.example` would
+*    both hold a dial slot. (An IPv6 literal in a different EXPANSION is NOT
+*    reconciled here; the PATCH path owns the archive's spelling, and it does
+*    not canonicalize either.)
+*  - nothing is removed HERE: a host the peer still advertises is re-learned
+*    after an operator PATCH drops it, because the peer is the source of truth
+*    for where it listens. The operator's answer to that is `forgetEndpoints`
+*    (issue #185), whose mark this function honours — addition stays add-only,
+*    and forgetting is a separate, explicit decision;
+*  - host, port and scheme are appended TOGETHER, which is what keeps the v4
+*    one-entry-per-host invariant true. That invariant is enforced on the READ
+*    path by `assertValidSecurity`/`assertValidPorts`, and a semantic failure
+*    there is NOT a quarantine (that class covers unreadable bytes): the throw
+*    escapes `parseArchive` out of `list()`, so a split entry would break every
+*    tool until an operator repaired the file;
+*  - past {@link MAX_CANDIDATE_HOSTS} nothing is added, and the loop stops
+*    rather than scanning the rest.
+*
+* `endpoints` must already have passed the peer's own `advertisedEndpointSchema`
+* (which bounds the port to 1..65535, the scheme to `ws`/`wss`, and rejects a
+* loopback destination), so every value written here is archive-valid without a
+* second validation pass.
+*/
+function mergeAdvertisedEndpoints(record, endpoints) {
+	const dialed = new Set(record.hosts.map((host) => host.toLowerCase()));
+	const forgotten = new Set((record.forgottenHosts ?? []).map((host) => host.toLowerCase()));
+	let added = 0;
+	for (const endpoint of endpoints) {
+		const key = endpoint.host.toLowerCase();
+		if (dialed.has(key) || forgotten.has(key)) continue;
+		if (record.hosts.length >= 32) break;
+		record.hosts.push(endpoint.host);
+		record.ports[endpoint.host] = endpoint.port;
+		record.security[endpoint.host] = endpoint.security;
+		dialed.add(key);
+		added += 1;
+	}
+	return added;
+}
 const FILE_MODE = 384;
 /**
 * Version-to-version migrations, keyed by the version they upgrade from.
@@ -118,6 +170,7 @@ function assertValidRecord(disk) {
 	if (typeof disk.port !== "number" || !Number.isInteger(disk.port) || disk.port < 1 || disk.port > 65535) throw new Error("device archive entry field port must be an integer in 1..65535");
 	assertValidSecurity(disk.hosts, disk.security);
 	assertValidPorts(disk.hosts, disk.ports);
+	assertValidForgotten(disk.hosts, disk.forgottenHosts);
 	if (disk.accessToken !== void 0 !== (disk.tokenExpiresAt !== void 0)) throw new Error("device archive entry must carry accessToken and tokenExpiresAt together or not at all");
 	return disk;
 }
@@ -166,6 +219,60 @@ function assertValidPorts(hosts, ports) {
 	}
 }
 /**
+* `forgottenHosts`, when present, must be a list of non-empty strings with no
+* case-variant duplicates and no overlap with `hosts`.
+*
+* Each rule refuses a state whose MEANING is ambiguous: two spellings of one
+* host make "is this address suppressed?" depend on which entry the comparison
+* hit first, and a host that is both dialed and forgotten makes the dial list
+* and the suppression list disagree about the same address. The message names
+* the offending host — these are addresses an operator chose, not secrets.
+*/
+function assertValidForgotten(hosts, forgotten) {
+	if (forgotten === void 0) return;
+	if (!Array.isArray(forgotten)) throw new Error("device archive entry field forgottenHosts must be an array");
+	const dialed = new Set(hosts.map((host) => host.toLowerCase()));
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of forgotten) {
+		if (typeof entry !== "string" || entry.length === 0) throw new Error("device archive entry field forgottenHosts must list non-empty strings");
+		const key = entry.toLowerCase();
+		if (seen.has(key)) throw new Error(`device archive entry lists host "${entry}" in forgottenHosts more than once`);
+		if (dialed.has(key)) throw new Error(`device archive entry names host "${entry}" in both hosts and forgottenHosts`);
+		seen.add(key);
+	}
+}
+/**
+* Repairs ONE cross-build state on the READ path: a host listed in both
+* `hosts` and `forgottenHosts` (issue #185).
+*
+* A build that predates the field PRESERVES it but cannot honour it, so a
+* downgrade followed by a still-advertising desktop appends the host to
+* `hosts` while the mark stays. Upgrading again then yields a record that says
+* both "dial it" and "never dial it". Refusing it would brick every device tool
+* until an operator hand-edits a 0600 file, so the READ path keeps the DIAL
+* list — what the running build actually did — and drops the mark, with a
+* warning naming the device and host (addresses are not secrets).
+*
+* The WRITE paths stay strict: `upsert`, `forgetEndpoints` and
+* `rememberEndpoints` never produce the overlap, and `assertValidRecord`
+* refuses it. This runs ONLY on the read path, before that assertion.
+*/
+function reconcileForgottenMarks(disk) {
+	const forgotten = disk.forgottenHosts;
+	if (!Array.isArray(forgotten) || !Array.isArray(disk.hosts)) return disk;
+	const dialed = new Set(disk.hosts.map((host) => host.toLowerCase()));
+	const kept = forgotten.filter((host) => !(typeof host === "string" && dialed.has(host.toLowerCase())));
+	if (kept.length === forgotten.length) return disk;
+	for (const host of forgotten) {
+		if (typeof host !== "string" || !dialed.has(host.toLowerCase())) continue;
+		console.warn(`device archive entry ${String(disk.deviceId)} lists host "${host}" as both dialed and forgotten; keeping it dialed and dropping the mark (a plugin downgrade can produce this)`);
+	}
+	return {
+		...disk,
+		forgottenHosts: kept
+	};
+}
+/**
 * Read path, fixed order: loose parse -> completeness gate -> version judgement
 * -> migration -> assert the required `DeviceRecord` type.
 *
@@ -193,7 +300,7 @@ function parseRecord(raw, archiveVersion) {
 		if (migrate === void 0) throw new Error(`no migration registered from device archive schemaVersion ${step}`);
 		migrated = migrate(migrated);
 	}
-	return assertValidRecord(migrated);
+	return assertValidRecord(reconcileForgottenMarks(migrated));
 }
 function parseArchive(parsed) {
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("device archive must be a JSON object");
@@ -311,6 +418,26 @@ var QuarantinedArchiveError = class QuarantinedArchiveError extends Error {
 	}
 };
 /**
+* Refusal raised by {@link DeviceStore.forgetEndpoints} when the operation
+* would leave a record with NO dial candidate.
+*
+* A record with nothing to dial is worse than the stale address the operator
+* wanted gone: every tool would answer `offline` until a RE-PAIR or a PATCH
+* with a non-empty `hosts` list writes a fresh one, and the archive would look
+* healthy the whole time. The check is ATOMIC — the whole call refuses, so a
+* name for the last host cannot remove a different host on its way to failing.
+* Nothing is written when this is thrown.
+*/
+var LastCandidateHostError = class extends Error {
+	deviceId;
+	constructor(deviceId) {
+		super(`device ${deviceId}: refusing to forget the last dial candidate — the record would have nothing to dial. Keep at least one address.`);
+		this.name = "LastCandidateHostError";
+		this.deviceId = deviceId;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/**
 * Preserves an unreadable archive as `<file>.corrupt` (best effort — a failed
 * copy must not mask the original problem) and returns the path it landed at.
 */
@@ -477,6 +604,137 @@ var DeviceStore = class {
 		const devices = this.#load().filter((record) => record.deviceId !== deviceId);
 		this.#persist(devices);
 	}
+	/**
+	* Merges freshly learned addresses into one record and writes ONLY when that
+	* record gained a host (issue #143), returning the number added.
+	*
+	* It exists so the enrichment is an ARCHIVE operation rather than an
+	* `upsert` the assembly assembles by hand, and so a merge that adds nothing
+	* never rewrites (and fsyncs) the archive: `connection.endpoints` is asked on
+	* every connect, and a stable desktop would otherwise pay a full atomic write
+	* per reconnect. The merge runs on a CLONE and is committed as a new list,
+	* mirroring `upsert`'s discipline — the store never adopts a caller's object
+	* graph, and a write refused at {@link #persist}'s own gate cannot have
+	* half-edited the record the archive still holds.
+	*
+	* `desktopIdentity` is the pin the answering connection belongs to: the
+	* record must still name that desktop. A RE-PAIR under the same `deviceId`
+	* (the desktop regenerated its identity) would otherwise take an address
+	* learned from the previous pairing — a stale candidate whose every dial then
+	* fails the Noise pin, permanently, because learning never removes.
+	*
+	* An unknown `deviceId` is a no-op — the record may have been removed (or
+	* re-paired) between the RPC and this write.
+	*/
+	learnEndpoints(deviceId, endpoints, desktopIdentity) {
+		const devices = this.#load();
+		const index = devices.findIndex((record) => record.deviceId === deviceId);
+		if (index < 0) return 0;
+		if (devices[index].desktopIdentity !== desktopIdentity) return 0;
+		const merged = structuredClone(devices[index]);
+		const added = mergeAdvertisedEndpoints(merged, endpoints);
+		if (added === 0) return 0;
+		const next = [...devices];
+		next[index] = merged;
+		this.#persist(next);
+		return added;
+	}
+	/**
+	* FORGETS addresses (issue #185): drops each named host from the dial list —
+	* host, scheme and port as one unit — and records it so the next
+	* advertisement cannot put it back. Returns the hosts that left the dial list
+	* (`removed`) and the marks this call added (`marked`).
+	*
+	* This is the operation learning cannot provide. `connection.endpoints` is
+	* asked on every handshake, so an address the desktop still advertises
+	* returns after any removal the operator makes by PATCH; forgetting is the
+	* explicit decision that outranks it.
+	*
+	* - Matching is CASE-INSENSITIVE (a PATCHed record keeps the operator's
+	*   spelling, the peer's schema lowercases what it advertises), and the mark
+	*   records the ARCHIVE's spelling when the host was dialed, the caller's
+	*   otherwise.
+	* - Naming an address the record does not dial is legal and still marks it:
+	*   suppression is the point, and a pre-emptive forget must survive until
+	*   the peer advertises the address.
+	* - Removing the LAST candidate throws {@link LastCandidateHostError} and
+	*   writes NOTHING — no host, no scheme, no port, no mark.
+	* - A call that changes no byte (the host was already forgotten) does not
+	*   rewrite (or fsync) the archive.
+	*
+	* The write goes through `#persist` on a CLONE with the result re-validated,
+	* so a caller-supplied junk host can never land a record the next read would
+	* refuse. An unknown `deviceId` is a no-op, like {@link learnEndpoints}.
+	*/
+	forgetEndpoints(deviceId, hosts) {
+		const devices = this.#load();
+		const index = devices.findIndex((record) => record.deviceId === deviceId);
+		if (index < 0) return {
+			removed: [],
+			marked: []
+		};
+		const merged = structuredClone(devices[index]);
+		const wanted = new Set(hosts.map((host) => host.toLowerCase()));
+		const removed = merged.hosts.filter((host) => wanted.has(host.toLowerCase()));
+		if (removed.length > 0 && removed.length === merged.hosts.length) throw new LastCandidateHostError(deviceId);
+		for (const host of removed) {
+			delete merged.security[host];
+			delete merged.ports[host];
+		}
+		merged.hosts = merged.hosts.filter((host) => !wanted.has(host.toLowerCase()));
+		const forgotten = merged.forgottenHosts ?? [];
+		const known = new Set(forgotten.map((host) => host.toLowerCase()));
+		const marked = [];
+		for (const host of hosts) {
+			const key = host.toLowerCase();
+			if (known.has(key)) continue;
+			const spelling = removed.find((entry) => entry.toLowerCase() === key) ?? host;
+			forgotten.push(spelling);
+			known.add(key);
+			marked.push(spelling);
+		}
+		if (removed.length === 0 && marked.length === 0) return {
+			removed: [],
+			marked: []
+		};
+		merged.forgottenHosts = forgotten;
+		assertValidRecord(merged);
+		const next = [...devices];
+		next[index] = merged;
+		this.#persist(next);
+		return {
+			removed,
+			marked
+		};
+	}
+	/**
+	* Lifts a forget mark (issue #185), returning the marks that were removed.
+	*
+	* It does NOT dial the host again: it only lets the next handshake's
+	* advertisement add it back through the ordinary learning path, with the
+	* port and scheme the peer reports at that moment. An operator who wants the
+	* address back immediately PATCHes it into `hosts`, which clears the mark on
+	* the same write.
+	*
+	* No-op (and no write) when the device is unknown, nothing is forgotten, or
+	* none of the named hosts is marked.
+	*/
+	rememberEndpoints(deviceId, hosts) {
+		const devices = this.#load();
+		const index = devices.findIndex((record) => record.deviceId === deviceId);
+		if (index < 0) return { restored: [] };
+		const current = devices[index].forgottenHosts ?? [];
+		if (current.length === 0) return { restored: [] };
+		const wanted = new Set(hosts.map((host) => host.toLowerCase()));
+		const restored = current.filter((host) => wanted.has(host.toLowerCase()));
+		if (restored.length === 0) return { restored: [] };
+		const merged = structuredClone(devices[index]);
+		merged.forgottenHosts = (merged.forgottenHosts ?? []).filter((host) => !wanted.has(host.toLowerCase()));
+		const next = [...devices];
+		next[index] = merged;
+		this.#persist(next);
+		return { restored };
+	}
 	#load() {
 		if (this.#devices !== void 0) return this.#devices;
 		let archive;
@@ -2647,6 +2905,33 @@ const DEFAULT_BACKOFF_MAX_MS = 6e4;
 const DEFAULT_REFRESH_GRACE_MS = 3e4;
 const DEFAULT_CONNECT_TIMEOUT_MS$1 = 1e4;
 const DEFAULT_PROTOCOL_VERSIONS = [1];
+/**
+* How long the optional `connection.endpoints` enrichment (issue #143) may hold
+* up ONE handshake before the connection gives up on it.
+*
+* The call runs INSIDE the handshake, so without a bound of its own it would
+* inherit the rpc layer's 60 s default: a peer that advertises
+* `connectionEndpointsVersion: 1` and then never answers (a wedged API gateway)
+* would keep the device in `connecting` for a minute, and every reconnect would
+* pay it again. THIS layer bounds it because the enrichment is worth
+* milliseconds, not a retry.
+*
+* WHY 2 s. The peer's handler is a local computation
+* (`getRemoteEndpoint()`: `networkInterfaces()` plus two config reads), so a
+* round trip is sub-millisecond on a LAN and 2 s is ~4 orders of magnitude of
+* slack.
+*
+* The UPPER bound is NOT derived from a claim about the whole handshake: a dial
+* already burns up to `DEFAULT_CONNECT_TIMEOUT_MS` (10 s) and hello/authenticate
+* ride the rpc layer's 60 s default, so `connected` can arrive long after a
+* tool's `DEVICE_SETTLE_WAIT_MS` (5 s) wait whatever this constant is. What is
+* derived is narrower and true: THIS wait alone must stay below that window, so
+* a peer that advertises the capability and then hangs on this one call cannot
+* by itself push the state flip past the window a tool already waited out. A
+* timeout costs one reconnect's worth of enrichment and says nothing about the
+* device.
+*/
+const ENDPOINTS_LEARN_TIMEOUT_MS = 2e3;
 /** Ping-silence multiplier: 2×heartbeatMs without a pong judges the line dead. */
 const SILENCE_FACTOR = 2;
 /** The deliberate local-shutdown face of a disposed client (see the replay path). */
@@ -2735,7 +3020,8 @@ var SecondWindowRateLimiter = class {
 	async acquire() {
 		let release;
 		const ahead = this.#queue;
-		this.#queue = ahead.then(() => new Promise((resolve) => release = resolve));
+		const next = () => new Promise((resolve) => release = resolve);
+		this.#queue = ahead.then(next, next);
 		await ahead;
 		try {
 			for (;;) {
@@ -2920,6 +3206,50 @@ function businessWindowFor(reportedInFlightRequests) {
 	return Math.max(1, Math.min(BUSINESS_MAX_IN_FLIGHT, Math.floor(reportedInFlightRequests / 2)));
 }
 /**
+* The destinations a `connection.endpoints` answer may contribute, in the order
+* the peer listed them (issue #143). Empty when the answer must be discarded.
+*
+* TWO answers are refused WHOLE:
+*
+*  - **the identity pin.** The answer must name the very desktop this record is
+*    pinned to (`DeviceRecord.desktopIdentity`). Noise already pins the peer's
+*    static key, so this is not the adversarial case it protects against — it
+*    is the defence against a CONFUSED answer (a proxy, a desktop whose identity
+*    was regenerated, a future protocol that answers for more than one host):
+*    the list decides where this client dials, so a list that cannot be
+*    attributed to our own desktop may not change it;
+*  - a MISSING or NON-STRING `desktopIdentity`: `undefined !== pin`, and a
+*    number is not the pin either, so both fall out of the same comparison.
+*
+* One refusal is per ENTRY: `advertisedEndpointSchema`, the peer's own
+* destination schema, rejects a LOOPBACK destination (a shared address that
+* resolves to our own machine would send the next reconnect to the wrong host)
+* and normalizes the host (case, IPv6), so the archive never stores a spelling
+* the dial cannot use. One unusable row must not discard its neighbours.
+*
+* NOT total on the wire shape, deliberately: a non-object answer or a non-array
+* `endpoints` throws here, and `#learnEndpoints`' one structural `catch` is what
+* turns that into the silent no-op the contract promises. Defending each shape
+* twice would look safer and be worse: the redundancy masks which guard a test
+* actually pins (issue #114's lesson), and the whole ANSWER is untrusted
+* anyway, so the boundary belongs at the caller, where the handshake can see
+* it. `endpoints ?? []` is the one shape that needs no throw: it is the legal
+* "no addresses right now" answer (the desktop's `addresses` can be empty).
+*
+* No length bound is needed here: one JSON-RPC record is capped at 64 KiB by
+* the transport, and the desktop's own snapshot is `addresses.slice(0, 32)`.
+*/
+function advertisedEndpoints(result, desktopIdentity) {
+	const answer = result;
+	if (answer.desktopIdentity !== desktopIdentity) return [];
+	const accepted = [];
+	for (const raw of answer.endpoints ?? []) {
+		const parsed = advertisedEndpointSchema.safeParse(raw);
+		if (parsed.success) accepted.push(parsed.data);
+	}
+	return accepted;
+}
+/**
 * The desktop's content-read allowance: 512/s, and the SAME in both generations
 * (`RemoteAccessService.ts` counts `agent.content.read` on its own counter,
 * 512 in v2.1.6 and v2.1.7 alike; only the shared line moved, 64 ⇒ 256).
@@ -3000,6 +3330,7 @@ var DeviceConnection = class {
 	#protocolVersions;
 	#helloProtocolVersions;
 	#transportRetryWaitMs;
+	#onAdvertisedEndpoints;
 	#stateListeners = /* @__PURE__ */ new Set();
 	/**
 	* Callers parked in {@link waitForSettled}. Separate from the state listeners
@@ -3062,6 +3393,7 @@ var DeviceConnection = class {
 		this.#protocolVersions = opts.protocolVersions ?? DEFAULT_PROTOCOL_VERSIONS;
 		this.#helloProtocolVersions = opts.helloProtocolVersions ?? this.#protocolVersions;
 		this.#transportRetryWaitMs = opts.transportRetryWaitMs ?? 5e3;
+		this.#onAdvertisedEndpoints = opts.onAdvertisedEndpoints;
 	}
 	/**
 	* The business RPC surface: rate-smoothed and gated on `connected`. Typed
@@ -3388,6 +3720,7 @@ var DeviceConnection = class {
 			if (reason === "GRANT_REVOKED" || reason === "UNAUTHENTICATED") throw new AuthRejectedError(reason);
 			throw error instanceof Error ? error : new Error(String(error));
 		}
+		await this.#learnEndpoints(link, hello.connectionEndpointsVersion);
 		if (epoch !== this.#epoch) {
 			client.dispose();
 			link.channel.close().catch(noop$1);
@@ -3411,6 +3744,51 @@ var DeviceConnection = class {
 		console.info(`[cherry-remote] device ${this.record.deviceId} connected (${digestIdentity(link.channel.remoteIdentity)})`);
 	}
 	/**
+	* Best-effort enrichment of the dial list from the peer's advertised
+	* endpoints (issue #143).
+	*
+	* WHAT THIS BUYS: candidates the pairing never saw — a VPN or second-NIC
+	* address that appeared after the QR was minted. It does NOT heal a total
+	* address change (the list is captured on the old path) and can never carry
+	* TLS (the desktop's snapshot is `security: 'ws'`), so a `wss` route still
+	* comes from the QR or the operator.
+	*
+	* EVERY failure here is SILENT and non-fatal, because this is an enrichment,
+	* not a verdict: a peer that does not advertise the capability (`connection`
+	* through 2.1.3 has neither the hello bit nor this method), one advertising a
+	* version this client cannot speak (strictly `1` — a higher number is not
+	* evidence that it speaks 1, the same rule the paged-summaries bit took), a
+	* refused call (the desktop throws when its gateway is not running), a wedged
+	* one (bounded by {@link ENDPOINTS_LEARN_TIMEOUT_MS}), an unattributable
+	* answer, or a store that cannot write. None of them is a CONNECTION failure:
+	* the link comes up either way, and only the archive is left without the new
+	* addresses — this instance's own record may already carry them, because the
+	* merge runs before the callback (see the paragraph below).
+	*
+	* The MERGE happens in two places on purpose: here (this instance's record,
+	* so its next reconnect dials the new address) and through the callback (the
+	* assembly's archive, so a restart keeps it). They are the same pure rule
+	* against two copies of the record, and each is idempotent.
+	*
+	* ONE `catch` covers everything after the gate, and that is the contract, not
+	* laziness: a refused call, a wedged one (bounded by
+	* {@link ENDPOINTS_LEARN_TIMEOUT_MS}), an answer of the wrong SHAPE (the
+	* parser throws rather than defending every field twice), a throwing assembly
+	* hook (an unwritable archive), or a bug in the merge must all land here —
+	* none of them may fail the handshake. The observable promise is therefore
+	* structural: this method cannot reject.
+	*/
+	async #learnEndpoints(link, capability) {
+		if (capability !== 1) return;
+		try {
+			const endpoints = advertisedEndpoints(await this.#houseCall(link, "connection.endpoints", { domain: "agent" }, ENDPOINTS_LEARN_TIMEOUT_MS), this.record.desktopIdentity);
+			if (endpoints.length === 0) return;
+			const added = mergeAdvertisedEndpoints(this.record, endpoints);
+			if (added > 0) console.info(`[cherry-remote] device ${this.record.deviceId} learned ${added} advertised endpoint(s)`);
+			this.#onAdvertisedEndpoints?.(endpoints);
+		} catch {}
+	}
+	/**
 	* authenticate with the stored token; a stale token (TOKEN_EXPIRED /
 	* UNAUTHENTICATED) is retried exactly once without it before the pairing
 	* is declared invalid.
@@ -5892,6 +6270,54 @@ function optionalString(value) {
 	return typeof value === "string" && value !== "" ? value : void 0;
 }
 /**
+* The `hosts` argument of `cherry_devices`' write actions (issue #185): a
+* non-empty list of non-empty host names, with no case-variant duplicate.
+*
+* Each rule is a state the store would have to interpret: an empty name can
+* never match a dialed host, and two spellings of one host would make "is this
+* address forgotten?" depend on which entry a comparison hit first. Values are
+* TRIMMED here (the model-facing surface is where a stray space is caught);
+* the archive then stores the spelling it already had for a dialed host.
+*/
+function hostListArgument(value) {
+	if (!Array.isArray(value) || value.length === 0) return {
+		error: "invalid-hosts",
+		message: "`hosts` must be a non-empty array of host names"
+	};
+	const hosts = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of value) {
+		if (typeof entry !== "string" || entry.trim() === "") return {
+			error: "invalid-hosts",
+			message: "`hosts` entries must be non-empty strings"
+		};
+		let host = entry.trim();
+		if (host.startsWith("[") && host.endsWith("]")) {
+			try {
+				new URL(`http://${host}/`);
+			} catch {
+				return {
+					error: "invalid-hosts",
+					message: `\`hosts\` entry "${host}" is not a valid IPv6 literal`
+				};
+			}
+			host = host.slice(1, -1);
+		}
+		if (host.length > 256) return {
+			error: "invalid-hosts",
+			message: "`hosts` entry exceeds 256 characters"
+		};
+		const key = host.toLowerCase();
+		if (seen.has(key)) return {
+			error: "invalid-hosts",
+			message: `\`hosts\` names "${host}" more than once (host names are case-insensitive)`
+		};
+		seen.add(key);
+		hosts.push(host);
+	}
+	return hosts;
+}
+/**
 * The peer's `agent.messages.send` refusal for a STALE `expectedIdleRevision`,
 * in the exact shape Cherry Studio answers it: a `rejected` receipt whose
 * `error` is `{reason: 'CONFLICT', message: 'Session is not idle at the
@@ -6572,26 +6998,86 @@ var CherryToolEngine = class {
 	#devicesTool() {
 		return defineCherryTool({
 			name: "cherry_devices",
-			description: "List every paired Cherry Studio desktop with its connection state (connected/connecting/offline/disabled/identity-mismatch). An optional `device` narrows the list to one device (display name prefix or deviceId).",
+			description: "List every paired Cherry Studio desktop with its connection state (connected/connecting/offline/disabled/identity-mismatch). An optional `device` narrows the list to one device (display name prefix or deviceId). `action: \"forget\"` removes the named `hosts` from that device's dial candidates AND stops the desktop's advertisements from adding them back; `action: \"remember\"` lifts that mark, so the next handshake may learn them again. Both write actions require `device` and `hosts`.",
 			parameters: {
 				type: "object",
-				properties: { device: {
-					type: "string",
-					description: "Optional device selector: exact deviceId, or a unique prefix of a deviceId or display name."
-				} },
+				properties: {
+					device: {
+						type: "string",
+						description: "Optional device selector: exact deviceId, or a unique prefix of a deviceId or display name."
+					},
+					action: {
+						type: "string",
+						enum: [
+							"list",
+							"forget",
+							"remember"
+						],
+						description: "What to do: `list` (the default) reads the devices; `forget`/`remember` edit ONE device's forgotten addresses and require `device` and `hosts`."
+					},
+					hosts: {
+						type: "array",
+						items: { type: "string" },
+						description: "For `forget`/`remember`: the host names to act on, matched case-insensitively. `forget` refuses to remove the last remaining address."
+					}
+				},
 				additionalProperties: false
 			},
 			execute: async (args) => {
+				const action = optionalString(args["action"]) ?? "list";
+				if (action !== "list" && action !== "forget" && action !== "remember") return {
+					error: "invalid-action",
+					message: "`action` accepts exactly \"list\", \"forget\" or \"remember\""
+				};
 				const selector = optionalString(args["device"]);
+				if (action === "list") {
+					const quarantined = this.#quarantineVerdict();
+					if (quarantined !== void 0) return quarantined;
+					if (selector === void 0) {
+						const records = this.#deps.store.list();
+						return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) };
+					}
+					const selected = this.#selectRecords(selector);
+					if (!Array.isArray(selected)) return selected;
+					return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) };
+				}
+				if (selector === void 0) return {
+					error: "device-required",
+					message: "`action` \"forget\"/\"remember\" needs `device`: a selector that names exactly one device"
+				};
+				const hosts = hostListArgument(args["hosts"]);
+				if (!Array.isArray(hosts)) return hosts;
 				const quarantined = this.#quarantineVerdict();
 				if (quarantined !== void 0) return quarantined;
-				if (selector === void 0) {
-					const records = this.#deps.store.list();
-					return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) };
-				}
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
-				return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) };
+				const record = selected[0];
+				let removed = [];
+				let marked = [];
+				let restored = [];
+				try {
+					if (action === "forget") ({removed, marked} = this.#deps.store.forgetEndpoints(record.deviceId, hosts));
+					else ({restored} = this.#deps.store.rememberEndpoints(record.deviceId, hosts));
+				} catch (error) {
+					if (error instanceof LastCandidateHostError) return {
+						error: "last-address",
+						device: record.deviceId,
+						message: error.message
+					};
+					throw error;
+				}
+				if (removed.length > 0 || marked.length > 0 || restored.length > 0) await this.#deps.evict(record.deviceId);
+				const fresh = this.#deps.store.list().find((entry) => entry.deviceId === record.deviceId);
+				if (fresh === void 0) return this.#notFoundVerdict(selector);
+				const device = await this.#deviceView(fresh);
+				return action === "forget" ? {
+					device,
+					removed,
+					marked
+				} : {
+					device,
+					restored
+				};
 			}
 		});
 	}
@@ -6645,7 +7131,8 @@ var CherryToolEngine = class {
 			state,
 			enabled: record.enabled,
 			hosts: record.hosts,
-			port: record.port
+			port: record.port,
+			forgottenHosts: record.forgottenHosts ?? []
 		};
 	}
 	#agentsTool() {
@@ -10900,7 +11387,12 @@ 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 seen = /* @__PURE__ */ new Set();
+		for (const host of patch.hosts) {
+			const key = host.toLowerCase();
+			if (seen.has(key)) throw new PatchError("hosts must not contain duplicates");
+			seen.add(key);
+		}
 	}
 	const port = body["port"];
 	if (port !== void 0) {
@@ -11256,6 +11748,23 @@ async function handleRequest(req, res, route) {
 			writeError(res, 405, "method-not-allowed", "DELETE or PATCH only");
 			return;
 		}
+		if (first === "devices" && match.segments.length === 3 && second !== void 0) {
+			const deviceId = decodeSegment(second);
+			if (deviceId === void 0) {
+				writeError(res, 400, "invalid-request", "device id is not valid URL encoding");
+				return;
+			}
+			const action = match.segments[2];
+			if (action !== "forget" && action !== "remember") {
+				writeError(res, 404, "not-found", "unknown route");
+				return;
+			}
+			if (method !== "POST") {
+				writeError(res, 405, "method-not-allowed", "POST only");
+				return;
+			}
+			return await changeEndpoints(req, res, route, deviceId, action);
+		}
 		if (first === "pair" && match.segments.length === 1) {
 			if (method !== "POST") {
 				writeError(res, 405, "method-not-allowed", "POST only");
@@ -11293,7 +11802,18 @@ async function handleRequest(req, res, route) {
 	}
 }
 function listDevices(res, route) {
-	writeJson(res, 200, route.deps.store.list().map((device) => ({
+	writeJson(res, 200, route.deps.store.list().map((device) => deviceSummary(route, device)));
+}
+/**
+* One device as the browser sees it: the public archive projection, never a
+* credential.
+*
+* ONE builder, because FOUR faces answer this shape — `GET /devices`, the
+* `PATCH`, and the two endpoint actions of issue #204 — and a hand-written copy
+* per face is how a field ends up on one and not the others.
+*/
+function deviceSummary(route, device) {
+	return {
 		deviceId: device.deviceId,
 		displayName: device.displayName,
 		state: projectState(device, route.deps.connect),
@@ -11301,8 +11821,9 @@ function listDevices(res, route) {
 		hosts: [...device.hosts],
 		port: device.port,
 		security: { ...device.security },
-		ports: { ...device.ports }
-	})));
+		ports: { ...device.ports },
+		forgottenHosts: [...device.forgottenHosts ?? []]
+	};
 }
 /**
 * The `GET /diagnostics` body (spec §5).
@@ -11530,8 +12051,10 @@ async function patchDevice(req, res, route, deviceId) {
 	const previousSecurity = existing.security;
 	const previousPorts = existing.ports;
 	const nextPorts = patch.port !== void 0 && patch.port !== previousPort ? portsFor(patch.hosts ?? previousHosts, {}, patch.port) : patch.hosts === void 0 ? previousPorts : portsFor(patch.hosts, previousPorts, previousPort);
+	const nextForgotten = patch.hosts === void 0 || existing.forgottenHosts === void 0 ? void 0 : existing.forgottenHosts.filter((host) => !patch.hosts.some((nextHost) => nextHost.toLowerCase() === host.toLowerCase()));
 	const next = {
 		...existing,
+		...nextForgotten === void 0 ? {} : { forgottenHosts: nextForgotten },
 		...patch.displayName === void 0 ? {} : { displayName: patch.displayName },
 		...patch.enabled === void 0 ? {} : { enabled: patch.enabled },
 		...patch.hosts === void 0 ? {} : {
@@ -11557,21 +12080,12 @@ async function patchDevice(req, res, route, deviceId) {
 	} catch (error) {
 		console.warn(`[cherry-remote] device ${deviceId} reconnect failed`, error);
 	}
-	const state = projectState(next, route.deps.connect);
+	const summary = deviceSummary(route, next);
 	if (patch.enabled !== void 0 && patch.enabled !== previousEnabled) route.hub.publish("device-state", {
 		deviceId,
-		state
-	});
-	writeJson(res, 200, {
-		deviceId: next.deviceId,
-		displayName: next.displayName,
-		state,
-		enabled: next.enabled,
-		hosts: [...next.hosts],
-		port: next.port,
-		security: { ...next.security },
-		ports: { ...next.ports }
+		state: summary.state
 	});
+	writeJson(res, 200, summary);
 }
 function warnConnect(deviceId) {
 	return (error) => {
@@ -11583,14 +12097,128 @@ function sameHosts(a, b) {
 	return a.length === b.length && a.every((host, index) => host === b[index]);
 }
 /**
+* `POST /devices/:id/forget` and `POST /devices/:id/remember` (issue #204): the
+* settings page's door onto #185's endpoint maintenance, which until now only
+* the `cherry_devices` tool could open.
+*
+* One action per request, and the action IS the request: there is no composite
+* "patch the record AND forget a host" body whose ordering would have to be
+* defined. Every judgement is the store's — the last-candidate refusal, the
+* case-insensitive matching, the disjointness of `hosts`/`forgottenHosts` — so
+* the two doors share ONE set of STORE rules; this route only maps the verdicts
+* onto HTTP and answers the projection the PATCH answers. (The BODY PARSERS do
+* differ on purpose — see `parseEndpointHosts`.)
+*
+* EVICTION on a change, exactly like the tool's own arm and a PATCH's address
+* maintenance, and for a DIFFERENT reason on each action — which is why both
+* are stated here rather than waved through as "parity":
+*
+*  - FORGET: a pooled connection CAPTURES its record at construction, so the
+*    socket built before this write would keep dialing the host we just forgot.
+*    (The mark itself is honoured by the store's learn merge, so a reconnect is
+*    about the DIAL LIST, not about suppressing the address.)
+*  - REMEMBER: learning happens only INSIDE a handshake, against a clone of the
+*    stored record. Without the eviction a desktop that stays connected would
+*    not re-handshake for as long as the link holds, so the restored address
+*    would come back only after some later flap — the button would look inert.
+*
+* The cost is real and inherited from the tool's arm: an eviction disposes the
+* subscription layer and closes a healthy socket, so a write can drop an
+* in-flight command's link. One operator click now reaches that churn; that is
+* the price of "the archive is the truth" for a live connection.
+*/
+async function changeEndpoints(req, res, route, deviceId, action) {
+	const existing = route.deps.store.list().find((device) => device.deviceId === deviceId);
+	if (existing === void 0) {
+		writeError(res, 404, "not-found", `no device ${deviceId}`);
+		return;
+	}
+	let hosts;
+	try {
+		hosts = parseEndpointHosts(await readJsonBody(req));
+	} catch (error) {
+		writeError(res, 400, "invalid-request", error instanceof Error ? error.message : String(error));
+		return;
+	}
+	try {
+		if (action === "forget") {
+			const { removed, marked } = route.deps.store.forgetEndpoints(deviceId, hosts);
+			if (removed.length > 0 || marked.length > 0) evict(route, deviceId);
+		} else {
+			const { restored } = route.deps.store.rememberEndpoints(deviceId, hosts);
+			if (restored.length > 0) evict(route, deviceId);
+		}
+	} catch (error) {
+		if (writeQuarantineRefusal(res, route, error)) return;
+		if (error instanceof LastCandidateHostError) {
+			writeError(res, 400, "last-address", error.message);
+			return;
+		}
+		writeError(res, 400, "invalid-device", error instanceof Error ? error.message : String(error));
+		return;
+	}
+	writeJson(res, 200, deviceSummary(route, route.deps.store.list().find((device) => device.deviceId === deviceId) ?? existing));
+}
+/**
+* The body of an endpoint action: `{hosts: [...]}`, non-empty, every entry
+* normalized the same way the PATCH normalizes an address.
+*
+* The normalization is not cosmetic: an IPv6 literal is stored bare but a
+* browser copy-pastes it bracketed, and the store matches by host spelling —
+* so `[::1]` would be treated as an address the record does not dial and merely
+* marked, leaving the real `::1` in `hosts`. The PATCH's rule is reused for the
+* spelling (same `normalizeHost`), and deliberately NOT for its duplicate
+* refusal: a repeated host in an action body names one host twice, which the
+* store's own sets collapse, while the PATCH's duplicates would build an
+* ambiguous record (`hosts`, `security` and `ports` are keyed by host).
+*/
+function parseEndpointHosts(body) {
+	const hosts = body["hosts"];
+	if (!Array.isArray(hosts) || hosts.length === 0) throw new PatchError("hosts must be a non-empty array");
+	return hosts.map((entry) => {
+		if (typeof entry !== "string") throw new PatchError("hosts entries must be strings");
+		return normalizeHost(entry);
+	});
+}
+/**
 * The scheme map for a WHOLE-REPLACE host list (issue #126): each named host
 * keeps the scheme it was dialed with, a host the list just gained defaults to
 * `ws`, and hosts the list dropped leave no entry behind. An edit is an
 * address edit, not a scheme edit — re-typing the same host must not silently
 * demote a TLS-proxied desktop to a plain dial.
+*
+* "The same host" is CASE-INSENSITIVE (issue #189), the same comparison the
+* learn merge, the forget/remember actions and the mark clearing already use:
+* `NAS.example` and `nas.example` are one address, so a PATCH that re-types
+* the case keeps the remembered scheme instead of resetting it to `ws`.
+* `sameHosts`/`sameSecurity` stay EXACT on purpose — they decide whether an
+* address edit happened at all, and a new spelling IS a change to persist.
 */
 function securityFor(hosts, previous) {
-	return Object.fromEntries(hosts.map((host) => [host, Object.hasOwn(previous, host) ? previous[host] : "ws"]));
+	const remembered = indexByHost(previous);
+	return Object.fromEntries(hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? "ws"]));
+}
+/**
+* A case-insensitive index over a per-host map (issue #189).
+*
+* FIRST spelling wins on a collision. A hand-edited archive CAN hold two
+* spellings of one host (the store does not reject it, and this face does not
+* touch `previous`), so callers look their exact spelling up FIRST and consult
+* this index only as the fallback: a surviving spelling therefore keeps its
+* OWN entry, and the collision rule only decides what a THIRD spelling
+* inherits.
+*/
+function indexByHost(previous) {
+	const index = /* @__PURE__ */ new Map();
+	for (const [host, value] of Object.entries(previous)) {
+		const key = host.toLowerCase();
+		if (!index.has(key)) index.set(key, value);
+	}
+	return index;
+}
+/** The exact spelling's entry, else the case-insensitive one, else nothing. */
+function exactOrRemembered(previous, remembered, host) {
+	return Object.hasOwn(previous, host) ? previous[host] : remembered.get(host.toLowerCase());
 }
 /**
 * The port map for a host list (issue #135): each named host keeps the port it
@@ -11599,11 +12227,13 @@ function securityFor(hosts, previous) {
 *
 * `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.
+* field on this face must move the whole list. Same `Object.hasOwn`/
+* case-insensitive rules as `securityFor` (issue #189): a re-typed spelling
+* keeps its own port, and an inherited function is never a remembered port.
 */
 function portsFor(hosts, previous, fallback) {
-	return Object.fromEntries(hosts.map((host) => [host, Object.hasOwn(previous, host) ? previous[host] : fallback]));
+	const remembered = indexByHost(previous);
+	return Object.fromEntries(hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? fallback]));
 }
 /** Order-insensitive comparison for two scheme maps. */
 function sameSecurity(a, b) {
@@ -11933,7 +12563,10 @@ function connectionFor(deviceId) {
 		identity: requireIdentity(),
 		record,
 		rateBudgetPerSecond: state.rateBudgetPerSecond,
-		...state.wsTls === void 0 ? {} : { wsOptions: state.wsTls }
+		...state.wsTls === void 0 ? {} : { wsOptions: state.wsTls },
+		onAdvertisedEndpoints: (endpoints) => {
+			state.store.learnEndpoints(deviceId, endpoints, record.desktopIdentity);
+		}
 	});
 	state.connectionsBuilt += 1;
 	connection.onState((deviceState) => {