dsh-cherry-bridge 0.2.1 → 0.2.3

package/README.en.md

@@ -40,13 +40,13 @@ flowchart TB
 
 ```bash
 # From npm (recommended, pinned)
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.1
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.3
 
 # Install the latest npm release
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # From GitHub source (same commit as the npm release)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.1
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.3
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points
@@ -93,7 +93,7 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 | Key | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `dataDir` | string | `$DSH_HOME/cherry-remote` (fallback `~/.dsh/cherry-remote`) | Plugin data directory holding `identity.key` and `devices.json` (both `0600`). |
-| `perSessionCacheBytes` | number | `2097152` (2 MiB) | Per-session cap on the **local** subscription event cache; beyond it the oldest events are dropped LRU-style with a `warn`. |
+| `perSessionCacheBytes` | number | `2097152` (2 MiB) | Per-session cap on the **local** subscription event cache; beyond it events are dropped from the oldest end (FIFO) with a `warn`, but the **newest single event is always kept** — even when it alone exceeds the cap (no drop line is logged then, and the window stays over budget). |
 | `rateBudgetPerSecond` | number | `32` | Per-device smoothed request budget (req/s). The desktop's shared allowance is 64 req/s through 2.1.6 and 256 req/s from 2.1.7, and only the newer generation downgrades an overrun to a single `RATE_LIMITED` refusal (the older one terminates the session with close `1011`) — hence a value sized for the harsher generation. Content reads (`agent.content.read`) derive their own tier at 8:1, **capped at 512/s** (that allowance is the same in both generations). |
 | `wsTls` | object | — | **Flat** `tls.connect` options for every `wss` dial (`rejectUnauthorized` / `ca` only): operator-supplied trust for a desktop behind a private CA or a self-signed TLS front. Applied to BOTH dial sites — pairing and reconnect. **Never written to the device archive, never logged, never in diagnostics.** The whole object applies as written or is ignored entirely: an unknown key or unusable value warns by name and falls back to Node's default trust store (no partial application). |
 

package/README.md

@@ -38,13 +38,13 @@ flowchart TB
 
 ```bash
 # 从 npm 安装（推荐，钉住版本）
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.1
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.3
 
 # 安装 npm 最新发布版
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # 从 GitHub 源码安装（与 npm 发布同一提交）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.1
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.3
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），
@@ -85,7 +85,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 | 键 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | `dataDir` | string | `$DSH_HOME/cherry-remote`（回退 `~/.dsh/cherry-remote`） | 插件数据目录，存放 `identity.key` 与 `devices.json`（均 `0600`）。 |
-| `perSessionCacheBytes` | number | `2097152`（2 MiB） | 每个会话的**本地**订阅事件缓存上限，超出按 LRU 丢弃最旧事件并 `warn`。 |
+| `perSessionCacheBytes` | number | `2097152`（2 MiB） | 每个会话的**本地**订阅事件缓存上限；超出后从最旧一端丢弃（FIFO）并 `warn`，但**最新的单条事件总会保留**——即使它自己就超过上限（此时不打丢弃日志，窗口保持超预算）。 |
 | `rateBudgetPerSecond` | number | `32` | 每设备平滑请求预算（请求/秒）。桌面端共享额度在 ≤2.1.6 是 64 req/s、≥2.1.7 是 256 req/s，且只有新版本才把超限降级为单请求 `RATE_LIMITED`（旧版本直接 close `1011` 终止会话），故按更严格的一代取保守值。内容读取（`agent.content.read`）按 8:1 派生独立一档，且**封顶 512/s**（该额度两代一致）。 |
 | `wsTls` | object | — | 每次 `wss` 拨号的**扁平** `tls.connect` 选项（只接受 `rejectUnauthorized` / `ca`），供桌面端位于私有 CA 或自签 TLS 前置之后时由运维提供信任；配对与重连**两个拨号点**共用。**不写入设备档案、不写日志、不进诊断报告。** 整个对象要么按原样生效、要么整体忽略：未知键或不可用值按名 `warn` 后回退 Node 默认信任库（不部分应用）。 |
 

package/dist/index.mjs

