dsh-cherry-bridge 0.1.8 → 0.1.10

package/dist/index.mjs

@@ -1737,11 +1737,11 @@ const CONTRACT_DIFFERENCES = [
 	},
 	{
 		id: "rate-limit-terminates-session",
-		title: "Over-limit rate limiting terminates the whole session (close 1011)",
-		realPeer: "Exceeding the desktop's per-socket budget (64 req/s in the current implementation, a server value with no negotiation channel) terminates the ENTIRE session with close code 1011 — it is not a per-request `RATE_LIMITED` rejection the caller can retry in place.",
-		fakePeer: "The fake closes the session with 1011 once `rateLimitPerSecond` is exceeded, so the client's offline→backoff→reconnect path is exercised rather than a request-level refusal.",
-		schemaAnchor: "remoteLimits + peer close code 1011 (implementation value, not a protocol promise)",
-		checklistStep: "rate-limit-terminates-session: against a real desktop, drive a burst well above the smooth budget and confirm the socket is closed with 1011 (session gone, state offline, backoff restart) rather than a single structured per-request rejection."
+		title: "Over-limit rate limiting is generation-dependent: a whole-session 1011 close (≤2.1.6) or a per-request refusal (≥2.1.7)",
+		realPeer: "Through 2.1.6, exceeding the desktop's per-socket budget (64 req/s shared, 512 req/s content; implementation values with no negotiation channel) terminated the ENTIRE session with close code 1011. From 2.1.7 (PR #21687) the shared allowance is 256 req/s and an over-budget request is answered with ONE structured `RATE_LIMITED` failure carrying `retryAfterMs`, while the session survives.",
+		fakePeer: "The fake models BOTH generations: `rateLimitMode` `close` (the ≤2.1.6 default) closes the session with 1011 once `rateLimitPerSecond` is exceeded, exercising the offline→backoff→reconnect path; `refuse` answers one structured `RATE_LIMITED` failure with `retryAfterMs` and keeps the session, exercising the bounded replay.",
+		schemaAnchor: "remoteLimits + peer close code 1011 (≤2.1.6) / failure data reason RATE_LIMITED + retryAfterMs (≥2.1.7); implementation values, not protocol promises",
+		checklistStep: "rate-limit-terminates-session: on a ≥2.1.7 desktop, raise `rateBudgetPerSecond` (or use an unpaced probe) and drive a burst above the allowance; confirm each over-budget request is refused with `RATE_LIMITED` + `retryAfterMs` while the session stays live, a refused READ succeeds after ONE replay, and a refused COMMAND surfaces as a verdict and is not replayed. On ≤2.1.6, the same burst closes the socket with 1011 (state offline, backoff restart)."
 	},
 	{
 		id: "execution-terminal-no-interrupted",
@@ -2176,18 +2176,21 @@ function buildDiagnostics(sources, identity = DEFAULT_IDENTITY) {
 * This is the SHARED tier: it covers every business RPC EXCEPT the content-read
 * tier below (see {@link DEFAULT_CONTENT_READ_BUDGET_PER_SECOND}).
 *
-* WHY 32: the desktop's own allowance for "other" RPCs is 64/s
-* (`RemoteAccessService.ts:223-225`; the official client paces them at 40/s,
-* `DesktopSession.ts:242-244`), and exceeding the allowance is not a refusal
-* but a whole-session close (1011). Half the peer's line leaves room for the
-* housekeeping traffic that shares the socket (hello/authenticate/ping/refresh
-* bypass pacing by design) and for arrival compression between our admission
-* times and the peer's arrival times.
+* WHY 32: the desktop's allowance for "other" RPCs is 64/s through 2.1.6 and
+* 256/s from 2.1.7 (`RemoteAccessService.ts`; the official client paces them at
+* 40/s, `DesktopSession.ts:36-37`). What an over-budget request does also
+* changed: through 2.1.6 it closes the WHOLE session (1011), while 2.1.7 (PR
+* #21687) refuses that one request (`RATE_LIMITED` + `retryAfterMs`) and keeps
+* the session. The generations cannot be told apart before one answers, so the
+* default is sized for the older, harsher peer: 32 is half of 64 and an eighth
+* of 256, leaving room for the housekeeping traffic that shares the socket
+* (hello/authenticate/ping/refresh bypass pacing by design) and for arrival
+* compression between our admission times and the peer's arrival times.
 *
 * SOURCES (neither is in this repository): the desktop lines are
-* `_research/cherry-studio` @ v2.1.6 (90b234e); the official-client lines are
-* CherryHQ/cherry-studio-app @ main 18329fe (app 0.3.0), read on 2026-10-18 —
-* recorded in `.superpowers/review-v013-r1/context.md`.
+* `_research/cherry-studio` @ v2.1.6 (90b234e) and CherryHQ/cherry-studio @
+* v2.1.7; the official-client lines are CherryHQ/cherry-studio-app @ v0.4.0,
+* both read on 2026-10-22 (issue #102).
 */
 const DEFAULT_RATE_BUDGET_PER_SECOND = 32;
 /**
@@ -2203,9 +2206,10 @@ const DEFAULT_RATE_BUDGET_PER_SECOND = 32;
 * (`RemoteAccessService.ts:223-225`) and the official client issues them at
 * 480/s (`DesktopSession.ts:33-37`). Pacing them with the 32/s shared tier
 * bound a multi-slice walk to ~670 KiB/s and queued it behind unrelated RPCs;
-* 256 is half the peer's own kill line — the same 2× margin the shared tier
-* keeps on 64/s — and lifts the bound to the multi-MiB/s range of the official
-* client while leaving the desktop a session-sized headroom.
+* 256 is half the 512/s content allowance in BOTH desktop generations (the
+* shared-tier allowance changed in 2.1.7; this one did not) and lifts the bound
+* to the multi-MiB/s range of the official client while leaving the desktop a
+* session-sized headroom.
 *
 * NOT a plugin-config key: the two tiers derive from ONE injected shared budget
 * at the ratio below, so an operator who lowers `rateBudgetPerSecond` lowers
@@ -2214,14 +2218,33 @@ const DEFAULT_RATE_BUDGET_PER_SECOND = 32;
 *
 * THE MARGINS ARE A DEFAULT-INJECTION CLAIM: the 2× headroom above holds at
 * the default injection (32/s), where this tier is exactly 256/s. An injected
-* budget consumes BOTH tiers' headroom in proportion — at 64/s the shared tier
-* is at the peer's 64/s line and this tier derives to 512/s, i.e. nominal
-* saturation of both allowances. The limiter's integer gap means the ACHIEVED
-* rate stays below the nominal one in that case (≤ 334/s on this tier, 55.6/s
-* on the shared one; see `SecondWindowRateLimiter` in `connection.ts`), which
-* is margin by accident rather than by design.
+* budget consumes BOTH tiers' headroom up to the point where this tier reaches
+* the PEER'S CEILING — at 64/s the shared tier sits on the ≤2.1.6 line (the
+* harsher generation, where overrun still closes the session) and this tier
+* derives to exactly 512/s, the content allowance BOTH generations share. Above
+* 64/s the clamp holds it at 512/s: `contentBudgetFor` (issue #111) still
+* derives the ratio, then bounds it — because a knob copied from 2.1.7's shared
+* figure (256)
+* would otherwise derive 2,048/s and spend the tier being refused. The
+* limiter's integer gap means the ACHIEVED rate stays below the nominal one in
+* that case (≤ 334/s on this tier, 55.6/s on the shared one; see
+* `SecondWindowRateLimiter` in `connection.ts`), which is margin by accident
+* rather than by design.
 */
 const DEFAULT_CONTENT_READ_BUDGET_PER_SECOND = 256;
+/**
+* The longest a READ may wait for the peer's rate window to clear before its
+* ONE bounded replay (`RATE_LIMITED` + `retryAfterMs`, desktop >= 2.1.7).
+*
+* Why the peer's own window and not a separate budget: the desktop derives
+* `retryAfterMs` from its 1 s accounting window, so a larger value cannot come
+* from the peer, and waiting longer would hold a tool call for no reason. The
+* caller's own deadline (`JsonRpcRequestOptions.deadline`) still clamps it, and
+* a wait answer's `AssemblyDeadline` is what makes a refusal near the budget a
+* `'deadline'` stop rather than an overrun. A COMMAND never takes this wait: its
+* refusal is a verdict on that arrival, and commands are never replayed.
+*/
+const RATE_LIMIT_MAX_WAIT_MS = 1e3;
 /** 2 MiB of event text cached per session (spec §3.5). */
 const DEFAULT_PER_SESSION_CACHE_BYTES = 2097152;
 /**
@@ -2399,6 +2422,29 @@ const SILENCE_FACTOR = 2;
 /** The deliberate local-shutdown face of a disposed client (see the replay path). */
 const DISPOSED_RE = /^JSON-RPC client disposed$/;
 /**
+* The peer's structured over-budget refusal (desktop >= 2.1.7), or undefined.
+*
+* 2.1.7 answers an over-budget request with ONE `RATE_LIMITED` failure carrying
+* `retryAfterMs` and keeps the session; <=2.1.6 instead closed the whole socket
+* with 1011, which is the transport-loss path and never reaches this check.
+*/
+function rateLimitRefusal(error) {
+	if (!(error instanceof JsonRpcRequestError)) return void 0;
+	const data = error.data;
+	if (typeof data !== "object" || data === null) return void 0;
+	return data["reason"] === "RATE_LIMITED" ? error : void 0;
+}
+/**
+* How long a refusal asks the caller to wait, bounded by
+* {@link RATE_LIMIT_MAX_WAIT_MS}. An absent or unusable value is 0: retry at
+* the next pacing slot rather than invent a delay the peer never asked for.
+*/
+function rateLimitWaitMs(refusal) {
+	const raw = refusal.data["retryAfterMs"];
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) return 0;
+	return Math.min(raw, RATE_LIMIT_MAX_WAIT_MS);
+}
+/**
 * The read methods whose transport loss may be replayed automatically.
 *
 * Two entries are DEAD today and are kept deliberately, so a future call site
@@ -2483,9 +2529,9 @@ var SecondWindowRateLimiter = class {
 * Which tier paces `method`. The rule is EXACT-MATCH: `agent.content.read` is
 * the only method on the content tier, and every other method — a command, a
 * list read, a different `agent.*.read` — keeps the shared tier. A prefix or
-* suffix match would silently widen the 256/s tier to methods whose peer-side
-* allowance is the 64/s one, which is a session-killing mistake (close 1011),
-* so a new content-plane method must be named here deliberately.
+* suffix match would silently widen the content tier to methods whose peer-side
+* allowance is the shared one — 64/s through 2.1.6, where exceeding it closes
+* the SESSION (1011) — so a new content-plane method must be named deliberately.
 */
 function classifyRateTier(method) {
 	return method === "agent.content.read" ? "content" : "shared";
@@ -2644,6 +2690,27 @@ function businessWindowFor(reportedInFlightRequests) {
 	return Math.max(1, Math.min(BUSINESS_MAX_IN_FLIGHT, Math.floor(reportedInFlightRequests / 2)));
 }
 /**
+* The desktop's content-read allowance: 512/s, and the SAME in both generations
+* (`RemoteAccessService.ts` counts `agent.content.read` on its own counter,
+* 512 in v2.1.6 and v2.1.7 alike; only the shared line moved, 64 ⇒ 256).
+*
+* A CEILING on the derived tier, not a third knob. The 8 : 1 ratio exists so an
+* operator who LOWERS the shared budget lowers both tiers; upward, the ratio
+* would spend headroom the peer does not have — `rateBudgetPerSecond: 256`
+* (2.1.7's SHARED figure, an easy number to copy) derives 2,048/s, which the
+* limiter's 1 ms gap compresses to ~1,000/s against this allowance, so roughly
+* every other content read is refused. On >=2.1.7 each refusal costs up to a
+* second plus one replay and a second refusal fails the whole read; on <=2.1.6
+* an overrun closes the SESSION (1011). Because this line is
+* generation-INDEPENDENT, bounding it needs no generation detection — the one
+* bound in this file that does not.
+*
+* 512 is the ceiling and 333/s is what the limiter then ACHIEVES from it
+* (`(1,000 + 150) / 512` ceils to a 3 ms gap), so the saturated tier still
+* keeps a 1.5x margin on arrival times.
+*/
+const CONTENT_BUDGET_CEILING_PER_SECOND = 512;
+/**
 * The content-read tier's budget for a given SHARED budget.
 *
 * ONE injected knob, two tiers: an operator who lowers `rateBudgetPerSecond`
@@ -2651,9 +2718,19 @@ function businessWindowFor(reportedInFlightRequests) {
 * them rather than staying pinned at 256 while the shared tier shrinks. An
 * absent injection is the production default (which yields exactly
 * `DEFAULT_CONTENT_READ_BUDGET_PER_SECOND`).
+*
+* Upward the ratio stops at {@link CONTENT_BUDGET_CEILING_PER_SECOND}: past a
+* shared budget of 64 the derived value would exceed an allowance that never
+* changed, so it is clamped instead of trying to pace past it.
+*
+* Exported for `tests/unit/contentBudgetCeiling.test.ts`, the same reason
+* `reconnectWait` is: the ceiling is a property of this mapping, and asserting
+* it through the limiter's timing would be a slower, flakier version of the
+* same claim.
 */
 function contentBudgetFor(sharedBudgetPerSecond) {
-	return Math.ceil((sharedBudgetPerSecond ?? 32) * 8);
+	const derived = Math.ceil((sharedBudgetPerSecond ?? 32) * 8);
+	return Math.min(CONTENT_BUDGET_CEILING_PER_SECOND, derived);
 }
 function defer() {
 	let resolve;
@@ -2695,6 +2772,13 @@ var DeviceConnection = class {
 	#transportRetryWaitMs;
 	#stateListeners = /* @__PURE__ */ new Set();
 	/**
+	* Callers parked in {@link waitForSettled}. Separate from the state listeners
+	* because their lifetime is ONE wait: a listener stays for the lifecycle, a
+	* settle waiter removes itself the moment it is answered (or times out), and
+	* mixing them would leave every answered wait in the multicast set.
+	*/
+	#settleWaiters = /* @__PURE__ */ new Set();
+	/**
 	* Waits parked inside `#awaitReconnect`. close() drains them: a shutdown has
 	* no reconnect to wait for, and — the case that matters — a close() followed
 	* by a fresh connect() must not let an OLD lifecycle's replay ride the new
@@ -2819,6 +2903,46 @@ var DeviceConnection = class {
 		this.#stateListeners.add(cb);
 	}
 	/**
+	* Waits for an attempt that is ALREADY IN FLIGHT to settle, bounded by
+	* `timeoutMs`, and answers with the state it ends on.
+	*
+	* The only state this waits on is `connecting`: an attempt is running, and
+	* its outcome is what the caller asked about. `connected` is answered at
+	* once, and so are `offline` (parked in backoff), `disabled` and
+	* `identity-mismatch` — no wait can change those, and waiting on them would
+	* merely delay the caller's answer by the whole bound. `offline` is the
+	* common case for a genuinely powered-off desktop, so it is the one that
+	* matters: the tools stay fail-fast there.
+	*
+	* This NEVER starts an attempt — it observes one the pool already started.
+	* That is the line the tool face has always drawn (a tool must not dial); the
+	* wait only stops the tool from calling a live dial a failure.
+	*
+	* The bound expiring is not an error: the current state (`connecting`) is
+	* returned, and the caller judges it exactly as it would have without the
+	* wait.
+	*/
+	async waitForSettled(timeoutMs) {
+		if (this.#state !== "connecting" || timeoutMs <= 0) return this.#state;
+		return new Promise((resolve) => {
+			let settled = false;
+			let timer;
+			const finish = (state) => {
+				if (settled) return;
+				settled = true;
+				if (timer !== void 0) clearTimeout(timer);
+				this.#settleWaiters.delete(onState);
+				resolve(state);
+			};
+			const onState = (state) => {
+				if (state !== "connecting") finish(state);
+			};
+			timer = setTimeout(() => finish(this.#state), timeoutMs);
+			this.#settleWaiters.add(onState);
+			if (this.#state !== "connecting") finish(this.#state);
+		});
+	}
+	/**
 	* Starts (or joins) the supervised lifecycle. Resolves once this cycle
 	* reaches `connected`; rejects with the cycle's failure. Transient
 	* failures keep being retried in the background by the backoff loop even
@@ -3218,6 +3342,8 @@ var DeviceConnection = class {
 		try {
 			return await link.client.request(method, params, opts);
 		} catch (error) {
+			const refusal = rateLimitRefusal(error);
+			if (refusal !== void 0) return await this.#replayAfterRateLimit(refusal, method, params, opts);
 			if (!this.#isTransportLoss(error)) throw error;
 			const lost = new TransportLostError(this.record.deviceId, "connected", method, { cause: error });
 			if (!RETRYABLE_READ_METHODS.has(method) || !this.#running) throw lost;
@@ -3244,6 +3370,51 @@ var DeviceConnection = class {
 			}
 		}
 	}
+	/**
+	* ONE bounded replay for a READ the peer refused because the socket is over
+	* its rate window.
+	*
+	* 2.1.7 answers that request with a structured `RATE_LIMITED` failure and a
+	* `retryAfterMs` instead of closing the session (see `rateLimitRefusal`), so
+	* the caller no longer learns it was throttled by losing its connection:
+	* without this, a transient refusal became a failed tool call whose part text
+	* the projection would even degrade.
+	*
+	* The shape mirrors the transport-loss replay, for the same reasons:
+	*
+	*  - only a READ is replayed (a command's refusal is a verdict on that
+	*    arrival, and commands are never replayed — receipts recover them);
+	*  - the wait is charged to the caller's deadline and never extends it, so a
+	*    wait answer's budget turns a refusal near its bound into a `'deadline'`
+	*    stop instead of an overrun;
+	*  - the replay takes a FRESH pacing admission: it is a new arrival at the
+	*    peer, and skipping the admission would replay into the same full window.
+	*
+	* A SECOND refusal is a real failure and propagates as itself (the fresh
+	* `retryAfterMs` is the more useful one); a link lost under the replay is
+	* reported as the classified `TransportLostError`, never as bare text.
+	*/
+	async #replayAfterRateLimit(refusal, method, params, opts) {
+		if (!RETRYABLE_READ_METHODS.has(method) || !this.#running) throw refusal;
+		const remaining = this.#remainingMs(opts);
+		if (remaining !== void 0 && remaining <= 0) throw new RpcDeadlineExceededError(this.record.deviceId, method);
+		const requested = rateLimitWaitMs(refusal);
+		const waitMs = Math.min(requested, remaining ?? Number.POSITIVE_INFINITY);
+		const deadlineSpent = remaining !== void 0 && requested >= remaining;
+		if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
+		if (!this.#running || this.#state !== "connected") throw refusal;
+		if (deadlineSpent || this.#deadlinePassed(opts)) throw new RpcDeadlineExceededError(this.record.deviceId, method);
+		await this.#limiter.acquire(method);
+		const link = this.#link;
+		if (!this.#running || this.#state !== "connected" || link === void 0) throw refusal;
+		if (this.#deadlinePassed(opts)) throw new RpcDeadlineExceededError(this.record.deviceId, method);
+		try {
+			return await link.client.request(method, params, opts);
+		} catch (error) {
+			if (this.#isTransportLoss(error)) throw new TransportLostError(this.record.deviceId, "connected", method, { cause: error });
+			throw error;
+		}
+	}
 	/** Whether a rejection is the dead channel, as opposed to a peer's own answer. */
 	#isTransportLoss(error) {
 		return error instanceof Error && !(error instanceof JsonRpcRequestError) && isChannelClosedError(error);
@@ -3308,6 +3479,11 @@ var DeviceConnection = class {
 		} catch (error) {
 			console.warn(`[cherry-remote] state listener threw for ${this.record.deviceId}`, error);
 		}
+		for (const cb of [...this.#settleWaiters]) try {
+			cb(next);
+		} catch (error) {
+			console.warn(`[cherry-remote] settle waiter threw for ${this.record.deviceId}`, error);
+		}
 	}
 };
 //#endregion
@@ -4466,6 +4642,35 @@ var ContentReadGate = class {
 };
 //#endregion
 //#region src/tools.ts
+/** `provider_unavailable`-shaped: lowercase words separated by underscores. */
+const REASON_CODE_SHAPE = /^[a-z][a-z0-9_]{1,63}$/;
+/**
+* Projects the wire's `failure` object (present on `status: 'error'` messages)
+* into {@link CherryReadFailure}, or `undefined` when there is none.
+*
+* Deliberately tolerant of a malformed payload: a peer that sends
+* `failure: { retryable: false }` with no nested record still yields a usable
+* verdict (`reasonCode: 'unknown'`, empty message) instead of failing the whole
+* read — the message's TEXT is already in hand, and losing it over a metadata
+* field would trade the content for the annotation. A degenerate object
+* (`{}`, `[]`) projects the same way: the peer DID attach a verdict, just an
+* empty one, and saying so is more honest than reporting "no verdict". Only an
+* ABSENT or non-object `failure` yields `undefined`.
+*/
+function projectMessageFailure(raw) {
+	const failure = raw["failure"];
+	if (typeof failure !== "object" || failure === null) return void 0;
+	const record = failure;
+	const nested = record["failure"];
+	const rawReason = (typeof nested === "object" && nested !== null ? nested : {})["reasonCode"];
+	const reasonCode = typeof rawReason === "string" && REASON_CODE_SHAPE.test(rawReason) ? rawReason : "unknown";
+	const rawMessage = record["message"];
+	return {
+		reasonCode,
+		retryable: record["retryable"] === true,
+		message: truncateErrorMessage(typeof rawMessage === "string" ? rawMessage : "")
+	};
+}
 /** The four terminal execution statuses the waiter predicate covers. */
 const TERMINAL_EXECUTION_STATUSES = [
 	"completed",
@@ -4905,6 +5110,79 @@ function withIdempotencyHint(error) {
 	error.message = `${error.message} — ${IDEMPOTENCY_HINT}`;
 	return error;
 }
+/**
+* The phrase this hint leaves behind, so applying it twice reads once. A phrase
+* from the ADVICE rather than the advice itself, because the wait clause varies
+* with the peer's `retryAfterMs`; matching the peer's own text would match every
+* rate-limit refusal, hinted or not.
+*/
+const RATE_LIMIT_HINT_MARK = "refuses BEFORE dispatch";
+/**
+* How long a refused COMMAND was asked to wait, or undefined when the peer sent
+* nothing a caller can act on.
+*
+* `<= 0` counts as absent rather than "retry immediately": a zero delay is
+* noise in an error message, and the desktop clamps its own value to `>= 1`
+* (`RemoteAccessService.ts`). CEILED so a fractional remainder is never
+* reported as a delay shorter than the one the peer asked for.
+*/
+function rateLimitedWaitMs(error) {
+	if (!(error instanceof JsonRpcRequestError)) return void 0;
+	const data = error.data;
+	if (!isRecord(data)) return void 0;
+	const raw = data["retryAfterMs"];
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return void 0;
+	return Math.ceil(raw);
+}
+/**
+* The recovery advice appended to a command's `RATE_LIMITED` refusal (desktop
+* >= 2.1.7; see the transport-loss section of `connection.ts`), issue #109.
+*
+* Two facts decide the retry and NEITHER survives the tool boundary on its own:
+*
+*  - **THIS attempt was not applied.** The desktop refuses BEFORE dispatch — its
+*    gateway calls `remote.rpc.refuse(input, …)` INSTEAD of `receive(input)` —
+*    so, unlike a reply lost on a dead link, this is a certain non-outcome.
+*    That is what makes a retry safe, and it is why the SAME `commandId` may be
+*    reused: nothing reached the peer's command ledger, so no
+*    `IDEMPOTENCY_CONFLICT` is waiting for the retry. The sentence says THIS
+*    attempt, not "the command", because an earlier attempt under the same
+*    `commandId` may itself have lost its reply after dispatch: the retry advice
+*    is right in that sequence too (the ledger replays the original receipt),
+*    but "never landed" would be a claim about a run this error knows nothing
+*    of.
+*  - **How long the peer asked us to wait** — `retryAfterMs`, derived from its
+*    own 1 s window and already on the error we are holding. The wait clause
+*    comes BEFORE the retry blessing, so a skimming reader cannot take "safe to
+*    retry" and act on it without waiting.
+*
+* The cause is named because at the DEFAULT pacing this refusal is unreachable:
+* the desktop's counter is per SOCKET (locals inside its `run()` loop, one per
+* accepted connection) and we pace 32/s shared / 256/s content against its
+* 64-or-256/s shared and 512/s content lines. Seeing one at all therefore
+* normally means the configured budget is above the peer's allowance — the knob
+* to look at, not a transient blip — and a caller told to "retry later" without
+* that pointer would keep retrying into the same wall. Only the 256/s figure is
+* quoted: this refusal exists only from 2.1.7, so the older 64/s line cannot be
+* the one an operator has to compare against.
+*
+* Like {@link withIdempotencyHint} this only ever EXTENDS `message`: the reason,
+* the `data` and the `JsonRpcRequestError` identity are the peer's, and one
+* command is still never replayed (the advice is for the CALLER's retry).
+*/
+function withRateLimitHint(error) {
+	if (!(error instanceof Error)) return error;
+	if (failureReason(error) !== "RATE_LIMITED") return error;
+	if (error.message.includes(RATE_LIMIT_HINT_MARK)) return error;
+	const waitMs = rateLimitedWaitMs(error);
+	const advice = [
+		"this attempt was not applied: the desktop refuses BEFORE dispatch, so nothing reached its command ledger",
+		waitMs === void 0 ? "A retry is safe, and it may reuse the SAME commandId" : `Wait about ${waitMs} ms first (the peer's retryAfterMs); a retry is then safe, and it may reuse the SAME commandId`,
+		"The default budget (32/s) does not come close to the desktop's allowance, so a refusal normally means `rateBudgetPerSecond` was raised too far (2.1.7+ allows 256/s shared)"
+	];
+	error.message = `${error.message} — ${advice.join(". ")}.`;
+	return error;
+}
 function optionalString(value) {
 	return typeof value === "string" && value !== "" ? value : void 0;
 }
@@ -5200,8 +5478,12 @@ var CherryToolEngine = class {
 	* ⑤): the candidate list is the answer. A MISS is a verdict too — see
 	* {@link CherryDeviceNotFound} — and it carries the ids the caller could have
 	* meant so the answer stays actionable.
+	*
+	* ASYNC because of the `connecting` wait below: the pool dials on first touch
+	* and on every reconnect, so a tool called in that window used to be refused
+	* for a connection that comes up a moment later (issue #99).
 	*/
-	#resolve(device) {
+	async #resolve(device) {
 		const resolution = this.#deps.store.resolve(device);
 		if ("ambiguous" in resolution) return {
 			error: "ambiguous-device",
@@ -5211,10 +5493,11 @@ var CherryToolEngine = class {
 		if ("notFound" in resolution) return this.#notFoundVerdict(device);
 		const connection = this.#deps.connect(resolution.deviceId);
 		this.#watchConnection(resolution.deviceId, connection);
-		if (connection.state !== "connected") return {
+		const state = connection.state === "connecting" ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? 5e3) : connection.state;
+		if (state !== "connected") return {
 			error: "device-unavailable",
 			device: resolution.deviceId,
-			state: connection.state
+			state
 		};
 		return {
 			record: resolution,
@@ -5250,6 +5533,10 @@ var CherryToolEngine = class {
 	/**
 	* Resolve-or-verdict: every non-`cherry_devices` tool needs a live link.
 	*
+	* `connecting` is waited out inside {@link #resolve} first, so the
+	* `DeviceUnavailableError` below is only ever raised for a state the wait
+	* could not improve on (bounded by `deviceSettleWaitMs`).
+	*
 	* The failure faces are deliberately DIFFERENT (controller ruling ⑤): an
 	* ambiguous selector and a MISS are ANSWERS — the candidate list, or the
 	* known ids, returned in band, because the caller can act on them — while a
@@ -5262,8 +5549,8 @@ var CherryToolEngine = class {
 	* `cherry_devices` does not come through this method — it goes through
 	* {@link #selectRecords}, which returns the verdict in band.
 	*/
-	#requireConnection(device) {
-		const resolved = this.#resolve(device);
+	async #requireConnection(device) {
+		const resolved = await this.#resolve(device);
 		if (!this.#isVerdict(resolved)) return resolved;
 		if (resolved.error === "ambiguous-device") return resolved;
 		if (resolved.error === "not-found") {
@@ -5282,10 +5569,10 @@ var CherryToolEngine = class {
 	* replace it with a weaker, wrong one — a miss under a READ-ONLY archive
 	* would describe a store that still holds a valid token as "no such device".
 	*/
-	#linkOr(device) {
+	async #linkOr(device) {
 		const quarantined = this.#quarantineVerdict();
 		if (quarantined !== void 0) return { verdict: quarantined };
-		const resolved = this.#requireConnection(device);
+		const resolved = await this.#requireConnection(device);
 		if ("error" in resolved) return { verdict: resolved };
 		return { link: resolved };
 	}
@@ -5507,10 +5794,13 @@ var CherryToolEngine = class {
 				const selector = optionalString(args["device"]);
 				const quarantined = this.#quarantineVerdict();
 				if (quarantined !== void 0) return quarantined;
-				if (selector === void 0) return { devices: this.#deps.store.list().map((record) => this.#deviceView(record)) };
+				if (selector === void 0) {
+					const records = this.#deps.store.list();
+					return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) };
+				}
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
-				return { devices: selected.map((record) => this.#deviceView(record)) };
+				return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) };
 			}
 		});
 	}
@@ -5540,7 +5830,9 @@ var CherryToolEngine = class {
 		return [resolution];
 	}
 	/**
-	* One device's view WITHOUT dialing.
+	* One device's view WITHOUT dialing — but after waiting out an attempt that is
+	* already in flight, exactly as {@link #resolve} does, so a cold-start row
+	* does not present a transient `connecting` as the device's answer.
 	*
 	* A disabled record is authoritative: the pooled connection is constructed
 	* with its own `record.enabled` snapshot and reports `disabled` only once
@@ -5548,10 +5840,11 @@ var CherryToolEngine = class {
 	* for a device whose connection was never started. Everything else falls back
 	* to the connection's own CLOSED state set.
 	*/
-	#deviceView(record) {
+	async #deviceView(record) {
 		let state = record.enabled ? "offline" : "disabled";
 		if (record.enabled) try {
-			state = this.#deps.connect(record.deviceId).state;
+			const connection = this.#deps.connect(record.deviceId);
+			state = connection.state === "connecting" ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? 5e3) : connection.state;
 		} catch (error) {
 			console.warn(`[cherry-remote] cherry_devices could not read the connection for ${record.deviceId}`, error);
 		}
@@ -5587,7 +5880,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const binding = {
@@ -5634,7 +5927,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const params = { agentId: requiredString(args, "agentId") };
@@ -5693,7 +5986,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const agentId = optionalString(args["agentId"]);
@@ -5722,7 +6015,7 @@ var CherryToolEngine = class {
 	#readTool() {
 		return defineCherryTool({
 			name: "cherry_read",
-			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. A binary attachment is reported as `kind: \"file\"` with `name`/`mediaType`/`byteLength` and an EMPTY `content` — the bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the stop point can be named — absent when it cannot, e.g. an empty or malformed position, a token past the length ceiling, or no anchor id — and passing it back as `messagesResumeCursor` continues the walk from there (`limit` then bounds how many messages are returned FROM that point). The two token forms are `\"cursor:<peer position>\"` (the walk consumed its whole page window) and `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
+			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. A binary attachment is reported as `kind: \"file\"` with `name`/`mediaType`/`byteLength` and an EMPTY `content` — the bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A failed message (`status: \"error\"`) may carry `failure: {reasonCode, retryable, message}` when the peer sent one — its classification, whether it judged a retry worthwhile, and a bounded summary; the peer's `source` and `context.responseBody` are never projected. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the stop point can be named — absent when it cannot, e.g. an empty or malformed position, a token past the length ceiling, or no anchor id — and passing it back as `messagesResumeCursor` continues the walk from there (`limit` then bounds how many messages are returned FROM that point). The two token forms are `\"cursor:<peer position>\"` (the walk consumed its whole page window) and `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5751,7 +6044,7 @@ var CherryToolEngine = class {
 			},
 			execute: async (args) => {
 				const resume = parseMessageResume(args["messagesResumeCursor"]);
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -5920,11 +6213,13 @@ var CherryToolEngine = class {
 		const partsTruncated = page.truncated ? page.truncationReason ?? "safety-bound" : void 0;
 		const unavailableParts = parts.filter((part) => part.unavailable !== void 0).length;
 		const incomplete = unavailableParts > 0 || partsTruncated !== void 0;
+		const failure = projectMessageFailure(raw);
 		return {
 			messageId,
 			revision,
 			role: String(raw["role"] ?? ""),
 			status: String(raw["status"] ?? ""),
+			...failure === void 0 ? {} : { failure },
 			parts,
 			...partsTruncated === void 0 ? {} : {
 				partsTruncated,
@@ -6037,13 +6332,23 @@ var CherryToolEngine = class {
 	*    back a snapshot that looks complete while containing content the peer
 	*    never certified. That is worse than an error: the caller cannot tell it
 	*    apart from a good read. It keeps failing loudly.
+	*  - **NOT degradable — a RATE LIMIT.** A `RATE_LIMITED` refusal is
+	*    SESSION-wide, not part-specific: the peer refused the arrival, it did not
+	*    fail to serve THIS part. Degrading would hand back a "complete" message
+	*    whose text is empty for a reason the caller could act on (wait and ask
+	*    again) — and if one slice is refused the others will be too, so the
+	*    snapshot would be missing precisely what was requested. The connection
+	*    already waited out `retryAfterMs` and replayed the slice ONCE, so a
+	*    second refusal is a real failure and the whole read fails with it.
 	*
 	* The discriminator is the DIGEST CHECK specifically, which is why
 	* {@link CherryToolEngine.#readExternalized} marks it: matching on message
-	* text would break the moment the wording changed.
+	* text would break the moment the wording changed. The rate-limit arm keys on
+	* the peer's REASON, never on wording.
 	*/
 	#degradableReadFailure(error) {
-		return !(error instanceof ContentIntegrityError);
+		if (error instanceof ContentIntegrityError) return false;
+		return failureReason(error) !== "RATE_LIMITED";
 	}
 	/**
 	* The pre-flight refusal of a `{ref}` whose DECLARED size is above the cap —
@@ -6171,7 +6476,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6234,7 +6539,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const agentId = requiredString(args, "agentId");
@@ -6319,7 +6624,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6443,7 +6748,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6525,7 +6830,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6625,7 +6930,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6702,7 +7007,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6845,18 +7150,18 @@ var CherryToolEngine = class {
 	* subscription failures still reject this call: the two surfaces stay
 	* distinct all the way to the caller (spec §6).
 	*
-	* ONE exception, and it is a HINT rather than a translation: the peer's
+	* TWO exceptions, and both are HINTS rather than translations: the peer's
 	* `IDEMPOTENCY_CONFLICT` — the same `commandId` re-used with a DIFFERENT body
-	* — carries the §6 recovery advice on the rethrown error (see
-	* {@link withIdempotencyHint}). The reason, the `data` and the failure
-	* currency are untouched; only the prose a caller reads grows the actionable
-	* half.
+	* — and its `RATE_LIMITED` refusal (desktop >= 2.1.7) each carry their
+	* recovery advice on the rethrown error (see {@link withIdempotencyHint} /
+	* {@link withRateLimitHint}). The reason, the `data` and the failure currency
+	* are untouched; only the prose a caller reads grows the actionable half.
 	*/
 	async #command(connection, method, params) {
 		try {
 			return await connection.rpc.request(method, params);
 		} catch (error) {
-			throw withIdempotencyHint(error);
+			throw withRateLimitHint(withIdempotencyHint(error));
 		}
 	}
 	/**