dsh-cherry-bridge 0.2.1 → 0.2.2

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.2
 
 # 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.2
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points

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.2
 
 # 安装 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.2
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），

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 {};
@@ -3704,11 +3705,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 +4719,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 +4776,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 +4799,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
@@ -4873,6 +4899,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,13 +4975,18 @@ 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;
 		await this.#rpc.request("agent.subscriptions.ack", {
 			subscriptionId: state.subscriptionId,
 			cursor: applied
@@ -5006,6 +5038,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 +5121,21 @@ 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,
+			ackInFlight: false,
+			ackRetryAt: 0,
+			ackRetryDelay: AUTO_ACK_RETRY_MS,
+			ackRetryTimer: void 0,
 			windowStart: Number(descriptor.highWatermark.seq),
 			evicted: false,
 			waiters: [],
@@ -5174,13 +5215,21 @@ 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,
+			ackInFlight: false,
+			ackRetryAt: 0,
+			ackRetryDelay: AUTO_ACK_RETRY_MS,
+			ackRetryTimer: void 0,
 			windowStart: Number(descriptor.checkpoint.cursor.seq),
 			evicted: false,
 			waiters: [],
@@ -5226,6 +5275,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);
@@ -5307,11 +5357,86 @@ var SessionSubscriptions = class {
 				bytes
 			});
 			state.bytes += bytes;