@@ -5,7 +5,7 @@ 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 { advertisedEndpointSchema, directEndpointUrl, jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, pairingQrSchema, remoteFailureSchema } from "@cherrystudio/remote-protocol";
+import { advertisedEndpointSchema, directEndpointUrl, jsonRpcNotificationSchema, jsonRpcRequestSchema, jsonRpcResponseSchema, pairingQrSchema, remoteFailureSchema, remoteLimits } from "@cherrystudio/remote-protocol";
 import { peerIdFromString } from "@libp2p/peer-id";
 /**
 * Adds the candidate addresses a peer ADVERTISED that this record does not
@@ -2414,10 +2414,11 @@ 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
-* `EffectiveLimits` cannot arrive here unvetted.
+* Re-projects the four numeric limit keys this report carries, dropping any
+* foreign key that a caller's `limits` object might carry — including
+* `EffectiveLimits`' newer `unackedBytes`, which no diagnostics consumer needs.
+* A whitelist inside the whitelist: the shape is rebuilt field by field rather
+* than spread, so a future addition cannot arrive here unvetted.
 */
 function projectLimits(raw) {
 	if (raw === null || typeof raw !== "object") return {};
@@ -2432,6 +2433,14 @@ function projectLimits(raw) {
 function numberOr(value, fallback) {
 	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+/**
+* A delivery-ledger counter (issue #217): a NON-NEGATIVE finite number, or
+* nothing at all. Absence means "not reported"; a fabricated zero would read as
+* "nothing was delivered", which is a claim this projection has no evidence for.
+*/
+function countEntry(key, raw) {
+	return typeof raw === "number" && Number.isFinite(raw) && raw >= 0 ? { [key]: raw } : {};
+}
 /** The loose-bag view every projection in this module takes of its input. */
 function bag(raw) {
 	return raw ?? {};
@@ -2549,7 +2558,10 @@ function sanitizeDiagnostics(source) {
 					sessionId: typeof cursor["sessionId"] === "string" ? cursor["sessionId"] : sessionId,
 					streamEpoch: typeof cursor["streamEpoch"] === "string" ? cursor["streamEpoch"] : "",
 					seq: typeof cursor["seq"] === "string" ? cursor["seq"] : ""
-				} }
+				} },
+				...countEntry("deliveredBytes", value["deliveredBytes"]),
+				...countEntry("unackedBytes", value["unackedBytes"]),
+				...countEntry("acks", value["acks"])
 			};
 		}),
 		recentErrors: (source.recentErrors ?? []).map((raw) => {
@@ -2610,7 +2622,10 @@ function buildDiagnostics(sources, identity = DEFAULT_IDENTITY) {
 			sessionId: entry.sessionId,
 			deviceId: entry.deviceId,
 			subscriptions: entry.subscriptions,
-			...entry.cursor === void 0 ? {} : { cursor: { ...entry.cursor } }
+			...entry.cursor === void 0 ? {} : { cursor: { ...entry.cursor } },
+			...entry.deliveredBytes === void 0 ? {} : { deliveredBytes: entry.deliveredBytes },
+			...entry.unackedBytes === void 0 ? {} : { unackedBytes: entry.unackedBytes },
+			...entry.acks === void 0 ? {} : { acks: entry.acks }
 		});
 	} catch {}
 	let recentErrors = [];
