dsh-cherry-bridge 0.1.9 → 0.1.11

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;
@@ -3265,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;
@@ -3291,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);
@@ -4518,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",
@@ -4728,6 +4881,59 @@ const MESSAGE_CACHE_ENTRY_BYTES = 1048576;
 */
 const MESSAGE_CACHE_BYTES_PER_DEVICE = 33554432;
 /**
+* How many command bodies the engine remembers PER DEVICE, keyed by the
+* CALLER-SUPPLIED `commandId` (issues #115, #118).
+*
+* Why a memory exists at all: a command's recovery path is RECEIPT. A reply
+* lost on the wire is answered by re-sending the ORIGINAL body under the
+* original id, and the desktop's ledger replays the recorded outcome. That
+* promise was impossible for `cherry_send`, whose body carries a DERIVED field
+* (`expectedIdleRevision`) that moves with every successful send: the retry
+* quoted a fresh baseline, the body differed from the recorded one, and the peer
+* answered IDEMPOTENCY_CONFLICT — on the one path where the caller cannot tell
+* what already landed. So the engine remembers the EXACT body it emitted, per
+* (device, caller id, method), and a same-id retry replays it verbatim. The
+* same defect had a harder shape in `cherry_respond` / `cherry_cancel` (issue
+* #118): their DERIVED fields were re-derived, and the retry usually met a
+* pre-check (`unknown-interaction`, `no-active-execution`) before the body was
+* ever compared — the memory is consulted before those, which is why it holds
+* the whole issued body rather than a way to rebuild one.
+*
+* What an entry holds is one short body: a session id, the caller's text (at
+* most the protocol's 32,768 characters, pre-validated before it is ever
+* stored), one revision string — or, for respond/cancel, the interaction's
+* staleness triple / the execution to abort, plus the caller-owned arguments
+* the fingerprint compares. 128 is "more than any live retry window needs,
+* small enough to be trivial": a caller retries a handful of command ids around
+* a lost reply, and each is recoverable while it stays in this FIFO.
+* Eviction costs a REQUEST, never correctness — an evicted id has NO entry, so
+* a same-id retry re-derives a fresh baseline. For a SEND the re-derived body
+* reaches the peer, which refuses the differing body exactly as it would
+* without this memory; for a RESPOND or CANCEL the retry usually dies earlier,
+* at the LOCAL pre-checks (`unknown-interaction`, `no-active-execution`,
+* `execution-mismatch`) — the pre-fix failure mode, which names real state.
+*
+* PER DEVICE, like every engine cache: the id is the caller's, but the peer
+* that settled it is not, and a second desktop must never be sent a body minted
+* against the first.
+*
+* INJECTABLE for tests (`commandBodyEntriesPerDevice`), because the production
+* value needs 129 live command ids before it evicts.
+*/
+const COMMAND_BODY_ENTRIES_PER_DEVICE = 128;
+/**
+* The three command methods whose bodies the engine remembers (see
+* {@link COMMAND_BODY_ENTRIES_PER_DEVICE}).
+*
+* Named once, because they are used twice each by design: as the remembered
+* entry's `method`, and as the method the entry is compared against on lookup.
+* Spelling them at both ends is how a lookup could start matching the wrong
+* tool without any type noticing.
+*/
+const SEND_METHOD = "agent.messages.send";
+const RESPOND_METHOD = "agent.interactions.respond";
+const CANCEL_METHOD = "agent.executions.cancel";
+/**
 * EMPTY-PAGE RUN limit for every aggregate walk. The desktop's pinned-list walk
 * legally answers ONE empty page with an advancing cursor (the pin→entity
 * section transition, `{items: [], nextCursor: 'entity:'}`), so a single empty
@@ -4940,6 +5146,79 @@ function unavailableReason(error) {
 */
 const IDEMPOTENCY_HINT = "the peer already recorded this commandId with a different body; regenerate the commandId for a retry whose parameters changed — never reuse an id with a different body (re-send the ORIGINAL body to replay the original receipt).";
 /**
+* The peer's own wording for `IDEMPOTENCY_CONFLICT` (its `agentHandlers` throws
+* exactly this), used when the ENGINE is the one that knows the body differs —
+* a caller-supplied `commandId` it has already emitted with other arguments
+* (issue #115).
+*
+* The refusal is LOCAL because the outcome is already decided: the peer's ledger
+* holds the recorded body, so a forwarded body would come back as this same
+* conflict, one round trip later, at the cost of a wire call that can never
+* succeed. Reusing the sentence keeps ONE vocabulary for one condition; callers
+* (and the existing conflict tests) match on the prefix.
+*/
+const COMMAND_BODY_DIFFERS_MESSAGE = "Command body differs from the recorded command";
+/**
+* The JSON-RPC error code the transport reserves for protocol failures (the
+* server answers every peer-refused request with it). Used for the LOCAL
+* {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal so it is the same currency a
+* forwarded one would have been: a `JsonRpcRequestError` carrying
+* `{reason: 'IDEMPOTENCY_CONFLICT'}`, distinguishable only by the fact that no
+* request was ever sent.
+*
+* A LOCAL twin of the literal `src/rpc/jsonRpcClient.ts` documents in its own
+* `JsonRpcRequestError` docblock: that module exports no code constant, and
+* adding one only to name this number would widen the published surface for it.
+*/
+const JSON_RPC_PROTOCOL_ERROR_CODE = 1e3;
+/**
+* The LOCAL {@link COMMAND_BODY_DIFFERS_MESSAGE} refusal — the peer's own
+* reason and sentence, wrapped with the same hints a forwarded conflict earns,
+* and never sent anywhere.
+*
+* ONE constructor for every command that remembers its body (send, respond,
+* cancel): the caller must not have to learn a second vocabulary for one
+* condition, and a test matches the prefix `Command body differs` whichever
+* tool produced it.
+*/
+function commandBodyDiffers() {
+	const conflict = new JsonRpcRequestError(JSON_RPC_PROTOCOL_ERROR_CODE, COMMAND_BODY_DIFFERS_MESSAGE, {
+		reason: "IDEMPOTENCY_CONFLICT",
+		message: COMMAND_BODY_DIFFERS_MESSAGE
+	});
+	withRateLimitHint(withIdempotencyHint(conflict));
+	return conflict;
+}
+/**
+* DEEP structural equality, for the caller-owned half of a remembered command
+* body (issue #118).
+*
+* `cherry_respond`'s `response.answers` is a RECORD: two callers sending the
+* same answers in a different KEY ORDER are sending the SAME answer, and a
+* plain `!==` (or a JSON string comparison) would refuse the retry as a
+* different body — turning the receipt recovery into a local conflict on the
+* exact shapes it exists for. Arrays stay ORDERED: `questions` is a list, and
+* reordering it really is a different value.
+*
+* Deliberately small: the values compared here are tool arguments decoded from
+* JSON, so only JSON's two container kinds, the primitives, and `undefined`
+* (an omitted optional argument) need to be understood.
+*/
+function sameCommandValue(left, right) {
+	if (left === right) return true;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (!Array.isArray(left) || !Array.isArray(right)) return false;
+		if (left.length !== right.length) return false;
+		return left.every((value, index) => sameCommandValue(value, right[index]));
+	}
+	if (isRecord(left) && isRecord(right)) {
+		const leftKeys = Object.keys(left);
+		if (leftKeys.length !== Object.keys(right).length) return false;
+		return leftKeys.every((key) => Object.hasOwn(right, key) && sameCommandValue(left[key], right[key]));
+	}
+	return false;
+}
+/**
 * Passes a command failure through UNCHANGED, except that `IDEMPOTENCY_CONFLICT`
 * gets {@link IDEMPOTENCY_HINT} appended to its message.
 *
@@ -4957,6 +5236,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;
 }
@@ -5049,14 +5401,37 @@ const CHERRY_TOOL_NAMES = [
 * those tasks add mutating tools without touching the host seam.
 */
 function registerCherryTools(ctx, deps, options = {}) {
+	return registerCherryToolsWithEngine(ctx, deps, options).dispose;
+}
+/**
+* The same registration, with the ENGINE it built handed back.
+*
+* Exists for TESTS: the engine's memory bookkeeping (the remembered command
+* bodies, the bounds they obey) is private to it on purpose, and the only
+* honest way to pin "bounded" and "dropped with the device" is to observe it
+* through this one seam instead of inferring it from retry outcomes that are
+* identical for an evicted entry and for one that never existed.
+*
+* Both this function and `export class CherryToolEngine` are SHIPPED names
+* (`src` is published on purpose, see AGENTS.md → Build facts), so they are a
+* compatibility commitment — which is why this seam is kept minimal.
+*/
+function registerCherryToolsWithEngine(ctx, deps, options = {}) {
 	const tools = ctx.tools;
 	if (tools === void 0) {
 		console.warn("[cherry-remote] ctx.tools is unavailable; the cherry_* tools were not registered");
-		return () => {};
+		return {
+			dispose: () => {},
+			engine: void 0
+		};
 	}
-	const disposers = new CherryToolEngine(deps, options).definitions().map((definition) => tools.register(definition));
-	return () => {
-		for (const dispose of disposers) dispose();
+	const engine = new CherryToolEngine(deps, options);
+	const disposers = engine.definitions().map((definition) => tools.register(definition));
+	return {
+		engine,
+		dispose: () => {
+			for (const dispose of disposers) dispose();
+		}
 	};
 }
 /** One tool declaration, in the exact shape the host registry consumes. */
@@ -5152,6 +5527,12 @@ var CherryToolEngine = class {
 	*/
 	#contentGate;
 	/**
+	* The `maxBytes` one `agent.content.read` slice asks for
+	* ({@link CONTENT_READ_MAX_BYTES} in production; injectable so a test can
+	* reach a walk's second slice, see `CherryToolEngineOptions`).
+	*/
+	#contentReadSliceBytes;
+	/**
 	* The parts pages already walked, keyed `<deviceId>\0<messageId>`.
 	*
 	* WHAT IS HELD is the RESULT of `agent.parts.list` — the raw part records plus
@@ -5218,6 +5599,49 @@ var CherryToolEngine = class {
 	* not pinned by bookkeeping.
 	*/
 	#watchedConnections = /* @__PURE__ */ new WeakSet();
+	/**
+	* The EXACT command body emitted for each (device, caller id, method), so a
+	* lost reply can be recovered by receipt (issues #115, #118).
+	*
+	* Keyed `<deviceId>\0<commandId>`, exactly like every other engine cache. The
+	* value is a {@link RememberedCommand}: the METHOD it was minted for, the
+	* caller-owned FINGERPRINT a retry must match, and the BODY the retry
+	* replays verbatim. The fingerprint is what must MATCH — a same-id call whose
+	* arguments differ is not a retry of this command at all, and is refused
+	* locally rather than sent. The body is what must be REPLAYED, derived
+	* fields included: that is the whole point, because those fields are the ones
+	* a retry cannot re-derive the same way.
+	*
+	* Three tools remember: `agent.messages.send` (the baseline it quoted),
+	* `agent.interactions.respond` (the staleness triple) and
+	* `agent.executions.cancel` (the execution it was told to abort). Two of
+	* them run PRE-CHECKS before composing a body — respond's
+	* `unknown-interaction`, cancel's `no-active-execution`/`execution-mismatch` —
+	* and after a lost reply those pre-checks are usually the first thing the
+	* retry meets, because the first attempt is what SETTLED the interaction and
+	* ENDED the run. So a caller-supplied id is consulted BEFORE any derivation:
+	* a remembered retry is an answer, not a fresh call.
+	*
+	* WHAT IS REMEMBERED: only CALLER-SUPPLIED ids. An auto-generated uuid is a
+	* one-shot identity — nobody can retry it, so an entry for it is pure leak.
+	* The entry is written the moment the command is ISSUED, before the reply is
+	* awaited: a reply lost on the wire must not cost the only copy of the bytes
+	* the peer's ledger will accept.
+	*
+	* Which body an id holds: the LATEST attempt issued for it — the first
+	* attempt, or the self-heal's fresh-uuid retry when one ran. After a heal, a
+	* same-id retry is therefore answered with the peer's conflict, deliberately:
+	* replaying the ledger's rejected receipt would re-run the healed admission
+	* and duplicate the run, and a conflict is the safer failure.
+	*
+	* Bounded FIFO, per device; dropped when the PAIRING is invalidated (unpair,
+	* identity-mismatch) but KEPT across an ordinary reconnect — see
+	* {@link COMMAND_BODY_ENTRIES_PER_DEVICE} and
+	* {@link CherryToolEngine.#forgetDevice}.
+	*/
+	#commandBodies = /* @__PURE__ */ new Map();
+	/** The per-device cap on {@link CherryToolEngine.#commandBodies}. */
+	#commandBodyEntriesPerDevice;
 	constructor(deps, options = {}) {
 		this.#deps = deps;
 		this.#partsSafetyBound = Math.max(1, Math.floor(options.partsSafetyBound ?? DEFAULT_PARTS_SAFETY_BOUND));
@@ -5226,7 +5650,9 @@ var CherryToolEngine = class {
 		this.#cacheEntriesPerDevice = Math.max(1, Math.floor(options.cacheEntriesPerDevice ?? CACHE_ENTRIES_PER_DEVICE));
 		this.#messageCacheEntryBytes = Math.max(1, Math.floor(options.messageCacheEntryBytes ?? MESSAGE_CACHE_ENTRY_BYTES));
 		this.#messageCacheBytesPerDevice = Math.max(1, Math.floor(options.messageCacheBytesPerDevice ?? MESSAGE_CACHE_BYTES_PER_DEVICE));
+		this.#commandBodyEntriesPerDevice = Math.max(1, Math.floor(options.commandBodyEntriesPerDevice ?? COMMAND_BODY_ENTRIES_PER_DEVICE));
 		this.#contentGate = new ContentReadGate(options.contentReadConcurrency ?? DEFAULT_CONTENT_READ_CONCURRENCY);
+		this.#contentReadSliceBytes = Math.max(1, Math.floor(options.contentReadSliceBytes ?? CONTENT_READ_MAX_BYTES));
 	}
 	definitions() {
 		return [
@@ -5789,7 +6215,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. An attachment is reported as METADATA, never as its bytes: a `kind: \"file\"` part, or a legacy `data` part named `file` (the metadata as JSON in `content.text`), comes back as `name`/`mediaType` (plus `byteLength` for the `file` kind) with `content` emptied — or kept verbatim when that record carries a key this projection does not report. 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: {
@@ -5987,11 +6413,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,
@@ -6048,38 +6476,115 @@ var CherryToolEngine = class {
 				releaseSlot?.();
 			}
 		} else text = "";
+		const legacy = this.#legacyAttachment(kind, raw, text);
 		return {
 			partId,
 			kind,
 			revision,
-			content: text,
-			...this.#attachmentFace(kind, raw, content),
+			content: legacy === void 0 ? text : legacy.remainder,
+			...legacy === void 0 ? this.#attachmentFace(kind, raw, content) : this.#attachmentFace(kind, raw, content, legacy.record),
 			...typeof raw["state"] === "string" ? { state: raw["state"] } : {},
 			...typeof raw["toolName"] === "string" ? { toolName: raw["toolName"] } : {},
 			...typeof raw["toolCallId"] === "string" ? { toolCallId: raw["toolCallId"] } : {}
 		};
 	}
 	/**
+	* The ONE place a legacy `data` part is recognised as an attachment: the
+	* structural discriminator, the JSON parse, and the lossless CONTENT rule.
+	*
+	* The legal legacy face is `{kind: 'data', name: 'file', content: {text:
+	* '{\"mediaType\":…,\"filename\":…}'}}` — the metadata SERIALIZED AS JSON in
+	* `content.text`, observed on the wire (2.1.7 desktop, image upload,
+	* 2026-10-22). An OBJECT inside `content` is not producible by a conforming
+	* peer at all: the pinned protocol 0.5.0 types `content` as a strict
+	* `{text}` | `{ref}` union, so the old documentation described a shape no
+	* peer can emit — and the real one was never lifted, which is how an image
+	* upload reached a model as a JSON blob.
+	*
+	* WHY THE NAME IS THE DISCRIMINATOR, and why it is not a heuristic: the
+	* desktop labels every `data` part with its data KIND in `name` — an
+	* attachment is `'file'`, a task event is `'data-compaction-anchor'`, an
+	* error is `'data-error'` — and the protocol types that field as an
+	* `opaqueId`. This lift therefore REQUIRES the label to be the literal
+	* `'file'` rather than ASSUMING every peer sets one: a `data` part that
+	* carries no name reads as no name, is not lifted, and passes through
+	* untouched. Several of those payloads are JSON too, so "the text parses"
+	* proves nothing; `'file'` is the one label that means "this is an
+	* attachment".
+	*
+	* NOTHING IS EVER DEGRADED: a text that does not parse, parses to a
+	* non-record, or carries neither `mediaType` nor `filename` as a string is
+	* not an attachment, and the part passes through COMPLETELY unchanged
+	* (`remainder` is the raw text, no field is lifted) — this runs on every
+	* `data` part of every read, so a throw here would take down the whole
+	* snapshot.
+	*
+	* THE CONTENT RULE: `remainder` is EMPTY when every key of the record is one
+	* this face projects (`mediaType`, `filename`) — the metadata is fully
+	* represented, and a model sees structure rather than a blob. A record
+	* carrying ANY other key keeps its raw text, so a field we do not project is
+	* never silently dropped (lossless by default). That promise is about KEYS: a
+	* key we DO project whose value is not a string (say `mediaType: 123`) is
+	* counted as represented — the key survives — and reports no field, because
+	* this face lifts strings only. Emptied text therefore means "every key was
+	* one of ours", not "every value produced a field".
+	*/
+	#legacyAttachment(kind, raw, text) {
+		if (kind !== "data" || optionalString(raw["name"]) !== "file") return void 0;
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return;
+		}
+		if (!isRecord(parsed)) return void 0;
+		if (optionalString(parsed["filename"]) === void 0 && optionalString(parsed["mediaType"]) === void 0) return;
+		const everythingLifted = Object.keys(parsed).every((key) => key === "mediaType" || key === "filename");
+		return {
+			record: parsed,
+			remainder: everythingLifted ? "" : text
+		};
+	}
+	/**
 	* The descriptive metadata of an attachment part — and deliberately NOT a
 	* way to reach its bytes.
 	*
-	* Two peer generations are covered, because both are inside the verified
-	* range and they disagree about where the metadata lives:
+	* Two legal faces are covered, because both are inside the verified range and
+	* they disagree about where the metadata lives:
 	*
 	*  - **Cherry ≥ 2.1.5** — `{kind: 'file', name, ref}`, ref at the TOP level.
-	*  - **Cherry 2.1.4** — `{kind: 'data', name, content: {mediaType, filename}}`.
+	*  - **legacy** — `{kind: 'data', name: 'file', content: {text: '<JSON>'}}`,
+	*    the metadata as JSON TEXT. {@link CherryToolEngine.#legacyAttachment}
+	*    parses it and passes the record in here.
+	*
+	* A THIRD arm — a `data` part carrying `{mediaType, filename}` as an OBJECT
+	* inside `content` — is schema-ILLEGAL under the pinned protocol (see the
+	* docblock above) and stays as a DEFENSIVE lift for a peer that violates it.
+	* It is not the 2.1.4 projection: that story was wrong, and a misbehaving
+	* peer's parts are not re-validated client-side, so the guarded arm costs
+	* nothing and covers exactly the peer it was written for.
 	*
 	* Only string fields are lifted: a null `filename` (the peer's explicit "no
 	* name") stays absent rather than becoming the string "null". Anything a
 	* caller needs beyond this — the bytes — stays behind `agent.content.read`,
 	* which this plugin does not call for a file part.
-	*/
-	#attachmentFace(kind, raw, content) {
+	*
+	* WHEN A PARSED `metadata` RECORD IS PRESENT IT IS AUTHORITATIVE. A legacy
+	* attachment's record can arrive externalized as `{ref}`, and that ref is the
+	* peer's serialization ENVELOPE, not the attachment's description: its
+	* `mediaType` is the literal `'text/plain'` the envelope is labelled with and
+	* its `byteLength` is the JSON metadata's own byte count. Letting either
+	* outrank the record would report `text/plain` as an image's media type and a
+	* size that is not the file's — so the record wins the media type, and this
+	* face reports NO `byteLength` at all (a legacy `data` part carries none). The
+	* `file` arm is untouched: there the ref IS the file's own description.
+	*/
+	#attachmentFace(kind, raw, content, metadata) {
 		if (kind !== "file" && kind !== "data") return {};
 		const ref = isRecord(raw["ref"]) ? raw["ref"] : isRecord(content["ref"]) ? content["ref"] : {};
-		const name = kind === "file" ? optionalString(raw["name"]) : optionalString(content["filename"]);
-		const mediaType = optionalString(ref["mediaType"]) ?? optionalString(content["mediaType"]);
-		const byteLength = optionalString(ref["byteLength"]);
+		const name = kind === "file" ? optionalString(raw["name"]) : optionalString(metadata?.["filename"]) ?? optionalString(content["filename"]);
+		const mediaType = kind === "data" && metadata !== void 0 ? optionalString(metadata["mediaType"]) ?? optionalString(content["mediaType"]) : optionalString(ref["mediaType"]) ?? optionalString(metadata?.["mediaType"]) ?? optionalString(content["mediaType"]);
+		const byteLength = kind === "file" ? optionalString(ref["byteLength"]) : void 0;
 		return {
 			...name === void 0 ? {} : { name },
 			...mediaType === void 0 ? {} : { mediaType },
@@ -6104,13 +6609,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 —
@@ -6157,7 +6672,7 @@ var CherryToolEngine = class {
 		const declaredBytes = Number(ref["byteLength"]);
 		const refusal = this.#externalizedRefusal(ref);
 		if (refusal !== void 0) throw refusal;
-		const maxSlices = Number.isSafeInteger(declaredBytes) ? Math.max(1, Math.ceil(declaredBytes / CONTENT_READ_MAX_BYTES)) : DEFAULT_CONTENT_SLICE_BOUND;
+		const maxSlices = Number.isSafeInteger(declaredBytes) ? Math.max(1, Math.ceil(declaredBytes / this.#contentReadSliceBytes)) : DEFAULT_CONTENT_SLICE_BOUND;
 		let offset = "0";
 		let sha;
 		let complete = false;
@@ -6170,7 +6685,7 @@ var CherryToolEngine = class {
 				contentId,
 				revision,
 				offset,
-				maxBytes: CONTENT_READ_MAX_BYTES
+				maxBytes: this.#contentReadSliceBytes
 			}, deadline === void 0 ? void 0 : { deadline: deadline.instant });
 			const data = typeof slice["dataBase64"] === "string" ? slice["dataBase64"] : "";
 			const cap = this.#externalizedByteCap;
@@ -6463,11 +6978,29 @@ var CherryToolEngine = class {
 	*/
 	async #admitSend(connection, subscriptions, deviceId, sessionId, request) {
 		const { args, text } = request;
+		const callerId = optionalString(args["commandId"]);
 		const attempt = async (commandId, revisionOverride) => {
-			const expectedIdleRevision = revisionOverride ?? await this.#idleRevision(connection, subscriptions, deviceId, sessionId);
+			const remembered = callerId === void 0 || commandId !== callerId ? void 0 : this.#recallCommandBody(deviceId, callerId);
+			if (remembered !== void 0 && remembered.method !== SEND_METHOD) throw commandBodyDiffers();
+			const rememberedBody = remembered?.body;
+			if (remembered !== void 0 && (rememberedBody?.["sessionId"] !== sessionId || rememberedBody["text"] !== text)) throw commandBodyDiffers();
+			const expectedIdleRevision = optionalString(rememberedBody?.["expectedIdleRevision"]) ?? revisionOverride ?? await this.#idleRevision(connection, subscriptions, deviceId, sessionId);
 			const baselineSeq = this.#newestSeq(subscriptions, sessionId);
+			if (callerId !== void 0) this.#rememberCommandBody(deviceId, callerId, {
+				method: SEND_METHOD,
+				fingerprint: {
+					sessionId,
+					text
+				},
+				body: {
+					commandId,
+					sessionId,
+					text,
+					expectedIdleRevision
+				}
+			});
 			return {
-				receipt: await this.#command(connection, "agent.messages.send", {
+				receipt: await this.#command(connection, SEND_METHOD, {
 					commandId,
 					sessionId,
 					text,
@@ -6718,6 +7251,19 @@ var CherryToolEngine = class {
 						message: "`response` must be {kind:\"answer\", answers:{<question text>: <answer>}}"
 					};
 				}
+				const callerId = optionalString(args["commandId"]);
+				const answer = response === void 0 ? { decision } : { response };
+				const remembered = callerId === void 0 ? void 0 : this.#recallCommandBody(record.deviceId, callerId);
+				if (remembered !== void 0 && remembered.method !== RESPOND_METHOD) throw commandBodyDiffers();
+				if (remembered !== void 0) {
+					const fingerprint = {
+						sessionId,
+						interactionId,
+						...answer
+					};
+					if (!sameCommandValue(remembered.fingerprint, fingerprint)) throw commandBodyDiffers();
+					return this.#command(connection, RESPOND_METHOD, remembered.body);
+				}
 				await this.#ensureSubscription(record.deviceId, sessionId);
 				const subscriptions = this.#deps.subs(record.deviceId);
 				const snapshot = await this.#interactionSnapshot(connection, subscriptions, record.deviceId, sessionId, interactionId);
@@ -6725,15 +7271,25 @@ var CherryToolEngine = class {
 					error: "unknown-interaction",
 					message: `no interaction ${interactionId} is known for session ${sessionId}`
 				};
-				return this.#command(connection, "agent.interactions.respond", {
+				const body = {
 					commandId: this.#commandId(args),
 					sessionId,
 					interactionId,
 					expectedRevision: snapshot.revision,
 					expectedExecutionId: snapshot.executionId,
 					inputDigest: snapshot.inputDigest,
-					...response === void 0 ? { decision } : { response }
+					...answer
+				};
+				if (callerId !== void 0) this.#rememberCommandBody(record.deviceId, callerId, {
+					method: RESPOND_METHOD,
+					fingerprint: {
+						sessionId,
+						interactionId,
+						...answer
+					},
+					body
 				});
+				return this.#command(connection, RESPOND_METHOD, body);
 			}
 		});
 	}
