dsh-cherry-bridge 0.1.9 → 0.1.11

package/src/tools.ts

@@ -12,6 +12,7 @@ import {
 } from './defaults.js'
 import { JsonRpcRequestError, RequestTimeoutError } from './rpc/jsonRpcClient.js'
 import { ContentReadGate } from './contentGate.js'
+import { truncateErrorMessage } from './diagnostics.js'
 import type { ReadResult, SessionSubscriptions } from './subscriptions.js'
 import { PairingError } from './pairing.js'
 import type { PairingErrorKind } from './pairing.js'
@@ -290,21 +291,92 @@ export interface CherryReadPart {
   toolName?: string
   toolCallId?: string
   /**
-   * The DESCRIPTIVE face of a binary attachment (`kind: 'file'`): what the file
-   * is, never what it holds. `content` stays empty for such a part by design —
-   * see {@link CherryToolEngine.#attachmentFace}.
+   * The DESCRIPTIVE face of an attachment — a `kind: 'file'` part, or the
+   * legacy `kind: 'data'` part the desktop labels `name: 'file'` and whose
+   * metadata is JSON in `content.text`: what the file is, never what it holds.
+   * `content` stays empty for such a part unless its record carries a key this
+   * face does not project — see {@link CherryToolEngine.#attachmentFace}.
    */
   name?: string
   mediaType?: string
   byteLength?: string
 }
 