+			state.bytesSinceAck += 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;
+		const covered = state.bytesSinceAck;
+		this.ack(sessionId).then(() => {
+			state.bytesSinceAck = Math.max(0, state.bytesSinceAck - covered);
+			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,6 +5455,7 @@ 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;
@@ -9160,8 +9286,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 +12798,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})`);

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,25 @@ 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 才会出现，本轮没有。

package/package.json

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

package/src/AGENTS.md

@@ -36,6 +36,7 @@ in [`docs/e2e-checklist.md`](../docs/e2e-checklist.md).
 | `recordBytes` | 65,536 (64 KiB) | one JSON-RPC record above it **aborts the connection** — the transport answers by killing it, so every in-flight request fails |
 | `contentBytes` | 24,576 (24 KiB) | the slice size for one `agent.content.read` |
 | `pageItems` | 100 | the protocol's single-page hard cap; `hello` may negotiate smaller |
+| `unackedBytes` | 262,144 (256 KiB) | the peer HOLDS `agent.events` beyond this much un-acked delivery — terminal included; the layer acks at ¼ of it (hello value, else this) (issue #212) |
 
 Through 2.1.7 the desktop's `pageOf` pages by **count alone** (2.1.8's byte
 budget aside, still count-paged): `pageItems: 100` fat parts produced a record
@@ -187,8 +188,7 @@ projection. An unchanged message costs no repeat `agent.parts.list`
 RPC on send → wait → read rounds, while every read still re-fetches and
 sha256-verifies every `{ref}`'s bytes (a corrupted ref behind an unchanged
 revision fails with `ContentIntegrityError`; `toolsReadCache.test.ts` T1b pins
-this beside the cache). A hit is still not a zero-RPC read: 2.1.6+ externalizes
-every part over 4,096 characters.
+this beside the cache).
 
 - **Entry & key**: the `agent.parts.list` result — `{revision, page}` — keyed
   `<deviceId>\0<messageId>` (device-scoped: a message id is the peer's; two
@@ -654,8 +654,7 @@ one host; whole-replace `hosts` defaults new hosts to
 `ws`/port; a CHANGED `port` re-points EVERY final host, the current value a map
 no-op (the settings UI sends both on save). `GET /devices` reports both maps and
 `forgottenHosts` (addresses and intent, not credentials); tools/diagnostics show
-only `port`. The settings
-page shows the per-host ports only when they differ from the record-level one.
+only `port`.
 TLS trust is operator config (`wsTls`: FLAT `tls.connect` `rejectUnauthorized`/
 `ca` only), forwarded to both dial sites (pool, pairing). `resolveBridgeConfig`
 validates it: unknown key or unusable value warns by FIELD NAME, WHOLE object
@@ -785,9 +784,8 @@ that is not valid URL encoding) · `last-address` 400 (the action would leave no
 to dial; nothing written) · `invalid-device` 400 (the store refused) · `not-found`
 404 (unknown device OR action — also what a QUARANTINED archive answers, its view
 being empty) · `method-not-allowed` 405 (before the body) · `archive-quarantined`
-503 (`{file, corrupt, recovery}`; a damaged archive empties its view and 404s first,
-so this arm only covers a store that refuses after that read — unreachable for the
-shipped store, kept so the arm exists); anything else is the generic 500
+503 (`{file, corrupt, recovery}`; a damaged archive 404s first, so this arm covers
+only a store that refuses after that read); anything else is the generic 500
 `internal-error`.
 
 > The minimal `pairing-progress` frame shape is `{stage, detail?}`; this plugin
@@ -844,9 +842,8 @@ the error message).
   construction**, not by a deny-list. `limits` is re-projected from its four
   keys: a whitelist inside the whitelist.
 - `stats.connectionsBuilt` counts connections built since the last `apply`, not
-  RPC requests — those belong to the transport; a same-named metric would be
-  misread. Counters and the error ring are zeroed on every `apply`: the
-  statistics describe **only** the current assembly.
+  RPC requests (those belong to the transport). Counters and the error ring are
+  zeroed on every `apply`: they describe **only** the current assembly.
 
 ### Logging: levels, identifiers, and what never appears
 
@@ -944,6 +941,4 @@ faces:
   answer is the byte-safe page **clamp**: never ask for a page that cannot fit.
 - Its read path refuses an unusable `byteLength`; we fall back to a slice bound
   plus the cumulative arm.
-- Its read path never replays a read; we replay reads **once** (deliberate
-  enhancement) while both sides keep commands receipt-recovered.
 

package/src/connection.ts

@@ -38,6 +38,17 @@ export interface EffectiveLimits {
   subscriptions: number
   pageItems: number
   inFlightRequests: number
+  /**
+   * The peer's hello-advertised UN-ACKED DELIVERY WINDOW (protocol
+   * `remoteLimits.unackedBytes`). Past this much delivered-but-unacknowledged
+   * traffic the desktop holds its event stream (issue #212), so the
+   * subscription layer sizes its own ack watermark from it.
+   *
+   * ABSENT, never defaulted — same rule as `messageSummaries` below: a hello
+   * that does not carry the key leaves the layer on the pinned protocol
+   * constant rather than on a guess about this peer.
+   */
+  unackedBytes?: number
   /**
    * The peer's hello-advertised `agentMessageSummariesVersion` (issue #105),
    * stored BESIDE the limits because it is re-read by that same handshake.
@@ -1402,11 +1413,13 @@ export class DeviceConnection {
     // reconnect to a peer that no longer advertises the capability (or a
     // downgrade) cannot inherit a stale `messageSummaries` from the previous
     // link — the exact failure mode that would send `partsMode` to a 2.1.7 peer.
+    const unackedBytes = positive(hello.limits?.['unackedBytes'])
     this.#limits = {
       heartbeatMs: positive(hello.heartbeatMs) ?? FALLBACK_LIMITS.heartbeatMs,
       subscriptions: positive(hello.limits?.['subscriptions']) ?? FALLBACK_LIMITS.subscriptions,
       pageItems: positive(hello.limits?.['pageItems']) ?? FALLBACK_LIMITS.pageItems,
       inFlightRequests: positive(hello.limits?.['inFlightRequests']) ?? FALLBACK_LIMITS.inFlightRequests,
+      ...(unackedBytes === undefined ? {} : { unackedBytes }),
       ...(typeof hello.agentMessageSummariesVersion === 'number'
         ? { messageSummaries: hello.agentMessageSummariesVersion }
         : {}),

package/src/diagnostics.ts

@@ -199,7 +199,7 @@ export interface DiagnosticsDevice {
    * `partsMode: 'paged'`.
    *
    * Its own field, not a fifth key inside `limits`: it is a VERSION, not a
-   * count, and `limits` is documented as the four numeric caps. Present only
+   * count, and `limits` here is the four numeric caps this report CARRIES. Present only
    * when a LIVE connection reported it (the same rule as `limits`: the endpoint
    * never dials to find out). ABSENT therefore means "not advertised **or** not
    * connected" — every desktop through 2.1.7, and any device whose link is
@@ -555,10 +555,11 @@ function projectMessageSummaries(raw: unknown): { messageSummaries?: number } {
 }
 
 /**
- * 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: unknown): { limits?: EffectiveLimits } {
   if (raw === null || typeof raw !== 'object') return {}

package/src/index.ts

@@ -664,6 +664,11 @@ function subsFor(deviceId: string): SessionSubscriptions {
   const created = new SessionSubscriptions(connection.rpc, {
     subscriptionsLimit: connection.limits.subscriptions,
     perSessionCacheBytes: state.perSessionCacheBytes,
+    // The peer's OWN un-acked window when hello advertised it (protocol 0.7.0
+    // peers do); absent falls back to the pinned constant inside the layer.
+    // A PROVIDER, not a value: the layer outlives a reconnect, and `limits` is
+    // rebuilt by every hello — a pinned number would freeze the first answer.
+    unackedBytes: () => connection.limits.unackedBytes,
   })
   state.subscriptions.set(deviceId, created)
   // INFO (spec §5 「订阅建立」): the layer is announced with the cap it was

package/src/subscriptions.ts

@@ -2,6 +2,7 @@ import { JsonRpcRequestError } from './rpc/jsonRpcClient.js'
 import type { JsonRpcClient } from './rpc/jsonRpcClient.js'
 import { DEFAULT_PER_SESSION_CACHE_BYTES } from './defaults.js'
 import { failureText } from './text.js'
+import { remoteLimits } from '@cherrystudio/remote-protocol'
 import type { AgentCursor, AgentEvent } from '@cherrystudio/remote-protocol/agent'
 
 /**
@@ -40,6 +41,27 @@ const DEFAULT_CHECKPOINT_MS = 300_000
  */
 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 = 3_000
+/** Ceiling for the doubling retry, so a permanently refusing peer is quiet. */
+const AUTO_ACK_RETRY_MAX_MS = 30_000
+
 export type ReadResult = { events: AgentEvent[]; nextCursor: AgentCursor } | { error: 'cursor-out-of-window' }
 
 export interface SessionSubscriptionsOptions {
@@ -60,6 +82,20 @@ export interface SessionSubscriptionsOptions {
    * default 300_000). Only bounds recovery retries; the peer is authoritative.
    */
   checkpointMs?: number
+  /**
+   * The peer's hello-advertised un-acked delivery window in bytes (protocol
+   * `remoteLimits.unackedBytes`, 262144 in the pinned package). Past that much
+   * delivered-but-unacknowledged traffic the desktop HOLDS its event stream
+   * (issue #212), so the layer acks its buffer at a quarter of this value.
+   *
+   * Omitted falls back to the pinned protocol constant. A peer that does not
+   * advertise the key is treated as the pinned generation — the same
+   * conservative rule the other negotiated limits follow.
+   *
+   * A FUNCTION is read at every watermark check, so a layer that outlives a
+   * reconnect picks up the new hello's value instead of pinning the first one.
+   */
+  unackedBytes?: number | (() => number | undefined)
 }
 
 /** Peer-side subscription phases (mirrors the real peer's internal state). */
@@ -108,6 +144,31 @@ interface SessionState {
   cursor: AgentCursor
   buffer: CachedEvent[]
   bytes: number
+  /**
+   * Bytes appended since the last ack we sent (issue #212). Drives
+   * {@link SessionSubscriptions.#maybeAutoAck}; kept separate from `bytes`,
+   * which measures what the CACHE holds rather than what the peer may still
+   * consider un-acknowledged.
+   */
+  bytesSinceAck: number
+  /** One auto-ack in flight at a time; a second would only duplicate a cursor. */
+  ackInFlight: boolean
+  /** Cooldown after a refused auto-ack (`AUTO_ACK_RETRY_MS`, doubling). */
+  ackRetryAt: number
+  /**
+   * Current retry delay: `AUTO_ACK_RETRY_MS` after the first refusal, doubled
+   * on every further one up to `AUTO_ACK_RETRY_MAX_MS`. Reset on a success, so
+   * a peer that recovers is back to prompt retries.
+   */
+  ackRetryDelay: number
+  /**
+   * The ARMED retry behind `ackRetryAt`. An ack failure is the one case where
+   * no further event will arrive to re-trigger the watermark check — the peer
+   * is holding at its window — so the retry cannot wait for traffic (issue
+   * #212's own failure mode, one ack later). Cleared by {@link #installReplay},
+   * {@link #installCheckpoint} and {@link SessionSubscriptions.dispose}.
+   */
+  ackRetryTimer?: ReturnType<typeof setTimeout>
   /**
    * The oldest stream position this session still TRACKS: the baseline the
    * subscription started from, advanced whenever old events are dropped. It is
@@ -189,6 +250,8 @@ export class SessionSubscriptions {
   readonly #limit: number
   readonly #perSessionCacheBytes: number
   readonly #checkpointMs: number
+  /** Where the peer's window comes from; see {@link SessionSubscriptionsOptions.unackedBytes}. */
+  readonly #unackedSource: number | (() => number | undefined) | undefined
   readonly #sessions = new Map<string, SessionState>()
   /**
    * Insertion order IS the eviction order, and it is SUBSCRIPTION recency, not
@@ -211,6 +274,7 @@ export class SessionSubscriptions {
     this.#limit = Math.max(1, Math.floor(positive(opts.subscriptionsLimit, DEFAULT_SUBSCRIPTIONS_LIMIT)))
     this.#perSessionCacheBytes = positive(opts.perSessionCacheBytes, DEFAULT_PER_SESSION_CACHE_BYTES)
     this.#checkpointMs = positive(opts.checkpointMs, DEFAULT_CHECKPOINT_MS)
+    this.#unackedSource = opts.unackedBytes
   }
 
   /**
@@ -316,6 +380,7 @@ export class SessionSubscriptions {
       // session that will not stay subscribed.
       console.info(`[cherry-remote] re-subscribing session ${sessionId} (replacing its live subscription)`)
       await this.#closeSubscription(existing.subscriptionId)
+      this.#cancelAckRetry(existing)
       this.#rejectWaiters(existing, new Error(`session ${sessionId} re-subscribed`))
       this.#sessions.delete(sessionId)
     }
@@ -424,13 +489,24 @@ export class SessionSubscriptions {
   /**
    * 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: string, cursor?: AgentCursor): Promise<void> {
     const state = this.#sessions.get(sessionId)
     if (state === undefined) return
-    const applied = cursor ?? state.cursor
+    // COALESCED TO THE FRONTIER. The peer keeps ONE `lastAck` per subscription
+    // and refuses a lower position, so an explicit ack carrying what a consumer
+    // has processed would lose a race against the layer's own ack and be
+    // answered CONFLICT — which the caller treats as a broken subscription.
+    // The buffer already holds everything up to `state.cursor`, so acking the
+    // frontier is both safe (an ack only frees flow control) and monotone.
+    const requested = cursor === undefined ? state.cursor : cursor
+    const applied = Number(requested.seq) > Number(state.cursor.seq) ? requested : state.cursor
     await this.#rpc.request('agent.subscriptions.ack', {
       subscriptionId: state.subscriptionId,
       cursor: applied,
@@ -484,6 +560,7 @@ export class SessionSubscriptions {
     this.#closed = true
     const ids = [...this.#sessions.values()].map((state) => state.subscriptionId)
     for (const state of this.#sessions.values()) {
+      this.#cancelAckRetry(state)
       const error = new Error('SessionSubscriptions disposed')
       for (const waiter of state.waiters.splice(0)) waiter.reject(error)
     }
@@ -590,7 +667,10 @@ export class SessionSubscriptions {
    */
   #installReplay(sessionId: string, descriptor: Extract<SubscribeDescriptor, { mode: 'replay' }>): void {
     const previous = this.#sessions.get(sessionId)
-    if (previous !== undefined) this.#rejectWaiters(previous, new Error(`session ${sessionId} re-subscribed`))
+    if (previous !== undefined) {
+      this.#cancelAckRetry(previous)
+      this.#rejectWaiters(previous, new Error(`session ${sessionId} re-subscribed`))
+    }
     this.#sessions.delete(sessionId)
     // Re-inserting moves the session to the MRU end of the Map's order.
     this.#sessions.set(sessionId, {
@@ -598,6 +678,11 @@ export class SessionSubscriptions {
       cursor: descriptor.highWatermark,
       buffer: [],
       bytes: 0,
+      bytesSinceAck: 0,
+      ackInFlight: false,
+      ackRetryAt: 0,
+      ackRetryDelay: AUTO_ACK_RETRY_MS,
+      ackRetryTimer: undefined,
       windowStart: Number(descriptor.highWatermark.seq),
       // A fresh window: nothing has been dropped from it, so the baseline is a
       // position this layer may serve (issue #2).
@@ -723,13 +808,21 @@ export class SessionSubscriptions {
     items: Array<{ kind: string; value: unknown }>,
   ): void {
     const previous = this.#sessions.get(sessionId)
-    if (previous !== undefined) this.#rejectWaiters(previous, new Error(`session ${sessionId} recovered`))
+    if (previous !== undefined) {
+      this.#cancelAckRetry(previous)
+      this.#rejectWaiters(previous, 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,
+      ackInFlight: false,
+      ackRetryAt: 0,
+      ackRetryDelay: AUTO_ACK_RETRY_MS,
+      ackRetryTimer: undefined,
       windowStart: Number(descriptor.checkpoint.cursor.seq),
       // A fresh window: nothing has been dropped from it, so the baseline is a
       // position this layer may serve (issue #2).
@@ -801,6 +894,7 @@ export class SessionSubscriptions {
           `${sessionId}`,
       )
       // The entry is removed outright, so no `live` flag needs clearing.
+      this.#cancelAckRetry(state)
       this.#rejectWaiters(state, new Error(`session ${sessionId} evicted by LRU`))
       this.#sessions.delete(sessionId)
       // AWAITED: the peer must observe the close before the next subscribe.
@@ -907,6 +1001,7 @@ export class SessionSubscriptions {
       const bytes = eventBytes(event)
       state.buffer.push({ cursor, event, bytes })
       state.bytes += bytes
+      state.bytesSinceAck += bytes
       state.cursor = cursor
       appended += 1
     }
@@ -915,6 +1010,106 @@ export class SessionSubscriptions {
     // Waking on a wholly stale batch would make a parked waiter re-judge state
     // that has not moved; only real progress is a wake.
     if (appended > 0) this.#wakeWaiters(state)
+    // The wake comes FIRST: a waiter that can settle from what just arrived
+    // must not wait behind an ack round trip.
+    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: string, state: SessionState): void {
+    if (state.bytesSinceAck < this.#ackWatermark()) return
+    if (state.ackInFlight) return
+    if (Date.now() < state.ackRetryAt) return
+    state.ackInFlight = true
+    // The bytes covered by THIS ack. Events that arrive while it is in flight
+    // stay counted, so the next window starts from the right place.
+    const covered = state.bytesSinceAck
+    void this.ack(sessionId)
+      .then(() => {
+        state.bytesSinceAck = Math.max(0, state.bytesSinceAck - covered)
+        // A peer that answers ack again gets prompt retries next time.
+        state.ackRetryDelay = AUTO_ACK_RETRY_MS
+      })
+      .catch((error: unknown) => {
+        // THIS attempt's delay, then the next one doubles: a peer that refuses
+        // every ack (a wedged controller, a link about to drop) must not log a
+        // line every few seconds for the life of the layer.
+        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)}`)
+        // ARMED HERE, not on the next batch: a peer holding at its window sends
+        // nothing more, so traffic-driven retry is no retry at all.
+        this.#armAckRetry(sessionId, state, delay)
+      })
+      .finally(() => {
+        state.ackInFlight = false
+        // RE-JUDGE: batches can arrive WHILE the ack was in flight (the peer
+        // flushes on the ack, so this is the common case), and those batches
+        // were refused a trigger by `ackInFlight`. Without this second look the
+        // layer could sit with bytes over the watermark and no event left to
+        // trigger it — the peer holding, exactly as in issue #212.
+        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(): number {
+    const source = this.#unackedSource
+    const advertised = typeof source === 'function' ? source() : source
+    return Math.max(1, Math.floor(positive(advertised, remoteLimits.unackedBytes) / 4))
+  }
+
+  /** Disarms the retry, if any (idempotent; safe on a state being replaced). */
+  #cancelAckRetry(state: SessionState): void {
+    if (state.ackRetryTimer === undefined) return
+    clearTimeout(state.ackRetryTimer)
+    state.ackRetryTimer = undefined
+  }
+
+  /**
+   * 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: string, state: SessionState, delayMs: number): void {
+    if (this.#closed) return
+    if (state.ackRetryTimer !== undefined) return
+    const timer = setTimeout(() => {
+      state.ackRetryTimer = undefined
+      if (this.#closed || this.#sessions.get(sessionId) !== state) return
+      // CLEARED HERE, not left to the wall clock: a clock stepped backwards
+      // would otherwise make `#maybeAutoAck` return early and arm nothing — a
+      // retry silently lost while the peer holds, which is #212 again.
+      state.ackRetryAt = 0
+      this.#maybeAutoAck(sessionId, state)
+    }, delayMs)
+    // Never hold the process open on a retry that is only about flow control.
+    timer.unref?.()
+    state.ackRetryTimer = timer
   }
 
   /**
@@ -937,6 +1132,7 @@ export class SessionSubscriptions {
         `[cherry-remote] subscription for session ${sessionId} reset by the peer ` +
           `(${String(params['reason'] ?? 'unspecified')}); re-subscribe required`,
       )
+      this.#cancelAckRetry(state)
       this.#rejectWaiters(state, new Error(`session ${sessionId} reset by the peer`))
       this.#sessions.delete(sessionId)
       return

package/src/tools.ts

@@ -4077,9 +4077,13 @@ export class CherryToolEngine {
           } satisfies CherryCursorOutOfWindow
         }
 
-        // ACK AFTER DELIVERY (controller ruling ④): the peer may only advance
-        // its view once the caller actually holds these events. A failing ack
-        // is logged, never allowed to swallow the delivered events.
+        // ACK AFTER DELIVERY (controller ruling ④): this EXPLICIT ack reports
+        // the position the caller has just been handed. The layer ALSO acks its
+        // own buffer on a byte watermark (issue #212, subscriptions
+        // `#maybeAutoAck`), because the peer holds the stream past its un-acked
+        // window. The peer keeps ONE `lastAck` and refuses a lower position, so
+        // both sites coalesce to the buffer frontier — see `ack()`.
+        // A failing ack is logged, never allowed to swallow the delivered events.
         // A FAILING ACK ALSO RE-ENSURES THE SESSION (v0.1.3 UltraReview P3-3).
         // The ack is the peer's verdict on the SUBSCRIPTION, not on the
         // delivery: a refused ack says the cursor is outside the window this
@@ -6041,8 +6045,9 @@ export class CherryToolEngine {
    * 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