@@ -6773,6 +7329,17 @@ var CherryToolEngine = class {
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
+				const callerId = optionalString(args["commandId"]);
+				const supplied = optionalString(args["expectedExecutionId"]);
+				const remembered = callerId === void 0 ? void 0 : this.#recallCommandBody(record.deviceId, callerId);
+				if (remembered !== void 0 && remembered.method !== CANCEL_METHOD) throw commandBodyDiffers();
+				if (remembered !== void 0) {
+					if (!sameCommandValue(remembered.fingerprint, {
+						sessionId,
+						expectedExecutionId: supplied
+					})) throw commandBodyDiffers();
+					return this.#command(connection, CANCEL_METHOD, remembered.body);
+				}
 				await this.#ensureSubscription(record.deviceId, sessionId);
 				const subscriptions = this.#deps.subs(record.deviceId);
 				const expectedExecutionId = await this.#activeExecutionId(connection, subscriptions, record.deviceId, sessionId);
@@ -6780,18 +7347,26 @@ var CherryToolEngine = class {
 					error: "no-active-execution",
 					message: `session ${sessionId} has no in-flight execution to cancel`
 				};
-				const supplied = optionalString(args["expectedExecutionId"]);
 				if (supplied !== void 0 && supplied !== expectedExecutionId) return {
 					error: "execution-mismatch",
 					expectedExecutionId,
 					supplied,
 					message: `the cached active execution is ${expectedExecutionId}, not ${supplied}; re-read the session before cancelling`
 				};
-				return this.#command(connection, "agent.executions.cancel", {
+				const body = {
 					commandId: this.#commandId(args),
 					sessionId,
 					expectedExecutionId
+				};
+				if (callerId !== void 0) this.#rememberCommandBody(record.deviceId, callerId, {
+					method: CANCEL_METHOD,
+					fingerprint: {
+						sessionId,
+						expectedExecutionId: supplied
+					},
+					body
 				});