@@ -3379,6 +3394,29 @@ var DeviceConnection = class {
 	#pendingPings = /* @__PURE__ */ new Set();
 	#token;
 	#tokenExpiresAt;
+	/**
+	* Hosts whose LAST attempt failed for that ADDRESS's own reason (issue #220).
+	* A pass dials the hosts it has not failed yet FIRST, so a stale candidate
+	* sitting first in `record.hosts` cannot cost its dial timeout on every
+	* reconnect — the rule the official client states as "failed candidates
+	* rotate behind untried addresses across retries, so the round budget cannot
+	* permanently starve a later route"
+	* (`.scratch-csa/docs/references/remote-access/connectivity.md` §Connection
+	* lifetime; the tree is gitignored, and its remote-agent directory is the
+	* same `16e505fe` at app tags v0.5.2 and v0.5.3, so this is not a rule that
+	* arrived with a newer app).
+	*
+	* Demotion is ORDER, never exclusion: with every host marked the list falls
+	* back to record order, so a record whose only address is marked still dials
+	* it. A mark is cleared when that host itself connects, so a repaired address
+	* returns to the front on its own — no expiry timer, no persistence, no
+	* config key. A pairing-level verdict and a cancellation never mark (they are
+	* not this address's fault: the line `isPerHostFailure` draws for the
+	* handshake face, mirrored explicitly in the dial face, where only
+	* `IdentityMismatchError` can arise today), and `close()` keeps the marks
+	* because they describe addresses, not this lifecycle.
+	*/
+	#demotedHosts = /* @__PURE__ */ new Set();
 	#wsOptions;
 	constructor(opts) {
 		this.record = opts.record;
@@ -3613,7 +3651,7 @@ var DeviceConnection = class {
 		this.#setState("connecting");
 		if (this.record.hosts.length === 0) throw new AllHostsUnreachableError(this.record.deviceId, this.record.hosts, /* @__PURE__ */ new Error("the device record has no candidate hosts"));
 		let lastError = /* @__PURE__ */ new Error(`device ${this.record.deviceId}: all candidate hosts unreachable`);
-		for (const host of this.record.hosts) {
+		for (const host of this.#dialOrder()) {
 			if (!this.#running || epoch !== this.#epoch) throw new CancelledError();
 			let link;
 			try {
@@ -3621,16 +3659,20 @@ var DeviceConnection = class {
 				link = await this.#dial(host, port, epoch);
 			} catch (error) {
 				if (error instanceof IdentityMismatchError) throw error;
+				if (error instanceof CancelledError) throw error;
 				lastError = error instanceof Error ? error : new Error(String(error));
+				this.#demotedHosts.add(host);
 				continue;
 			}
 			this.#link = link;
 			try {
 				await this.#handshake(link, epoch);
+				this.#demotedHosts.delete(host);
 				return;
 			} catch (error) {
 				if (error instanceof CancelledError || !this.#running || epoch !== this.#epoch) throw new CancelledError();
 				if (!isPerHostFailure(error)) throw error;
+				this.#demotedHosts.add(host);
 				this.#teardownLink();
 				lastError = error instanceof Error ? error : new Error(String(error));
 				continue;
@@ -3638,6 +3680,24 @@ var DeviceConnection = class {
 		}
 		throw new AllHostsUnreachableError(this.record.deviceId, this.record.hosts, lastError);
 	}
+	/**
+	* The pass's dial order (issue #220): hosts this connection has NOT failed
+	* yet, in record order, then the demoted ones, in record order.
+	*
+	* Record order is preserved INSIDE each half, so an ordinary single-address
+	* record, a fresh record and an all-demoted record all dial exactly the list
+	* the record carries — the demotion can only move an address that failed
+	* behind addresses that did not, and can never drop one.
+	*/
+	#dialOrder() {
+		const hosts = this.record.hosts;
+		if (this.#demotedHosts.size === 0) return hosts;
+		const untried = [];
+		const demoted = [];
+		for (const host of hosts) if (this.#demotedHosts.has(host)) demoted.push(host);
+		else untried.push(host);
+		return [...untried, ...demoted];
+	}
 	async #dial(host, port, epoch) {
 		const ws = new WebSocket(directEndpointUrl({
 			host,
@@ -3704,11 +3764,13 @@ var DeviceConnection = class {
 			if (rpcReason$1(error) === "INVALID_CONNECTION_STATE") throw new ProtocolVersionError(String(error));
 			throw error instanceof Error ? error : new Error(String(error));
 		}
+		const unackedBytes = positive$2(hello.limits?.["unackedBytes"]);
 		this.#limits = {
 			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,
+			...unackedBytes === void 0 ? {} : { unackedBytes },
 			...typeof hello.agentMessageSummariesVersion === "number" ? { messageSummaries: hello.agentMessageSummariesVersion } : {}
 		};
 		link.client.updateMaxInFlight(businessWindowFor(this.#limits.inFlightRequests));
@@ -4716,6 +4778,26 @@ const DEFAULT_CHECKPOINT_MS = 3e5;
 * not a tuning knob.
 */
 const MAX_RECOVERY_ATTEMPTS = 4;
+/**
+* ACK WATERMARK (issue #212). The peer delivers `agent.events` only while the
+* bytes it has sent since our last `agent.subscriptions.ack` stay inside
+* `remoteLimits.unackedBytes`; past that it HOLDS the stream — silently, with
+* the subscription still live — and a held batch can be a run's terminal.
+*
+* This layer used to ack ONLY from `cherry_events`, so a waiter (which by
+* design consumes without acking) parked on a buffer that stopped advancing
+* just under one window: a real 240 s wait answered `timeout` with the finished
+* text, its cursor frozen at 666 events ≈ 262144 bytes.
+*
+* The layer therefore acks what it has ALREADY BUFFERED (the bytes are in
+* memory; acking does not lose them) once a quarter of the peer's window has
+* accumulated. A retry cooldown keeps a refusing peer from turning every batch
+* into a round trip.
+*/
+/** First retry delay after a refused auto-ack; doubles per attempt. */
+const AUTO_ACK_RETRY_MS = 3e3;
+/** Ceiling for the doubling retry, so a permanently refusing peer is quiet. */
+const AUTO_ACK_RETRY_MAX_MS = 3e4;
 function positive$1(value, fallback) {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
 }
@@ -4753,6 +4835,8 @@ var SessionSubscriptions = class {
 	#limit;
 	#perSessionCacheBytes;
 	#checkpointMs;
+	/** Where the peer's window comes from; see {@link SessionSubscriptionsOptions.unackedBytes}. */
+	#unackedSource;
 	#sessions = /* @__PURE__ */ new Map();
 	/**
 	* Insertion order IS the eviction order, and it is SUBSCRIPTION recency, not
@@ -4774,6 +4858,7 @@ var SessionSubscriptions = class {
 		this.#limit = Math.max(1, Math.floor(positive$1(opts.subscriptionsLimit, DEFAULT_SUBSCRIPTIONS_LIMIT)));
 		this.#perSessionCacheBytes = positive$1(opts.perSessionCacheBytes, DEFAULT_PER_SESSION_CACHE_BYTES);
 		this.#checkpointMs = positive$1(opts.checkpointMs, DEFAULT_CHECKPOINT_MS);
+		this.#unackedSource = opts.unackedBytes;
 	}
 	/**
 	* Session ids with a live subscription, LRU-first. Task 10's reconnect
@@ -4816,6 +4901,28 @@ var SessionSubscriptions = class {
 		return this.#sessions.get(sessionId)?.cursor;
 	}
 	/**
+	* The DELIVERY LEDGER of one subscription (issue #217): the payload bytes it
+	* has received since it was installed, how much of that the peer may still
+	* count as un-acknowledged, and how many acks it has taken. Undefined for a
+	* session this layer does not hold — never a fabricated zero.
+	*
+	* Diagnostics is the caller: these three numbers are what turns 「the stream
+	* exceeded the peer's window」 from an extrapolation into a measurement.
+	*
+	* A CLIENT-SIDE ledger, never the peer's: `unackedBytes` is this layer's
+	* model of what the peer may still count (bytes since its last accepted
+	* ack), not a reading of the peer's own window or ack position.
+	*/
+	deliveryOf(sessionId) {
+		const state = this.#sessions.get(sessionId);
+		if (state === void 0) return void 0;
+		return {
+			deliveredBytes: state.deliveredBytes,
+			unackedBytes: state.bytesSinceAck,
+			acks: state.acks
+		};
+	}
+	/**
 	* The session's cache WINDOW START — the retention BOUNDARY of this layer's
 	* cache: the oldest position it still tracks — or undefined when the session
 	* is untracked.
@@ -4873,6 +4980,7 @@ var SessionSubscriptions = class {
 		if (existing !== void 0) {
 			console.info(`[cherry-remote] re-subscribing session ${sessionId} (replacing its live subscription)`);
 			await this.#closeSubscription(existing.subscriptionId);
+			this.#cancelAckRetry(existing);
 			this.#rejectWaiters(existing, /* @__PURE__ */ new Error(`session ${sessionId} re-subscribed`));
 			this.#sessions.delete(sessionId);
 		}
@@ -4948,17 +5056,25 @@ var SessionSubscriptions = class {
 	/**
 	* Advances the peer's view of this session: `agent.subscriptions.ack` with
 	* the delivered cursor. The peer only accepts a cursor inside the window it
-	* actually delivered (an out-of-window ack is its CONFLICT), so this is
-	* called with the cursor a consumer has durably processed.
+	* actually delivered (an out-of-window ack is its CONFLICT).
+	*
+	* Two callers, one contract — "this position is accounted for, keep sending":
+	* `cherry_events` passes the cursor a CONSUMER has processed, and
+	* {@link #maybeAutoAck} passes the BUFFER frontier because the events are
+	* retained here (see that method for why an ack cannot lose replay).
 	*/
 	async ack(sessionId, cursor) {
 		const state = this.#sessions.get(sessionId);
 		if (state === void 0) return;
-		const applied = cursor ?? state.cursor;
+		const requested = cursor === void 0 ? state.cursor : cursor;
+		const applied = Number(requested.seq) > Number(state.cursor.seq) ? requested : state.cursor;
+		const covered = state.bytesSinceAck;
 		await this.#rpc.request("agent.subscriptions.ack", {
 			subscriptionId: state.subscriptionId,
 			cursor: applied
 		});
+		state.bytesSinceAck = Math.max(0, state.bytesSinceAck - covered);
+		state.acks += 1;
 	}
 	/**
 	* Parks a resolver that settles when the session buffer advances past
@@ -5006,6 +5122,7 @@ var SessionSubscriptions = class {
 		this.#closed = true;
 		const ids = [...this.#sessions.values()].map((state) => state.subscriptionId);
 		for (const state of this.#sessions.values()) {
+			this.#cancelAckRetry(state);
 			const error = /* @__PURE__ */ new Error("SessionSubscriptions disposed");
 			for (const waiter of state.waiters.splice(0)) waiter.reject(error);
 		}
@@ -5088,13 +5205,23 @@ var SessionSubscriptions = class {
 	*/
 	#installReplay(sessionId, descriptor) {
 		const previous = this.#sessions.get(sessionId);
-		if (previous !== void 0) this.#rejectWaiters(previous, /* @__PURE__ */ new Error(`session ${sessionId} re-subscribed`));
+		if (previous !== void 0) {
+			this.#cancelAckRetry(previous);
+			this.#rejectWaiters(previous, /* @__PURE__ */ new Error(`session ${sessionId} re-subscribed`));
+		}
 		this.#sessions.delete(sessionId);
 		this.#sessions.set(sessionId, {
 			subscriptionId: descriptor.subscriptionId,
 			cursor: descriptor.highWatermark,
 			buffer: [],
 			bytes: 0,
+			bytesSinceAck: 0,
+			deliveredBytes: 0,
+			acks: 0,
+			ackInFlight: false,
+			ackRetryAt: 0,
+			ackRetryDelay: AUTO_ACK_RETRY_MS,
+			ackRetryTimer: void 0,
 			windowStart: Number(descriptor.highWatermark.seq),
 			evicted: false,
 			waiters: [],
@@ -5174,13 +5301,23 @@ var SessionSubscriptions = class {
 	*/
 	#installCheckpoint(sessionId, descriptor, items) {
 		const previous = this.#sessions.get(sessionId);
-		if (previous !== void 0) this.#rejectWaiters(previous, /* @__PURE__ */ new Error(`session ${sessionId} recovered`));
+		if (previous !== void 0) {
+			this.#cancelAckRetry(previous);
+			this.#rejectWaiters(previous, /* @__PURE__ */ new Error(`session ${sessionId} recovered`));
+		}
 		this.#sessions.delete(sessionId);
 		this.#sessions.set(sessionId, {
 			subscriptionId: descriptor.subscriptionId,
 			cursor: descriptor.checkpoint.cursor,
 			buffer: [],
 			bytes: 0,
+			bytesSinceAck: 0,
+			deliveredBytes: 0,
+			acks: 0,
+			ackInFlight: false,
+			ackRetryAt: 0,
+			ackRetryDelay: AUTO_ACK_RETRY_MS,
+			ackRetryTimer: void 0,
 			windowStart: Number(descriptor.checkpoint.cursor.seq),
 			evicted: false,
 			waiters: [],
@@ -5226,6 +5363,7 @@ var SessionSubscriptions = class {
 		for (const [sessionId, state] of this.#sessions) {
 			if (sessionId === protectedSessionId) continue;
 			console.warn(`[cherry-remote] subscription limit (${this.#limit}) reached; evicting least-recently-used session ${sessionId}`);
+			this.#cancelAckRetry(state);
 			this.#rejectWaiters(state, /* @__PURE__ */ new Error(`session ${sessionId} evicted by LRU`));
 			this.#sessions.delete(sessionId);
 			await this.#closeSubscription(state.subscriptionId);
@@ -5239,7 +5377,9 @@ var SessionSubscriptions = class {
 	}
 	/**
 	* `agent.events`: append to the session buffer, enforce the byte budget by
-	* dropping the OLDEST events (logged), advance the cursor, then wake waiters.
+	* dropping the OLDEST events (logged, and never the last remaining one — see
+	* `#trimToBudget`'s floor, issue #221), advance the cursor, then wake
+	* waiters.
 	*
 	* SEQ MONOTONICITY IS ENFORCED HERE, per (sessionId, streamEpoch). The peer is
 	* supposed to deliver each stream position exactly once and in order, and the
@@ -5307,11 +5447,85 @@ var SessionSubscriptions = class {
 				bytes
 			});
 			state.bytes += bytes;
+			state.bytesSinceAck += bytes;
+			state.deliveredBytes += bytes;
 			state.cursor = cursor;
 			appended += 1;
 		}
 		this.#trimToBudget(sessionId, state);
 		if (appended > 0) this.#wakeWaiters(state);
+		if (appended > 0) this.#maybeAutoAck(sessionId, state);
+	}
+	/**
+	* Sends `agent.subscriptions.ack` once the un-acked bytes approach the peer's
+	* window, so the peer keeps delivering (issue #212).
+	*
+	* WHAT IS BEING ACKED is "everything in this layer's buffer", not "everything
+	* a caller has consumed". That is safe against the pinned peer because an ack
+	* does exactly one thing: it frees FLOW CONTROL — the desktop decrements its
+	* un-acked budget and advances `lastAck` (`agentSubscriptions.ts`). Replay
+	* retention lives on the journal (`replayBytes`/`replayMs`) and is not
+	* touched by an ack, so a `read`/`cherry_events`/re-subscribe from a cursor
+	* below the acked position is still served — by the local buffer here and by
+	* the journal there. The ack's own doc comment states the same contract.
+	*
+	* The ack is fire-and-forget with its failure SURFACED (a refused ack must be
+	* visible, not swallowed). A refusal also ARMS A TIMER: once the peer is
+	* holding at its window no further event arrives, so a retry that waited for
+	* traffic would never fire and the wait would time out exactly as in issue
+	* #212.
+	*/
+	#maybeAutoAck(sessionId, state) {
+		if (state.bytesSinceAck < this.#ackWatermark()) return;
+		if (state.ackInFlight) return;
+		if (Date.now() < state.ackRetryAt) return;
+		state.ackInFlight = true;
+		this.ack(sessionId).then(() => {
+			state.ackRetryDelay = AUTO_ACK_RETRY_MS;
+		}).catch((error) => {
+			const delay = state.ackRetryDelay;
+			state.ackRetryAt = Date.now() + delay;
+			state.ackRetryDelay = Math.min(delay * 2, AUTO_ACK_RETRY_MAX_MS);
+			console.warn(`[cherry-remote] auto-ack for session ${sessionId} failed: ${failureText(error)}`);
+			this.#armAckRetry(sessionId, state, delay);
+		}).finally(() => {
+			state.ackInFlight = false;
+			if (this.#closed || this.#sessions.get(sessionId) !== state) return;
+			this.#maybeAutoAck(sessionId, state);
+		});
+	}
+	/**
+	* Quarter of the peer's window, read from the CURRENT source so a layer that
+	* outlives a reconnect follows the new hello instead of its first answer.
+	* Falls back to the pinned protocol constant when nothing is advertised.
+	*/
+	#ackWatermark() {
+		const source = this.#unackedSource;
+		const advertised = typeof source === "function" ? source() : source;
+		return Math.max(1, Math.floor(positive$1(advertised, remoteLimits.unackedBytes) / 4));
+	}
+	/** Disarms the retry, if any (idempotent; safe on a state being replaced). */
+	#cancelAckRetry(state) {
+		if (state.ackRetryTimer === void 0) return;
+		clearTimeout(state.ackRetryTimer);
+		state.ackRetryTimer = void 0;
+	}
+	/**
+	* One timer-driven retry after a refused ack. At most one is armed per
+	* session; it no-ops when the state it was armed for is no longer current
+	* (a re-subscribe, a checkpoint recovery or `dispose`).
+	*/
+	#armAckRetry(sessionId, state, delayMs) {
+		if (this.#closed) return;
+		if (state.ackRetryTimer !== void 0) return;
+		const timer = setTimeout(() => {
+			state.ackRetryTimer = void 0;
+			if (this.#closed || this.#sessions.get(sessionId) !== state) return;
+			state.ackRetryAt = 0;
+			this.#maybeAutoAck(sessionId, state);
+		}, delayMs);
+		timer.unref?.();
+		state.ackRetryTimer = timer;
 	}
 	/**
 	* `agent.subscriptions.resetRequired`: the peer tore the subscription down
@@ -5330,22 +5544,37 @@ var SessionSubscriptions = class {
 		for (const [sessionId, state] of this.#sessions) {
 			if (state.subscriptionId !== subscriptionId) continue;
 			console.warn(`[cherry-remote] subscription for session ${sessionId} reset by the peer (${String(params["reason"] ?? "unspecified")}); re-subscribe required`);
+			this.#cancelAckRetry(state);
 			this.#rejectWaiters(state, /* @__PURE__ */ new Error(`session ${sessionId} reset by the peer`));
 			this.#sessions.delete(sessionId);
 			return;
 		}
 	}
-	/** Drops the OLDEST buffered events until the session fits its byte budget. */
+	/**
+	* Drops the OLDEST buffered events until the session fits its byte budget.
+	*
+	* The loop stops at ONE remaining event (issue #221): the budget governs the
+	* window's TAIL, never its head. A single event above the budget — only
+	* reachable when `perSessionCacheBytes` is set below one record's size, since
+	* the transport caps a record at 65,536 bytes — used to be evicted too,
+	* leaving an EMPTY window whose `windowStart` had advanced past it: the event
+	* that just happened, the one thing a reader wants, became unreachable and
+	* every read from the baseline answered `cursor-out-of-window` about content
+	* this layer had held a moment earlier. Keeping it is also the honest
+	* reading of `evicted`: nothing was discarded, so the baseline stays a
+	* servable resume point.
+	*/
 	#trimToBudget(sessionId, state) {
 		if (state.bytes <= this.#perSessionCacheBytes) return;
 		let dropped = 0;
-		while (state.bytes > this.#perSessionCacheBytes && state.buffer.length > 0) {
+		while (state.bytes > this.#perSessionCacheBytes && state.buffer.length > 1) {
 			const removed = state.buffer.shift();
 			state.bytes -= removed.bytes;
 			dropped += 1;
 			state.windowStart = Math.max(state.windowStart, Number(removed.cursor.seq));
 			state.evicted = true;
 		}
+		if (dropped === 0) return;
 		console.warn(`[cherry-remote] session ${sessionId} cache exceeded ${this.#perSessionCacheBytes} bytes; dropped ${dropped} oldest event(s)`);
 	}
 	/** Coalesced wake: each parked waiter settles exactly once. */
@@ -9160,8 +9389,9 @@ var CherryToolEngine = class {
 	* dimension and deliberately does NOT settle a wait (Task 13 asserts the two
 	* layers separately).
 	*
-	* Waiters never ack: they consume the projection and leave the peer's view
-	* untouched.
+	* Waiters do not ack what they fold. The subscription LAYER acks its own
+	* buffer on a byte watermark (issue #212) so the peer keeps delivering past
+	* its un-acked window; that ack is about flow control, not consumption.
 	*
 	* A wait can also end because the LINK went away — the plugin was torn down,
 	* the device was unpaired, or the connection closed. That is not a timeout and
@@ -12671,7 +12901,8 @@ function subsFor(deviceId) {
 	const connection = connectionFor(deviceId);
 	const created = new SessionSubscriptions(connection.rpc, {
 		subscriptionsLimit: connection.limits.subscriptions,
-		perSessionCacheBytes: state.perSessionCacheBytes
+		perSessionCacheBytes: state.perSessionCacheBytes,
+		unackedBytes: () => connection.limits.unackedBytes
 	});
 	state.subscriptions.set(deviceId, created);
 	console.info(`[cherry-remote] subscription layer established for ${deviceId} (peer limit ${connection.limits.subscriptions})`);
@@ -12796,11 +13027,13 @@ function assemblyDeps() {
 		}),
 		diagnosticsSessions: () => [...state.subscriptions.entries()].flatMap(([deviceId, layer]) => layer.activeSessions().map((sessionId) => {
 			const cursor = layer.cursorOf(sessionId);
+			const delivery = layer.deliveryOf(sessionId);
 			return {
 				deviceId,
 				sessionId,
 				subscriptions: 1,
-				...cursor === void 0 ? {} : { cursor }
+				...cursor === void 0 ? {} : { cursor },
+				...delivery === void 0 ? {} : delivery
 			};
 		})),
 		diagnosticsErrors: () => [...state.recentErrors],

package/docs/e2e-checklist.md

@@ -137,6 +137,7 @@ schema 已允许 `interrupted`，所以客户端**必须**处理，但当前服
 - [ ] 长回复（>4096 单元）经 `{ref}` 外置，聚合结果仍包含完整文本。
 - [ ] `cherry_read` 能按 messageId 读到该轮消息与 parts。
 - [ ] `wait: false` 立即返回命令回执，随后 `cherry_wait` / `cherry_events` 能续查到同一终态。
+- [ ] 长回答（事件流超过 256 KiB，约 30 小节的一次长输出）时 `wait: true` 仍在终态后立即返回 `completed`；期间每 5 s 采一次 `GET /diagnostics` 的 `sessions[].cursor.seq`，确认它没有停住（修复前会冻结在窗口处，最终报 `timeout`）。
 - [ ] 同 `commandId` 同参重发 → 返回**同一回执**（幂等）；异参重发 → `IDEMPOTENCY_CONFLICT` 透传。
 
 ### C. 交互应答
@@ -337,3 +338,48 @@ A–G 各节要真人 + Electron 端批准，无法被 CI 化；下表只记录
   被测设备是单主机同端口；需要造一条混合端口记录才能走。
 - **#161 `failureText`**：要制造一个 peer 可达的 caught failure（如 ack 失败）才会出现，
   本轮 `recentErrors` 为空。
+
+### 0.2.1（2026-11-01 · DSH profile `web` · 桌面端 ISV-ZYX 2.1.10）
+
+| 项 | 结果 | 观测 |
+| --- | --- | --- |
+| 装机生效 | 通过 | 版本 `0.2.1`；包 mtime `23:19:54` 早于宿主 PID 1 启动 `23:20:24`；装机 `dist/index.mjs`、`dist/index.d.mts`、`lib/client.js`、`locale/zh.json` 与 npm `dsh-cherry-bridge@0.2.1` tarball（shasum `ae7ed02b…`）sha256 全同 |
+| 档案无迁移 | 通过 | `devices.json` 仍是 `schemaVersion: 4`（本轮没有触发任何迁移）；`forgottenHosts` 是**可选键、不升版本**（代码依据：档案校验器与视图），首次 `forget` 后出现在文件里。注：捕获里**没有 forget 之前的档案快照**，所以「之前不在文件里」不算本轮观测 |
+| `GET /cherry-remote/api/devices` 新键 | 通过 | 每台设备多出 `forgottenHosts`（无标记时是空数组 `[]`，不是缺键）；本机设备 `hosts` 两条、`security` / `ports` 各两条 |
+| 忘记一条非末位地址（#185 / #204） | 通过 | `POST …/devices/<id>/forget {"hosts":["172.17.14.36"]}` → 200；同一响应里 `hosts` 少一条、`forgottenHosts` 多一条、`state` 变 `connecting`（驱逐），`security` / `ports` 同步删掉该键；档案已落盘。注：forget 之前的「两条地址」由收尾/live 的原状锚定，捕获的第一条事件就是 forget |
+| **重连后不会学回来** | 通过 | 21 s 后 `state: connected`，`hosts` **仍是单条**（观测）。**推断**：桌面一直在广播两条、学习合并跳过了被标记者 —— 依据是下一行「恢复只摘标记」之后 18 s 地址就自己回来了，中间没有别的写入 |
+| 恢复只摘标记 | 通过 | `POST …/remember` → 200，`forgottenHosts: []` 而 `hosts` **未变**；再 18 s 后 `hosts` 回到两条，`security` / `ports` 里重新出现该键（`ws` / 23333，这两个值是否对端所报见下方「未覆盖」） |
+| 拒绝忘记最后一条 | 通过 | 只剩一条时 `forget` → `400` `{"error":"last-address","message":"… refusing to forget the last dial candidate — the record would have nothing to dial. Keep at least one address."}`；档案**未变**（`hosts` 与标记都保持原样；代码在持久化**之前**抛出） |
+| 驱逐的代价可观测 | 通过 | 四次改动 = 四次重建：`stats.connectionsBuilt` 收尾 **5**，两次改动后读到 **3**（故基线推为 1，`1` 本身没有直接读到）；`connections` / `sockets` 两次读到 1/1（23:25:00 那次没取到 `stats`）；`recentErrors` 恰好 **4** 条 `CONNECTION_OFFLINE`（`device transitioned to offline`，每次驱逐一条，无其他；捕获里第 4 条被截断，`/diagnostics` 现读为 4）；收尾回到原状（两条地址、无标记、`connected`） |
+
+**本轮未覆盖**（**不是通过**）：
+
+- **恢复后的端口 / 协议是否真来自对端**：本环境桌面广播的就是记录级默认（`ws` / 23333），
+  观测无法区分「对端说的」与「默认值」；由 `DeviceStore.learnEndpoints` 与
+  `advertisedEndpoints` 的单测覆盖（每个端点自带 port/scheme）。
+- **设置页那对按钮的点击**：需要能打开宿主的浏览器；本机渲染由 `tests/unit/ui.test.ts`
+  覆盖，地址编辑器打开时两个控件冻结由 `#204m` 覆盖。本轮走的是页面调用的同两条 HTTP 路由。
+- **驱逐时 in-flight 命令丢失**：需要一个正在执行的 command 才会出现，本轮没有。
+
+### 0.2.2（2026-11-03 · DSH profile `web` · 桌面端 ISV-ZYX）
+
+| 项 | 结果 | 观测 |
+| --- | --- | --- |
+| 装机生效 | 通过 | 包版本 `0.2.2`；`dist/index.mjs` mtime `00:13:42` 早于宿主 PID 1 启动 `00:13:54`；装机 `dist/index.mjs`、`dist/index.d.mts`、`lib/client.js`、`locale/zh.json`、`locale/en.json` 与发行 tarball（sha1 `1ac80762…`，等于 registry 的 `dist.shasum`）逐文件 sha256 **全同** |
+| 超窗长回答 `wait: true` 仍返回 `completed`（§B 新增项） | 通过 | 同一会话（`dsh-bridge 2.1.10 smoke`）连发两轮 30 节长回答，会话 `seq` 从 341 推到 **1374**、再从 1374 推到 **2204**；两轮 `cherry_send` 都返回 `status: "completed"` 并带回助手全文。对端提交时刻是 `00:18:05.797` / `00:19:18.597`，而提交后 1.4 s 的首个采样点已经读到终值 1374 / 2204；第三轮的下一次工具调用发生在提交后 6.6 s，故返回延迟的上界是 6.6 s（含 agent 侧一次调度） |
+| 窗口不冻结（§B 新增项） | 通过 | 每 5 s 采一次 `GET …/diagnostics` 的 `sessions[].cursor.seq`：`00:17:32→00:18:07` 为 346→**918**→993→1074→1153→1227→1308→**1374**，`00:18:49→00:19:19` 为 1374→**1854**→1930→1994→2065→2144→**2204**；两段单调推进、终值后保持，**没有任何一段平台期**（修复前同一会话在整个 240 s 等待窗口里冻结在 666，见 v0.2.2 release 正文） |
+
+**本轮未覆盖**（**不是通过**）：
+
+- **字节级的窗口证据**：`GET …/diagnostics` 按设计只带四个数字 limit 键（`projectLimits`
+  的白名单刻意剔掉 `unackedBytes`），也不报 ack 次数，所以「事件流累计 > 262144 B」是
+  **外推**：同一会话修复前的实测是 666 个事件到窗口（≈394 B/event），本轮 1374 / 2204 事件
+  对应约 0.54 / 0.87 MB。要直接测字节，得先给诊断报告加字段。
+- **ack 是否从未失败**：失败只会 `console.warn`，不进 `recentErrors`；本环境的宿主日志不可读
+  （`/proc/1/fd/1` 拒读）。本轮能断言的是「没有出现冻结与告警级停滞」，不是「ack 零失败」。
+- **桌面端版本号**：本轮没有重读（上一轮记录为 2.1.10）；本客户端不从握手读桌面端版本号
+  （`EffectiveLimits` 只有心跳/订阅/分页/并发/未确认字节五个窗口参数加 `messageSummaries`），`/devices`
+  与 `/diagnostics` 也都不带。
+- **`wait: true` 的毫秒级时延**：只有上界，没有工具级计时器。
+- 第二部分其余小节（配对、交互应答、断连恢复、多设备、`/scope`、语言切换）本轮没有重跑：
+  它们不在 0.2.2 的改动面上。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cherry-bridge",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "private": false,
   "packageManager": "npm@10.9.9",