+/**
+ * The peer's verdict on a FAILED message, narrowed to what a caller can act on.
+ *
+ * The wire carries more (`failure.failure.source`, `context.responseBody`, the
+ * provider's status code); none of it is projected. `cherry_read` is a text
+ * channel for the conversation, and the provider's raw error body is neither
+ * conversation nor the caller's business — the peer already classified the
+ * cause into `reasonCode`, which is the actionable half.
+ */
+export interface CherryReadFailure {
+  /**
+   * The peer's classification (`provider_unavailable`, `rate_limit`,
+   * `context_length`, … — the protocol's versioned vocabulary).
+   *
+   * Relayed as a SHAPE-checked string rather than matched against a closed
+   * enum: the vocabulary belongs to the peer and grows with it, and relabelling
+   * a new code `'unknown'` would hide a real cause behind a value that means
+   * "the peer could not classify". Absent or unusable values become
+   * `'unknown'`, which is exactly what the contract uses for that case.
+   */
+  reasonCode: string
+  /** Whether the peer judged a retry of the same work worthwhile. */
+  retryable: boolean
+  /**
+   * The peer's one-line explanation, bounded by the diagnostics error cap
+   * (200 characters) with a `…[truncated]` marker when it was cut.
+   */
+  message: string
+}
+
+/** `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`.
+ */
+export function projectMessageFailure(raw: Record<string, unknown>): CherryReadFailure | undefined {
+  const failure = raw['failure']
+  if (typeof failure !== 'object' || failure === null) return undefined
+  const record = failure as Record<string, unknown>
+  const nested = record['failure']
+  const detail = typeof nested === 'object' && nested !== null ? (nested as Record<string, unknown>) : {}
+  const rawReason = detail['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 : ''),
+  }
+}
+
 /** One message in a `cherry_read` snapshot. */
 export interface CherryReadMessage {
   messageId: string
   revision: string
   role: string
   status: string
+  /**
+   * Present exactly when the peer sent a `failure` for this message (in
+   * practice: `status: 'error'`). A successful message never carries it, so a
+   * caller can test for the key rather than compare `status` strings.
+   */
+  failure?: CherryReadFailure
   parts: CherryReadPart[]
   /**
    * Present only when this message's parts could NOT all be read: the safety
@@ -792,6 +864,80 @@ const MESSAGE_CACHE_ENTRY_BYTES = 1_048_576
  */
 const MESSAGE_CACHE_BYTES_PER_DEVICE = 33_554_432
 
+/**
+ * One command the engine issued under a CALLER-SUPPLIED `commandId`, kept so a
+ * retry can replay it by receipt (issues #115, #118).
+ *
+ * The three fields answer the three questions a retry raises:
+ *
+ *  - `method` — is this id being replayed by the tool that minted it? An id
+ *    remembered for a send says nothing about a respond retry, and the reverse;
+ *  - `fingerprint` — did the caller ask for the SAME command? The caller-owned
+ *    arguments only, compared with {@link sameCommandValue}; the DERIVED body
+ *    fields are deliberately excluded, because they are exactly what moved;
+ *  - `body` — what the peer's ledger recorded, reproduced verbatim.
+ */
+interface RememberedCommand {
+  method: string
+  fingerprint: unknown
+  body: Record<string, unknown>
+}
+
+/**
+ * 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
@@ -1196,6 +1342,89 @@ const IDEMPOTENCY_HINT =
   '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 = 1000
+
+/**
+ * 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(): Error {
+  const conflict = new JsonRpcRequestError(JSON_RPC_PROTOCOL_ERROR_CODE, COMMAND_BODY_DIFFERS_MESSAGE, {
+    reason: 'IDEMPOTENCY_CONFLICT',
+    message: COMMAND_BODY_DIFFERS_MESSAGE,
+  })
+  // The two hint helpers pass an error through UNCHANGED (they only append to
+  // a conflict's / a rate-limit's prose), so the identity is the object built
+  // above; the return type keeps the `JsonRpcRequestError` the callers branch
+  // on (the engine's command-failure currency).
+  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: unknown, right: unknown): boolean {
+  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.
@@ -1215,6 +1444,87 @@ function withIdempotencyHint(error: unknown): unknown {
   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: Error): number | undefined {
+  if (!(error instanceof JsonRpcRequestError)) return undefined
+  const data = error.data
+  if (!isRecord(data)) return undefined
+  const raw = data['retryAfterMs']
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) return undefined
+  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).
+ */
+export function withRateLimitHint(error: unknown): unknown {
+  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 === undefined
+      ? '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: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined
 }
@@ -1327,6 +1637,15 @@ export interface CherryToolEngineOptions {
    * which no loopback suite should spend its run on.
    */
   messageCacheBytesPerDevice?: number
+  /**
+   * Cap on the remembered `cherry_send` bodies for one device — issue #115.
+   * Omitted uses {@link COMMAND_BODY_ENTRIES_PER_DEVICE}.
+   *
+   * Injectable so a test can drive the bound to one and observe the FIFO
+   * arithmetic: at the production 128 a proof needs 129 live command ids, which
+   * no loopback suite should spend its run on.
+   */
+  commandBodyEntriesPerDevice?: number
   /**
    * How many `{ref}` contents may be assembled at once across the WHOLE engine
    * — every tool call, every device. Omitted uses
@@ -1337,6 +1656,20 @@ export interface CherryToolEngineOptions {
    * property under test ("no more than the limit at once") is the same at 1.
    */
   contentReadConcurrency?: number
+  /**
+   * The `maxBytes` every `agent.content.read` slice asks for. Omitted uses
+   * {@link CONTENT_READ_MAX_BYTES}, the protocol's `contentBytes`.
+   *
+   * TEST-ONLY, and it exists because the loopback fan-out caps a record at
+   * 32 KiB: at the production 24 KiB no honest ref fits in TWO slices (one
+   * full slice plus the `< 24 KiB` remainder), so a walk's SECOND slice — the
+   * one that proves the ref's digest describes the whole of what is served,
+   * rather than merely its first slice — is unreachable through the fake. A
+   * smaller slice size makes any multi-slice behaviour testable. Never lowered
+   * in production: the peer caps the slice anyway, and asking for less only
+   * costs round trips.
+   */
+  contentReadSliceBytes?: number
 }
 
 /**
@@ -1385,18 +1718,42 @@ export function registerCherryTools(
   deps: CherryToolsDeps,
   options: CherryToolEngineOptions = {},
 ): () => void {
+  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.
+ */
+export function registerCherryToolsWithEngine(
+  ctx: CherryToolsContext,
+  deps: CherryToolsDeps,
+  options: CherryToolEngineOptions = {},
+): { dispose: () => void; engine: CherryToolEngine | undefined } {
   const tools = ctx.tools
   if (tools === undefined) {
     // Headless deployments have no tool registry. Degrade to a warning rather
     // than throwing: the assembly's HTTP/UI half must still come up.
     console.warn('[cherry-remote] ctx.tools is unavailable; the cherry_* tools were not registered')
-    return () => {}
+    return { dispose: () => {}, engine: undefined }
   }
 
   const engine = new CherryToolEngine(deps, options)
   const disposers = engine.definitions().map((definition) => tools.register(definition))
-  return () => {
-    for (const dispose of disposers) dispose()
+  return {
+    engine,
+    dispose: () => {
+      for (const dispose of disposers) dispose()
+    },
   }
 }
 
@@ -1423,7 +1780,7 @@ function defineCherryTool(definition: {
  * share. Kept as one class (rather than per-face closures) so the per-session
  * and per-device state the later faces add has an obvious home.
  */
-class CherryToolEngine {
+export class CherryToolEngine {
   readonly #deps: CherryToolsDeps
   /**
    * Circuit-breaker for the parts walk. A LOCAL policy value, injectable so a
@@ -1498,6 +1855,12 @@ class CherryToolEngine {
    * being read, shared by every tool call and every device this engine serves.
    */
   readonly #contentGate: ContentReadGate
+  /**
+   * 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`).
+   */
+  readonly #contentReadSliceBytes: number
   /**
    * The parts pages already walked, keyed `<deviceId>\0<messageId>`.
    *
@@ -1568,7 +1931,49 @@ class CherryToolEngine {
    * not pinned by bookkeeping.
    */
   readonly #watchedConnections = new WeakSet<DeviceConnection>()
-
+  /**
+   * 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}.
+   */
+  readonly #commandBodies = new Map<string, RememberedCommand>()
+  /** The per-device cap on {@link CherryToolEngine.#commandBodies}. */
+  readonly #commandBodyEntriesPerDevice: number
   constructor(deps: CherryToolsDeps, options: CherryToolEngineOptions = {}) {
     this.#deps = deps
     this.#partsSafetyBound = Math.max(
@@ -1592,7 +1997,15 @@ class CherryToolEngine {
       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(): CherryToolDefinition[] {
@@ -2445,12 +2858,19 @@ class CherryToolEngine {
         '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 ' +
+        '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. The ' +
+        '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 ' +
@@ -2779,11 +3199,13 @@ class CherryToolEngine {
     // stays absent rather than claiming a zero.
     const unavailableParts = parts.filter((part) => part.unavailable !== undefined).length
     const incomplete = unavailableParts > 0 || partsTruncated !== undefined
+    const failure = projectMessageFailure(raw)
     return {
       messageId,
       revision,
       role: String(raw['role'] ?? ''),
       status: String(raw['status'] ?? ''),
+      ...(failure === undefined ? {} : { failure }),
       parts,
       // A circuit-broken part list advertises itself: the caller can see that
       // this message is incomplete and that later parts are still unread, so
@@ -2896,52 +3318,152 @@ class CherryToolEngine {
       text = ''
     }
 
+    // A LEGACY ATTACHMENT is a `data` part whose metadata is JSON TEXT, not an
+    // object (see {@link CherryToolEngine.#attachmentFace}). The face is lifted
+    // here, from the ALREADY-RESOLVED text — the same text a `{ref}` payload
+    // resolves to — so an externalized metadata record lifts identically.
+    const legacy = this.#legacyAttachment(kind, raw, text)
     return {
       partId,
       kind,
       revision,
-      content: text,
-      // Pre-2.1.5 peers (2.1.4 is inside the verified range) projected a file
-      // as a `data` part whose metadata sits INSIDE `content`; lifting it here
-      // is what keeps an attachment from degrading into an anonymous empty
-      // part across the peer upgrade.
-      ...this.#attachmentFace(kind, raw, content),
+      // THE CONTENT RULE: the JSON text is emptied only when EVERY key of the
+      // record is one the face projects; a record carrying keys we do not
+      // project keeps its raw text, so nothing is silently dropped.
+      content: legacy === undefined ? text : legacy.remainder,
+      ...(legacy === undefined
+        ? 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: string,
+    raw: Record<string, unknown>,
+    text: string,
+  ): { record: Record<string, unknown>; remainder: string } | undefined {
+    if (kind !== 'data' || optionalString(raw['name']) !== 'file') return undefined
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(text) as unknown
+    } catch {
+      return undefined
+    }
+    if (!isRecord(parsed)) return undefined
+    // At least ONE projected key must be a string: a record naming neither
+    // `mediaType` nor `filename` says nothing about an attachment, whatever
+    // its name label claims.
+    if (optionalString(parsed['filename']) === undefined && optionalString(parsed['mediaType']) === undefined) {
+      return undefined
+    }
+    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.
+   *
+   * 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: string,
     raw: Record<string, unknown>,
     content: Record<string, unknown>,
+    metadata?: Record<string, unknown>,
   ): { name?: string; mediaType?: string; byteLength?: string } {
     if (kind !== 'file' && kind !== 'data') return {}
     const ref = isRecord(raw['ref']) ? raw['ref'] : isRecord(content['ref']) ? content['ref'] : {}
     // WHERE the name lives is part of the shape, not a matter of preference: on
     // a `file` part `name` IS the filename, while a `data` part's `name` is the
-    // data KIND label — the 2.1.4 projection passes the literal `'file'` there —
-    // so the filename can only come from `content.filename`. Reading `name` for
-    // the data kind would report "file" as the attachment's name.
-    const name = kind === 'file' ? optionalString(raw['name']) : optionalString(content['filename'])
-    const mediaType = optionalString(ref['mediaType']) ?? optionalString(content['mediaType'])
-    const byteLength = optionalString(ref['byteLength'])
+    // data KIND label (the attachment's is the literal `'file'`), so a legacy
+    // filename can only come from the metadata record's `filename`. Reading
+    // `name` for the data kind would report "file" as the attachment's name.
+    const name =
+      kind === 'file'
+        ? optionalString(raw['name'])
+        : (optionalString(metadata?.['filename']) ?? optionalString(content['filename']))
+    const mediaType =
+      kind === 'data' && metadata !== undefined
+        ? (optionalString(metadata['mediaType']) ?? optionalString(content['mediaType']))
+        : (optionalString(ref['mediaType']) ??
+          optionalString(metadata?.['mediaType']) ??
+          optionalString(content['mediaType']))
+    // A legacy `data` part carries no `byteLength`: the only ref it can have is
+    // the metadata envelope's, whose length describes the RECORD.
+    const byteLength = kind === 'file' ? optionalString(ref['byteLength']) : undefined
     return {
       ...(name === undefined ? {} : { name }),
       ...(mediaType === undefined ? {} : { mediaType }),
@@ -2967,13 +3489,23 @@ class CherryToolEngine {
    *    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: unknown): boolean {
-    return !(error instanceof ContentIntegrityError)
+    if (error instanceof ContentIntegrityError) return false
+    return failureReason(error) !== 'RATE_LIMITED'
   }
 
   /**
@@ -3042,7 +3574,7 @@ class CherryToolEngine {
     const refusal = this.#externalizedRefusal(ref)
     if (refusal !== undefined) throw refusal
     const maxSlices = Number.isSafeInteger(declaredBytes)
-      ? Math.max(1, Math.ceil(declaredBytes / CONTENT_READ_MAX_BYTES))
+      ? Math.max(1, Math.ceil(declaredBytes / this.#contentReadSliceBytes))
       : DEFAULT_CONTENT_SLICE_BOUND
 
     let offset = '0'
@@ -3071,7 +3603,9 @@ class CherryToolEngine {
           contentId,
           revision,
           offset,
-          maxBytes: CONTENT_READ_MAX_BYTES,
+          // The protocol's slice size in production; injectable for tests that
+          // must reach a walk's SECOND slice (see the option's docblock).
+          maxBytes: this.#contentReadSliceBytes,
         },
         deadline === undefined ? undefined : { deadline: deadline.instant },
       )) as Record<string, unknown>
@@ -3607,12 +4141,37 @@ class CherryToolEngine {
     request: { args: Record<string, unknown>; text: string },
   ): Promise<{ receipt: Record<string, unknown>; baselineSeq: number }> {
     const { args, text } = request
+    const callerId = optionalString(args['commandId'])
     const attempt = async (
       commandId: string,
       revisionOverride?: string,
     ): Promise<{ receipt: Record<string, unknown>; baselineSeq: number }> => {
+      // The memory belongs to the id it was MINTED for, so the lookup is gated
+      // on `commandId === callerId`: the self-heal's fresh-uuid attempt derives
+      // its own baseline instead of inheriting the caller's.
+      const remembered =
+        callerId === undefined || commandId !== callerId
+          ? undefined
+          : this.#recallCommandBody(deviceId, callerId)
+      // A remembered id that belongs to ANOTHER method is a mismatch, not a
+      // miss: refusing locally keeps the decision off the wire.
+      if (remembered !== undefined && remembered.method !== SEND_METHOD) throw commandBodyDiffers()
+      // A same-id call whose caller-owned arguments differ from the remembered
+      // body is not a retry of that command: the peer holds the original body,
+      // so the conflict is already decided and is answered LOCALLY, in the
+      // peer's own words, with no wire call.
+      const rememberedBody = remembered?.body
+      const mismatched =
+        remembered !== undefined &&
+        (rememberedBody?.['sessionId'] !== sessionId || rememberedBody['text'] !== text)
+      if (mismatched) throw commandBodyDiffers()
+      // THE REMEMBERED BODY IS REPLAYED, derived field included. Rebuilding it
+      // from a derived `expectedIdleRevision` instead is what #115's memory
+      // exists to stop, so the value is read back rather than recomputed.
       const expectedIdleRevision =
-        revisionOverride ?? (await this.#idleRevision(connection, subscriptions, deviceId, sessionId))
+        optionalString(rememberedBody?.['expectedIdleRevision']) ??
+        revisionOverride ??
+        (await this.#idleRevision(connection, subscriptions, deviceId, sessionId))
       // THE BASELINE IS TAKEN BEFORE THE COMMAND IS ISSUED, and that ordering
       // is what makes a fast run observable at all. The waiter's baseline is
       // the cut that decides which events belong to THIS run; taking it after
@@ -3624,7 +4183,16 @@ class CherryToolEngine {
       // Nothing before this point can emit this run's events: the command has
       // not been sent yet.
       const baselineSeq = this.#newestSeq(subscriptions, sessionId)
-      const receipt = await this.#command(connection, 'agent.messages.send', {
+      // The body is remembered the moment it is ISSUED — a reply lost on the wire
+      // must not cost the only copy of the bytes the peer's ledger will accept.
+      if (callerId !== undefined) {
+        this.#rememberCommandBody(deviceId, callerId, {
+          method: SEND_METHOD,
+          fingerprint: { sessionId, text },
+          body: { commandId, sessionId, text, expectedIdleRevision },
+        })
+      }
+      const receipt = await this.#command(connection, SEND_METHOD, {
         commandId,
         sessionId,
         text,
@@ -4020,6 +4588,26 @@ class CherryToolEngine {
           }
         }
 
+        const callerId = optionalString(args['commandId'])
+        const answer: Record<string, unknown> = response === undefined ? { decision } : { response }
+        // A RETRY IS ANSWERED BEFORE ANYTHING IS DERIVED. The staleness triple
+        // below is derived from what the plugin has observed, and after a lost
+        // reply that observation has MOVED (the first answer settled the card)
+        // or vanished (the peer no longer serves it). Re-deriving would either
+        // quote a body the ledger never recorded or — the usual case — stop at
+        // the `unknown-interaction` verdict below, before the body is ever
+        // compared. So a caller-supplied id is consulted FIRST: same id, same
+        // caller-owned arguments and same method replays the remembered body
+        // verbatim, and the snapshot is not asked at all.
+        const remembered =
+          callerId === undefined ? undefined : this.#recallCommandBody(record.deviceId, callerId)
+        if (remembered !== undefined && remembered.method !== RESPOND_METHOD) throw commandBodyDiffers()
+        if (remembered !== undefined) {
+          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)
 
@@ -4042,15 +4630,27 @@ class CherryToolEngine {
           } satisfies Record<string, unknown>
         }
 
-        return this.#command(connection, 'agent.interactions.respond', {
-          commandId: this.#commandId(args),
+        const commandId = this.#commandId(args)
+        const body = {
+          commandId,
           sessionId,
           interactionId,
           expectedRevision: snapshot.revision,
           expectedExecutionId: snapshot.executionId,
           inputDigest: snapshot.inputDigest,
-          ...(response === undefined ? { decision } : { response }),
-        })
+          ...answer,
+        }
+        // ISSUE-TIME WRITE: the body is fully composed here, so it is remembered
+        // 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.
+        if (callerId !== undefined) {
+          this.#rememberCommandBody(record.deviceId, callerId, {
+            method: RESPOND_METHOD,
+            fingerprint: { sessionId, interactionId, ...answer },
+            body,
+          })
+        }
+        return this.#command(connection, RESPOND_METHOD, body)
       },
     })
   }
@@ -4092,6 +4692,27 @@ class CherryToolEngine {
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
+        const callerId = optionalString(args['commandId'])
+        // The caller's own value is a PRE-CHECK, not a body field — but it is
+        // part of what the caller ASKED FOR, so it belongs in the fingerprint: a
+        // retry asserting a different execution is not a retry of this cancel.
+        const supplied = optionalString(args['expectedExecutionId'])
+
+        // A RETRY IS ANSWERED BEFORE THE PRE-CHECKS — the same ordering (and
+        // the same reason) as `agent.interactions.respond`'s consult above;
+        // what differs here is only which verdicts would otherwise eat the
+        // retry: `no-active-execution` and `execution-mismatch` describe the
+        // state RIGHT NOW, and a lost reply left the run the first attempt
+        // cancelled already finished.
+        const remembered =
+          callerId === undefined ? undefined : this.#recallCommandBody(record.deviceId, callerId)
+        if (remembered !== undefined && remembered.method !== CANCEL_METHOD) throw commandBodyDiffers()
+        if (remembered !== undefined) {
+          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)
@@ -4107,7 +4728,6 @@ class CherryToolEngine {
             message: `session ${sessionId} has no in-flight execution to cancel`,
           } satisfies Record<string, unknown>
         }
-        const supplied = optionalString(args['expectedExecutionId'])
         if (supplied !== undefined && supplied !== expectedExecutionId) {
           return {
             error: 'execution-mismatch',
@@ -4119,11 +4739,18 @@ class CherryToolEngine {
           } satisfies Record<string, unknown>
         }
 
-        return this.#command(connection, 'agent.executions.cancel', {
-          commandId: this.#commandId(args),
-          sessionId,
-          expectedExecutionId,
-        })
+        const commandId = this.#commandId(args)
+        const body = { commandId, sessionId, expectedExecutionId }
+        // ISSUE-TIME WRITE, as respond's: the derived execution id is exactly
+        // the field a retry cannot re-derive once the run has ended.
+        if (callerId !== undefined) {
+          this.#rememberCommandBody(record.deviceId, callerId, {
+            method: CANCEL_METHOD,
+            fingerprint: { sessionId, expectedExecutionId: supplied },
+            body,
+          })
+        }
+        return this.#command(connection, CANCEL_METHOD, body)
       },
     })
   }
@@ -4284,7 +4911,7 @@ class CherryToolEngine {
         // pairing's idle revisions and execution ids, and would grow the maps
         // for the lifetime of the process. The store record is untouched by
         // this — the caches are pure derived state and can always be rebuilt.
-        this.#forgetDevice(record.deviceId)
+        this.#forgetDevice(record.deviceId, { dropCommandBodies: true })
         await this.#deps.evict(record.deviceId)
         // The remove is GUARDED, not merely ordered. `#selectRecords` already
         // rejects a quarantined store before a record can be named, so reaching
@@ -4330,12 +4957,12 @@ class CherryToolEngine {
    * 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: DeviceConnection,
@@ -4345,7 +4972,7 @@ class CherryToolEngine {
     try {
       return (await connection.rpc.request(method, params)) as Record<string, unknown>
     } catch (error) {
-      throw withIdempotencyHint(error)
+      throw withRateLimitHint(withIdempotencyHint(error))
     }
   }
 
@@ -4645,7 +5272,8 @@ class CherryToolEngine {
    *    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
@@ -4673,7 +5301,8 @@ class CherryToolEngine {
     this.#watchedConnections.add(connection)
     watch(deviceId, (state) => {
       if (state !== 'offline' && state !== 'identity-mismatch') return
-      this.#forgetDevice(deviceId)
+      // A plain `offline` keeps the remembered command bodies: see `#forgetDevice`.
+      this.#forgetDevice(deviceId, { dropCommandBodies: state === 'identity-mismatch' })
     })
   }
 
@@ -4686,8 +5315,16 @@ class CherryToolEngine {
    * 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: string): void {
+  #forgetDevice(deviceId: string, options: { dropCommandBodies?: boolean } = {}): void {
     const prefix = `${deviceId}\u0000`
     for (const key of [...this.#revisionCache.keys()]) {
       if (key.startsWith(prefix)) this.#forget(this.#revisionCache, key)
@@ -4708,6 +5345,116 @@ class CherryToolEngine {
     for (const key of [...this.#messageCache.keys()]) {
       if (key.startsWith(prefix)) this.#dropCachedMessage(key)
     }
+    // The remembered command bodies (issues #115/#118) differ from every cache above:
+    // what they replay against is the peer's command LEDGER, and that survives
+    // an ordinary reconnect — so they are dropped only when the PAIRING is
+    // invalidated (`dropCommandBodies`: unpair, identity-mismatch), because a
+    // body minted against one pairing must not be replayed to whatever desktop
+    // answers under this device id next.
+    //
+    // The residual, stated rather than closed: GRANT_REVOKED also surfaces as
+    // `offline`, so a voided pairing's entries survive until the re-pair path
+    // (unpair / identity-mismatch) or the 128-entry FIFO retires them; a same-id
+    // retry across a silent re-pair replays a body the new peer admits as a NEW
+    // command — and the caller asked for that send.
+    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: string, commandId: string): RememberedCommand | undefined {
+    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: string): string[] {
+    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: string, commandId: string): void {
+    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: string,
+    commandId: string,
+    remembered: RememberedCommand,
+  ): void {
+    const key = this.#cacheKey(deviceId, commandId)
+    if (!this.#commandBodies.has(key)) {
+      let own = 0
+      let oldest: string | undefined
+      for (const candidate of this.#commandBodies.keys()) {
+        if (!candidate.startsWith(`${deviceId}\u0000`)) continue
+        own += 1
+        if (oldest === undefined) oldest = candidate
+      }
+      if (own >= this.#commandBodyEntriesPerDevice && oldest !== undefined) {
+        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)
   }
 
   /**