+				return this.#command(connection, CANCEL_METHOD, body);
 			}
 		});
 	}
@@ -6882,7 +7457,7 @@ var CherryToolEngine = class {
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
 				const record = selected[0];
-				this.#forgetDevice(record.deviceId);
+				this.#forgetDevice(record.deviceId, { dropCommandBodies: true });
 				await this.#deps.evict(record.deviceId);
 				try {
 					this.#deps.store.remove(record.deviceId);
@@ -6912,18 +7487,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));
 		}
 	}
 	/**
@@ -7150,7 +7725,8 @@ var CherryToolEngine = class {
 	*    the stored credential no longer describes a valid pairing. A transient
 	*    network drop ALSO lands here and clears the caches unnecessarily; that
 	*    is accepted, because the cost is one round trip per session on reuse and
-	*    the alternative is keeping snapshots across an identity change.
+	*    the alternative is keeping snapshots across an identity change. (The
+	*    remembered command BODIES are the one exception: see `#forgetDevice`.)
 	*  - `identity-mismatch` — the peer's pinned key changed: the pairing is over.
 	*
 	* {@link CherryToolEngine.#resolve} installs the watch on every tool call that
@@ -7173,7 +7749,7 @@ var CherryToolEngine = class {
 		this.#watchedConnections.add(connection);
 		watch(deviceId, (state) => {
 			if (state !== "offline" && state !== "identity-mismatch") return;
-			this.#forgetDevice(deviceId);
+			this.#forgetDevice(deviceId, { dropCommandBodies: state === "identity-mismatch" });
 		});
 	}
 	/**
@@ -7185,13 +7761,106 @@ var CherryToolEngine = class {
 	* leaves the archive (`cherry_unpair`), so a re-paired device cannot inherit
 	* the previous pairing's snapshots and a long-lived process does not
 	* accumulate entries for devices that no longer exist.
+	*
+	* The remembered command bodies obey a NARROWER seam than the read caches:
+	* `dropCommandBodies` is passed by the callers that invalidate the PAIRING
+	* (unpair, identity-mismatch), never by an ordinary `offline`. What a body
+	* replays against — the peer's command ledger — survives a reconnect, and the
+	* body is the only local copy of the exact bytes that ledger will accept, so
+	* a link drop that emptied it would cost the recovery itself, where the read
+	* caches merely pay one re-walk.
 	*/
