dsh-cherry-bridge 0.2.2 → 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.2
+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.2
+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.2
+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.2
+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

@@ -2433,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 ?? {};
@@ -2550,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) => {
@@ -2611,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 = [];
@@ -3380,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;
@@ -3614,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 {
@@ -3622,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;
@@ -3639,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,
@@ -4842,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.
@@ -4987,10 +5068,13 @@ var SessionSubscriptions = class {
 		if (state === void 0) return;
 		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
@@ -5132,6 +5216,8 @@ var SessionSubscriptions = class {
 			buffer: [],
 			bytes: 0,
 			bytesSinceAck: 0,
+			deliveredBytes: 0,
+			acks: 0,
 			ackInFlight: false,
 			ackRetryAt: 0,
 			ackRetryDelay: AUTO_ACK_RETRY_MS,
@@ -5226,6 +5312,8 @@ var SessionSubscriptions = class {
 			buffer: [],
 			bytes: 0,
 			bytesSinceAck: 0,
+			deliveredBytes: 0,
+			acks: 0,
 			ackInFlight: false,
 			ackRetryAt: 0,
 			ackRetryDelay: AUTO_ACK_RETRY_MS,
@@ -5289,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
@@ -5358,6 +5448,7 @@ var SessionSubscriptions = class {
 			});
 			state.bytes += bytes;
 			state.bytesSinceAck += bytes;
+			state.deliveredBytes += bytes;
 			state.cursor = cursor;
 			appended += 1;
 		}
@@ -5389,9 +5480,7 @@ var SessionSubscriptions = class {
 		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;
@@ -5461,17 +5550,31 @@ var SessionSubscriptions = class {
 			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. */
@@ -12924,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

@@ -360,3 +360,26 @@ A–G 各节要真人 + Electron 端批准，无法被 CI 化；下表只记录
 - **设置页那对按钮的点击**：需要能打开宿主的浏览器；本机渲染由 `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.2",
+  "version": "0.2.3",
   "type": "module",
   "private": false,
   "packageManager": "npm@10.9.9",

package/src/AGENTS.md

@@ -830,10 +830,11 @@ the error message).
 - **May be emitted** (`sanitizeDevice`): `deviceId`, `displayName`, `state`,
   `enabled`, `hosts`, `port`, a **12-char digest** of `desktopIdentity`, the
   hello-negotiated `limits` (`heartbeatMs`/`subscriptions`/`pageItems`/
-  `inFlightRequests` — **only with a live connection**; the endpoint never
-  dials and never wakes a device to fetch fallbacks), `messageSummaries` (the
-  hello capability bit, absent when not advertised), `sessionId` and session
-  cursors (unsubscribed sessions have none), the `stats` counters
+  `inFlightRequests` — **only with a live connection**; it never dials or wakes
+  a device for fallbacks), `messageSummaries` (the
+  hello capability bit, absent when not advertised), `sessionId`, session
+  cursors (none when unsubscribed) and their ledger (`deliveredBytes`/
+  `unackedBytes`/`acks`, #217), the `stats` counters
   (`connections`/`sockets`/`connectionsBuilt`/`subscriptions`), the two resolved
   `config` keys, and error `reason`/`message`.
 - **Never emitted**: `accessToken`, `tokenExpiresAt`, `invitationSecret`, the

package/src/connection.ts

@@ -896,6 +896,29 @@ export class DeviceConnection {
   #pendingPings = new Set<{ nonce: string; sentAt: number }>()
   #token: string | undefined
   #tokenExpiresAt: number | undefined
+  /**
+   * 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.
+   */
+  readonly #demotedHosts = new Set<string>()
 
   readonly #wsOptions: WsDialOptions | undefined
 
@@ -1255,7 +1278,7 @@ export class DeviceConnection {
     }
 
     let lastError: Error = new Error(`device ${this.record.deviceId}: all candidate hosts unreachable`)
-    for (const host of this.record.hosts) {
+    for (const host of this.#dialOrder()) {
       // CANCELLATION GATE, at the top of every candidate. `close()` bumps the
       // epoch and clears `#running`, so either check is enough — both are here
       // because they answer different halves of the same question ("is this
@@ -1279,7 +1302,15 @@ export class DeviceConnection {
         link = await this.#dial(host, port, epoch)
       } catch (error) {
         if (error instanceof IdentityMismatchError) throw error
+        // A cancellation is not this ADDRESS's fault, so it neither marks it
+        // nor continues the pass. UNREACHABLE today — `#dial`'s AbortController
+        // is aborted only through `#teardownLink`, which needs `#link`, and
+        // `#link` is not committed until the dial returns — so this is a
+        // DEFENSIVE arm, not a pinned one: it keeps the rule true if the dial
+        // ever grows a close path, at the cost of two lines and no behaviour.
+        if (error instanceof CancelledError) throw error
         lastError = error instanceof Error ? error : new Error(String(error))
+        this.#demotedHosts.add(host)
         continue
       }
       // Commit the link before the RPC handshake so every failure path below
@@ -1288,6 +1319,8 @@ export class DeviceConnection {
       this.#link = link
       try {
         await this.#handshake(link, epoch)
+        // This address works: any mark an earlier pass left on it is stale.
+        this.#demotedHosts.delete(host)
         return
       } catch (error) {
         // A close() that landed mid-handshake surfaces here as the failure of
@@ -1299,10 +1332,11 @@ export class DeviceConnection {
         // The terminal faces end the pass: they describe the PAIRING, not this
         // address, so trying the next candidate would only repeat them.
         if (!isPerHostFailure(error)) throw error
-        // A channel-level failure (socket dropped mid-handshake) is this
-        // ADDRESS's problem: tear the link down here, since the loop's next
-        // iteration would otherwise overwrite `#link` and leak this socket, and
-        // fall through to the next candidate.
+        // A peer that answers hello/authenticate with a per-address failure is
+        // this ADDRESS's problem too: demote it for the NEXT pass, tear the
+        // link down here (the loop's next iteration would otherwise overwrite
+        // `#link` and leak this socket), and fall through to the next candidate.
+        this.#demotedHosts.add(host)
         this.#teardownLink()
         lastError = error instanceof Error ? error : new Error(String(error))
         continue
@@ -1311,6 +1345,27 @@ export class DeviceConnection {
     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(): readonly string[] {
+    const hosts = this.record.hosts
+    if (this.#demotedHosts.size === 0) return hosts
+    const untried: string[] = []
+    const demoted: string[] = []
+    for (const host of hosts) {
+      if (this.#demotedHosts.has(host)) demoted.push(host)
+      else untried.push(host)
+    }
+    return [...untried, ...demoted]
+  }
+
   async #dial(host: string, port: number, epoch: number): Promise<LiveLink> {
     // (see {@link DeviceConnectionOptions.wsOptions} for TLS trust)
     // The URL comes from the SAME helper the pairing dial uses (issue #126):

package/src/diagnostics.ts

@@ -216,6 +216,16 @@ export interface DiagnosticsSession {
   deviceId: string
   subscriptions: number
   cursor?: { sessionId: string; streamEpoch: string; seq: string }
+  /**
+   * Issue #217: the layer's own delivery ledger for THIS subscription — payload
+   * bytes received since it was installed, how many of them the peer may still
+   * count as un-acknowledged, and successful acks. Absent when the layer does
+   * not report it (an unsubscribed session has no ledger); counts describe the
+   * current subscription, so a re-subscribe restarts them.
+   */
+  deliveredBytes?: number
+  unackedBytes?: number
+  acks?: number
 }
 
 /** One recent error summary (spec §5: 「最近错误摘要」). */
@@ -324,6 +334,10 @@ export interface SubscriptionStat {
   sessionId: string
   subscriptions: number
   cursor?: { sessionId: string; streamEpoch: string; seq: string }
+  /** See {@link DiagnosticsSession.deliveredBytes} (issue #217). */
+  deliveredBytes?: number
+  unackedBytes?: number
+  acks?: number
 }
 
 /**
@@ -577,6 +591,17 @@ function numberOr(value: unknown, fallback: number): number {
   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: 'deliveredBytes' | 'unackedBytes' | 'acks', raw: unknown): Partial<DiagnosticsSession> {
+  return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0
+    ? ({ [key]: raw } as Partial<DiagnosticsSession>)
+    : {}
+}
+
 /** The loose-bag view every projection in this module takes of its input. */
 function bag(raw: unknown): Record<string, unknown> {
   return (raw ?? {}) as Record<string, unknown>
@@ -728,6 +753,9 @@ export function sanitizeDiagnostics(source: {
                 seq: typeof cursor['seq'] === 'string' ? cursor['seq'] : '',
               },
             }),
+        ...countEntry('deliveredBytes', value['deliveredBytes']),
+        ...countEntry('unackedBytes', value['unackedBytes']),
+        ...countEntry('acks', value['acks']),
       }
     }),
     recentErrors: (source.recentErrors ?? []).map((raw): DiagnosticsError => {
@@ -808,6 +836,9 @@ export function buildDiagnostics(
         deviceId: entry.deviceId,
         subscriptions: entry.subscriptions,
         ...(entry.cursor === undefined ? {} : { cursor: { ...entry.cursor } }),
+        ...(entry.deliveredBytes === undefined ? {} : { deliveredBytes: entry.deliveredBytes }),
+        ...(entry.unackedBytes === undefined ? {} : { unackedBytes: entry.unackedBytes }),
+        ...(entry.acks === undefined ? {} : { acks: entry.acks }),
       })
     }
   } catch {

package/src/index.ts

@@ -878,7 +878,16 @@ function assemblyDeps(): CherryHttpDeps & CherryToolsDeps {
       [...state.subscriptions.entries()].flatMap(([deviceId, layer]) =>
         layer.activeSessions().map((sessionId) => {
           const cursor = layer.cursorOf(sessionId)
-          return { deviceId, sessionId, subscriptions: 1, ...(cursor === undefined ? {} : { cursor }) }
+          // The layer's own delivery ledger (issue #217), beside the cursor it
+          // is measured against: both come from ONE session state read.
+          const delivery = layer.deliveryOf(sessionId)
+          return {
+            deviceId,
+            sessionId,
+            subscriptions: 1,
+            ...(cursor === undefined ? {} : { cursor }),
+            ...(delivery === undefined ? {} : delivery),
+          }
         }),
       ),
     diagnosticsErrors: () => [...state.recentErrors],

package/src/subscriptions.ts

@@ -151,6 +151,20 @@ interface SessionState {
    * consider un-acknowledged.
    */
   bytesSinceAck: number
+  /**
+   * Event payload bytes received since this subscription was INSTALLED
+   * (issue #217). Monotone for the life of one subscription — unlike `bytes`
+   * (what the cache still holds) and `bytesSinceAck` (what the peer may still
+   * count) — so 「the stream exceeded the window」 becomes a measurement in
+   * diagnostics instead of an extrapolation from a frozen cursor.
+   */
+  deliveredBytes: number
+  /**
+   * Successful `agent.subscriptions.ack` calls for this subscription (issue
+   * #217). NOT a progress metric: every accepted call counts, including a
+   * repeated explicit ack at the cursor the peer already holds.
+   */
+  acks: 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). */
@@ -320,6 +334,31 @@ export class SessionSubscriptions {
     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: string,
+  ): { deliveredBytes: number; unackedBytes: number; acks: number } | undefined {
+    const state = this.#sessions.get(sessionId)
+    if (state === undefined) return undefined
+    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
@@ -507,10 +546,21 @@ export class SessionSubscriptions {
     // 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
+    // What THIS ack covers: everything received up to the moment it is sent.
+    // Events arriving while it is in flight sit past the applied cursor, so
+    // they stay counted.
+    const covered = state.bytesSinceAck
     await this.#rpc.request('agent.subscriptions.ack', {
       subscriptionId: state.subscriptionId,
       cursor: applied,
     })
+    // COUNTED ONLY AFTER the peer accepted it: a refused ack frees no window,
+    // so a ledger that moved optimistically would claim progress the peer never
+    // granted. The SAME rule governs the byte side, which is why BOTH live here
+    // rather than in the auto-ack caller: an explicit ack frees the window just
+    // as well, and the ledger must not disagree with it.
+    state.bytesSinceAck = Math.max(0, state.bytesSinceAck - covered)
+    state.acks += 1
   }
 
   /**
@@ -679,6 +729,10 @@ export class SessionSubscriptions {
       buffer: [],
       bytes: 0,
       bytesSinceAck: 0,
+      // A fresh subscription owns a fresh ledger (issue #217): the counters
+      // describe THIS install, never a previous one.
+      deliveredBytes: 0,
+      acks: 0,
       ackInFlight: false,
       ackRetryAt: 0,
       ackRetryDelay: AUTO_ACK_RETRY_MS,
@@ -819,6 +873,10 @@ export class SessionSubscriptions {
       buffer: [],
       bytes: 0,
       bytesSinceAck: 0,
+      // A fresh subscription owns a fresh ledger (issue #217): the counters
+      // describe THIS install, never a previous one.
+      deliveredBytes: 0,
+      acks: 0,
       ackInFlight: false,
       ackRetryAt: 0,
       ackRetryDelay: AUTO_ACK_RETRY_MS,
@@ -915,7 +973,9 @@ export class SessionSubscriptions {
 
   /**
    * `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
@@ -1002,6 +1062,7 @@ export class SessionSubscriptions {
       state.buffer.push({ cursor, event, bytes })
       state.bytes += bytes
       state.bytesSinceAck += bytes
+      state.deliveredBytes += bytes
       state.cursor = cursor
       appended += 1
     }
@@ -1039,12 +1100,10 @@ export class SessionSubscriptions {
     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)
+        // The BYTE ledger moved inside `ack()` itself — one place for remarks
+        // and explicit acks alike — so only the retry state is the auto-ack's.
         // A peer that answers ack again gets prompt retries next time.
         state.ackRetryDelay = AUTO_ACK_RETRY_MS
       })
@@ -1139,11 +1198,24 @@ export class SessionSubscriptions {
     }
   }
 
-  /** 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: string, state: SessionState): void {
     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
@@ -1154,6 +1226,10 @@ export class SessionSubscriptions {
       state.windowStart = Math.max(state.windowStart, Number(removed.cursor.seq))
       state.evicted = true
     }
+    if (dropped === 0) return
+    // Only a REAL drop is logged: an over-budget window holding one event has
+    // discarded nothing, and "dropped 0 oldest event(s)" would send an operator
+    // looking for a gap that does not exist.
     console.warn(
       `[cherry-remote] session ${sessionId} cache exceeded ${this.#perSessionCacheBytes} bytes; ` +
         `dropped ${dropped} oldest event(s)`,