-	#forgetDevice(deviceId) {
+	#forgetDevice(deviceId, options = {}) {
 		const prefix = `${deviceId}\u0000`;
 		for (const key of [...this.#revisionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#revisionCache, key);
 		for (const key of [...this.#executionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#executionCache, key);
 		for (const key of [...this.#interactionCache.keys()]) if (key.startsWith(prefix)) this.#forget(this.#interactionCache, key);
 		for (const key of [...this.#messageCache.keys()]) if (key.startsWith(prefix)) this.#dropCachedMessage(key);
+		if (options.dropCommandBodies === true) {
+			for (const key of [...this.#commandBodies.keys()]) if (key.startsWith(prefix)) this.#forget(this.#commandBodies, key);
+		}
+	}
+	/**
+	* The command remembered for one caller-supplied `commandId`, keyed
+	* `<deviceId>\0<commandId>` — or `undefined` when this device has never
+	* emitted one (a first attempt, or an entry the FIFO evicted).
+	*
+	* The METHOD is the caller's to judge, and it is a THREE-WAY decision, never
+	* a miss:
+	*
+	*  - no entry → a fresh call;
+	*  - an entry under the caller's own method → match the fingerprint, then
+	*    replay or refuse;
+	*  - an entry under a DIFFERENT method → a MISMATCH, refused locally. An id
+	*    minted for `agent.messages.send` is not a respond retry, and collapsing
+	*    that case into "no entry" would send a respond under a send's id and
+	*    let the PEER answer the conflict one round trip later.
+	*/
+	#recallCommandBody(deviceId, commandId) {
+		return this.#commandBodies.get(this.#cacheKey(deviceId, commandId));
+	}
+	/**
+	* TEST SEAM — the remembered bodies, as one `commandId` per device.
+	*
+	* The memory itself is PRIVATE, and stays that way for callers. What a test
+	* needs to assert is its bookkeeping — that the bound evicts the oldest entry
+	* and that {@link CherryToolEngine.#forgetDevice} drops a device's entries —
+	* and neither can be observed through a real retry: a retry of an evicted id
+	* is indistinguishable from a retry of an absent one, because both are refused
+	* locally by the same rule. Keys are rendered WITHOUT the device component so
+	* a test reads ids, not cache internals.
+	*/
+	rememberedCommandIds(deviceId) {
+		const prefix = `${deviceId}${CACHE_KEY_SEPARATOR}`;
+		return [...this.#commandBodies.keys()].filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+	}
+	/**
+	* TEST SEAM — fill the memory the way a long-lived process would: one entry
+	* per id, WITHOUT spending a wire call on each. The bound and the FIFO order
+	* are the engine's own ({@link CherryToolEngine.#rememberCommandBody}), which
+	* is what makes this a test of the real policy rather than of a mock of it.
+	*/
+	rememberCommandBodyForTest(deviceId, commandId) {
+		this.#rememberCommandBody(deviceId, commandId, {
+			method: "agent.messages.send",
+			fingerprint: {
+				sessionId: "session-for-test",
+				text: "text-for-test"
+			},
+			body: {
+				commandId,
+				sessionId: "session-for-test",
+				text: "text-for-test",
+				expectedIdleRevision: "0"
+			}
+		});
+	}
+	/**
+	* Remembers the exact body one caller-supplied `commandId` was ISSUED with,
+	* evicting this device's oldest entry when it is at the bound.
+	*
+	* FIFO, per device: `Map` insertion order IS the policy, the same deliberate
+	* choice the session caches document, and a `set` on an EXISTING key keeps its
+	* position — a refresh is a rewrite, not a use, so the policy stays
+	* insert-order rather than becoming LRU. One line per eviction, naming the
+	* device and the bound only.
+	*/
+	#rememberCommandBody(deviceId, commandId, remembered) {
+		const key = this.#cacheKey(deviceId, commandId);
+		if (!this.#commandBodies.has(key)) {
+			let own = 0;
+			let oldest;
+			for (const candidate of this.#commandBodies.keys()) {
+				if (!candidate.startsWith(`${deviceId}\u0000`)) continue;
+				own += 1;
+				if (oldest === void 0) oldest = candidate;
+			}
+			if (own >= this.#commandBodyEntriesPerDevice && oldest !== void 0) {
+				this.#commandBodies.delete(oldest);
+				console.warn(`[cherry-remote] remembered command bodies for device ${deviceId} reached their ${this.#commandBodyEntriesPerDevice}-commandId bound; evicted the oldest (a retry of that commandId now re-derives its body, and the peer decides whether it replays)`);
+			}
+		}
+		this.#commandBodies.set(key, remembered);
 	}
 	/**
 	* The session's current idle revision, from the SUBSCRIPTION CACHE.