dsh-cherry-bridge 0.1.10 → 0.2.0

package/src/tools.ts

@@ -16,6 +16,7 @@ import { truncateErrorMessage } from './diagnostics.js'
 import type { ReadResult, SessionSubscriptions } from './subscriptions.js'
 import { PairingError } from './pairing.js'
 import type { PairingErrorKind } from './pairing.js'
+import { failureText } from './text.js'
 import type { AgentCursor } from '@cherrystudio/remote-protocol/agent'
 
 /**
@@ -291,9 +292,11 @@ 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
@@ -604,6 +607,42 @@ export interface CherryCreateResult {
 
 /** The protocol's single-page hard cap, used only as the pre-hello ceiling. */
 const PAGE_ITEMS_FALLBACK = 100
+/**
+ * The page this bridge asks for when the peer's hello advertised
+ * `agentMessageSummariesVersion: 1` (issue #105).
+ *
+ * WHY IT IS NOT {@link LIST_PAGE_CLAMP} (16): that clamp is metadata-BLIND. It
+ * exists because `AgentMessage` carries `partIds` — up to 4,096 entries of
+ * schema-capped ids each — so a count-only peer can answer a page the 65,536-byte
+ * record cannot hold and the transport kills the connection (`defaults.ts`).
+ * What `partsMode: 'paged'` returns is `AgentMessageSummary`: identity,
+ * revision, role, status and optional usage/model/failure, and NO `partIds`.
+ *
+ * WHY THE PAGE BOUND IS THE PEER'S, NOT OURS: the ONLY verified advertiser of
+ * the capability (desktop 2.1.8) budgets the ACCUMULATED page — `pageOf`
+ * prefix-truncates at `PAGE_ITEM_BYTES` = 62,279 bytes and `queryPage` re-asks
+ * at a halved limit, so its reply records stay under `recordBytes` = 65,536
+ * whatever our `limit` says, answering with a SHORT page + `nextCursor` (the
+ * shape our walk already tolerates) instead of a killed link. The single-item
+ * `RESOURCE_EXHAUSTED {ITEM_TOO_LARGE, retryable: false}` refusal is the
+ * exception arm, and a schema-valid summary row cannot reach it: measured
+ * against the 0.7.0 schema, the worst row (ids at 256 units, `model` fields at
+ * 2,048 chars each, 32 `costs` entries, `failure` refined to ≤4,096 bytes) is
+ * ≈37 KB — under the 62,279 budget, so the refusal exists for full
+ * `partIds`-bearing rows, not summaries.
+ *
+ * 100 is the protocol's own `pageItems` cap, i.e. the ceiling a walk can use at
+ * all: `#aggregate` still intersects this with the peer's NEGOTIATED
+ * `pageItems`, so a peer advertising less keeps its size. Residual exposure —
+ * a hypothetical peer advertising the capability WITHOUT a page budget —
+ * contains no verified desktop (≤2.1.7 never advertises and keeps the clamp),
+ * the same "pragmatic, not provable" class `defaults.ts` already scopes.
+ *
+ * The PARTS walk keeps {@link PARTS_LIST_PAGE_CLAMP} unconditionally: nothing
+ * in protocol 0.7.0 proves `agent.parts.list` is byte-aware, and a part is the
+ * fattest item there is.
+ */
+const MESSAGE_SUMMARIES_PAGE_ITEMS = PAGE_ITEMS_FALLBACK
 /** The largest MESSAGE aggregate a caller may ask for; the per-page clamp still applies. */
 const MAX_AGGREGATE_LIMIT = 1000
 /**
@@ -749,6 +788,33 @@ interface AggregateWalk<T> {
   deadline?: AssemblyDeadline
 }
 
+/**
+ * The `agent.messages.list` request for ONE message walk, and the page size to
+ * ask for — the ONE place the paged-summaries dialect is decided (issue #105).
+ *
+ * THE INVARIANT: `partsMode` is sent ONLY to a peer whose own hello advertised
+ * `agentMessageSummariesVersion: 1`. 0.5.0's params schema — what every desktop
+ * through 2.1.7 ships — is a STRICT object with no such key, so sending it
+ * there is a protocol violation, not a wasted field. Both message-walk faces
+ * (`cherry_read` and the terminal/timeout/idle aggregate) come through HERE for
+ * the same reason the resume token has one helper: two call sites spelling the
+ * dialect would eventually disagree about which peer may hear it.
+ *
+ * With the capability, the page size is {@link MESSAGE_SUMMARIES_PAGE_ITEMS} —
+ * summary rows are metadata, so the byte-safe clamp no longer bounds anything
+ * they can carry. Without it, the clamp stays exactly as it was: the
+ * count-paged peer still returns `partIds`-bearing rows.
+ */
+function messageListRequest(connection: DeviceConnection): {
+  params: Record<string, unknown>
+  maxPerPage: number
+} {
+  if (connection.limits.messageSummaries === 1) {
+    return { params: { partsMode: 'paged' }, maxPerPage: MESSAGE_SUMMARIES_PAGE_ITEMS }
+  }
+  return { params: {}, maxPerPage: LIST_PAGE_CLAMP }
+}
+
 /** Token prefix for a peer page position; the one `#aggregate` can send back. */
 const RESUME_CURSOR_PREFIX = 'cursor:'
 /** Token prefix for "strictly older than this message id". */
@@ -862,6 +928,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
@@ -1219,6 +1359,55 @@ function failureReason(error: unknown): string | undefined {
   return undefined
 }
 
+/**
+ * The phrase this hint leaves behind, so applying it twice reads once.
+ */
+const PEER_REFUSAL_FINAL_MARK = 'retrying the same request cannot help'
+
+/**
+ * The recovery advice a PERMANENT peer refusal grows — `RESOURCE_EXHAUSTED`
+ * carrying `details.retryable === false`, which is the desktop's per-item byte
+ * budget (`PAGE_ITEM_BYTES` = 62,279; `details.kind` is `ITEM_TOO_LARGE` with
+ * `itemBytes` / `budgetBytes`), issue #105.
+ *
+ * WHY THE WARNING HAS TO BE ADDED: the official client marks every
+ * `RESOURCE_EXHAUSTED` RETRYABLE and re-asks at the same page size on an
+ * exponential backoff, so a byte-budget refusal never converges — and the
+ * condition really is permanent: the same item over the same budget will be
+ * over it again. A caller (or a model reading the error) that retries learns
+ * nothing but spends the peer's rate window.
+ *
+ * The sentence is deliberately narrower than the reason: only the
+ * `retryable === false` shape grows it. Every other `RESOURCE_EXHAUSTED` —
+ * the upload window, the subscription cap, a legacy refusal with no `details` —
+ * keeps its own text, because some of those ARE worth a later retry.
+ *
+ * Like {@link withIdempotencyHint} this EXTENDS `message` only: the reason, the
+ * structured `data` and the {@link JsonRpcRequestError} identity stay the
+ * peer's, so branching callers see exactly what it sent.
+ */
+export function withPeerRefusalHint(error: unknown): unknown {
+  if (!(error instanceof JsonRpcRequestError)) return error
+  if (failureReason(error) !== 'RESOURCE_EXHAUSTED') return error
+  const data = error.data
+  if (!isRecord(data) || !isRecord(data['details']) || data['details']['retryable'] !== false) return error
+  if (error.message.includes(PEER_REFUSAL_FINAL_MARK)) return error
+  const kind = optionalString(data['details']['kind'])
+  // The two permanent shapes need OPPOSITE advice. ITEM_TOO_LARGE means ONE
+  // item alone exceeds the per-item budget: no page size fits it — that item
+  // and everything behind it are unreachable (the upstream #21951 dead-end),
+  // so suggesting a smaller `limit` would burn round trips learning nothing.
+  const cause = kind === 'ITEM_TOO_LARGE' ? 'an ITEM_TOO_LARGE page item over its byte budget' : 'the same item'
+  const tail =
+    kind === 'ITEM_TOO_LARGE'
+      ? 'the item ITSELF exceeds the peer\u2019s per-item budget, so no page size or request shape can fetch it (nor the items behind it — upstream #21951)'
+      : 'ask for FEWER items per page (a smaller `limit`), which is the only change that can fit the budget'
+  error.message =
+    `${error.message} — the peer marked this refusal permanent (\`details.retryable: false\`: ${cause}); ` +
+    `retrying the same request cannot help — ${tail}`
+  return error
+}
+
 /**
  * One `{ref}`'s content could not be TRUSTED: the bytes served do not match the
  * digest the ref advertises (or there was no digest to check against).
@@ -1266,6 +1455,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.
@@ -1478,6 +1750,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
@@ -1488,6 +1769,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
 }
 
 /**
@@ -1536,22 +1831,58 @@ 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()
+    },
   }
 }
 
-/** One tool declaration, in the exact shape the host registry consumes. */
+/**
+ * One tool declaration, in the exact shape the host registry consumes.
+ *
+ * This helper adds no result WRAPPER and this ticket adds no result-side
+ * truncation (issue #161): a tool result is the MODEL's signal, and the peer is
+ * the user's own Noise-authenticated desktop, so shortening the peer's
+ * explanation costs the caller the text it acts on. The two result-text clamps
+ * that DO exist are per-field product choices, not a log rule — `aggregateError`
+ * (`message.slice(0, 200)` in `#assemblyFailed`) and `truncateErrorMessage`'s
+ * 200-character diagnostics digest used by `projectMessageFailure`. The LOG
+ * face is where boundedness is required (`failureText` / `clipText` in `src/text.ts`);
+ * this ticket's sweep does not change tool output.
+ */
 function defineCherryTool(definition: {
   name: string
   description: string
@@ -1574,7 +1905,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
@@ -1649,6 +1980,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>`.
    *
@@ -1719,7 +2056,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(
@@ -1743,7 +2122,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[] {
@@ -2137,7 +2524,12 @@ class CherryToolEngine {
         if (deadline !== undefined && deadlineExhaustion(error)) {
           return this.#truncated(items, 'deadline', cursor)
         }
-        throw error
+        // A PERMANENT peer refusal (issue #105) grows its advice HERE, at the
+        // one seam every paged walk's refusals pass through, and ONLY the
+        // `details.retryable: false` shape: a walk has no retry of its own to
+        // reason about, and the caller is the party that must change the
+        // request. The error object, its reason and its `data` are unchanged.
+        throw withPeerRefusalHint(error)
       }
       const extracted = extract(result)
       // THE PAGE'S OWN SHAPE (issue #46), judged on EVERY page — terminal or
@@ -2596,8 +2988,11 @@ 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 ' +
@@ -2753,15 +3148,18 @@ class CherryToolEngine {
       throw new Error(`agent.sessions.get returned no historyRevision for session ${sessionId}`)
     }
 
+    // The paged-summaries dialect (issue #105) from the ONE helper both message
+    // faces share: `partsMode` only for a peer whose hello advertised it.
+    const messageList = messageListRequest(connection)
     const page = await this.#aggregate(
       connection,
       'agent.messages.list',
-      { sessionId, historyRevision },
+      { sessionId, historyRevision, ...messageList.params },
       (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
       {
         limit,
         safetyBound: MAX_AGGREGATE_LIMIT,
-        maxPerPage: LIST_PAGE_CLAMP,
+        maxPerPage: messageList.maxPerPage,
         resume:
           resume === undefined
             ? undefined
@@ -3053,52 +3451,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.7.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 }),
@@ -3209,7 +3707,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'
@@ -3238,7 +3736,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>
@@ -3458,7 +3958,16 @@ class CherryToolEngine {
         try {
           await subscriptions.ack(sessionId, result.nextCursor)
         } catch (error) {
-          console.warn(`[cherry-remote] acknowledging session ${sessionId} at ${result.nextCursor.seq} failed`, error)
+          // ONE bounded STRING (issue #161): the ack refusal is the PEER's
+          // JSON-RPC `error.message` verbatim (a CONFLICT from an out-of-window
+          // cursor, a reset race), so the old object print let the console
+          // render peer text with no local bound. Ceiling:
+          // `[cherry-remote] acknowledging session ` (38) + sessionId +
+          // ` at ` (4) + seq + ` failed: ` (9) + LOG_TEXT_MAX (240).
+          console.warn(
+            `[cherry-remote] acknowledging session ${sessionId} at ${result.nextCursor.seq} failed: ` +
+              failureText(error),
+          )
           this.#reEnsureInBackground(record.deviceId, sessionId)
         }
         return { events: result.events, nextCursor: result.nextCursor }
@@ -3774,12 +4283,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
@@ -3791,7 +4325,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,
@@ -4187,6 +4730,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)
 
@@ -4209,15 +4772,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)
       },
     })
   }
@@ -4259,6 +4834,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)
@@ -4274,7 +4870,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',
@@ -4286,11 +4881,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)
       },
     })
   }
@@ -4451,7 +5053,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
@@ -4812,7 +5414,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
@@ -4840,7 +5443,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' })
     })
   }
 
@@ -4853,8 +5457,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)
@@ -4875,6 +5487,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)
   }
 
   /**
@@ -5997,15 +6719,25 @@ class CherryToolEngine {
    * identity object: the verdict is already known and true, and only the
    * content behind it failed.
    *
-   * `aggregateError` is BOUNDED like every other peer-echoed string in a result
-   * (the full text goes to the log): the reason is actionable at 200 characters
-   * and the log is where the operator reads the rest.
+   * `aggregateError` is a TOOL RESULT, not a log line — see
+   * {@link defineCherryTool} for the product decision (issue #161): a result is
+   * the MODEL's signal, so it is not bounded by the logging rule, and the
+   * 200-character clip here is this field's own choice.
+   *
+   * The LOG line IS the logging face, and it renders the failure as ONE bounded
+   * string through {@link failureText} (issue #161). An assembly failure is
+   * usually a peer RPC refusal — its `error.message` is the peer's own text,
+   * capped at 512 characters by the failure schema — and the old line
+   * interpolated it whole: one 512-char refusal made a 654-character line for
+   * the `timeout` / `s-1` fixture (83 fixed prefix + 512 + 59 suffix). The
+   * RESULT keeps the raw message's first 200 characters; a bound on the log
+   * does not change what the model receives.
    */
   #assemblyFailed(identity: Record<string, unknown>, error: unknown): Record<string, unknown> {
     const message = error instanceof Error ? error.message : String(error)
     console.warn(
       `[cherry-remote] the ${String(identity['status'])} answer for session ${String(identity['sessionId'])} ` +
-        `could not assemble its content (${message}); returning the verdict with the assembly failure reported`,
+        `could not assemble its content (${failureText(error)}); returning the verdict with the assembly failure reported`,
     )
     return {
       ...identity,
@@ -6101,12 +6833,14 @@ class CherryToolEngine {
     const historyRevision = optionalString(session['historyRevision'])
     if (historyRevision === undefined) return { messages: [] }
 
+    // The SAME dialect `cherry_read` sends, from the same helper (issue #105).
+    const messageList = messageListRequest(connection)
     const page = await this.#aggregate(
       connection,
       'agent.messages.list',
-      { sessionId, historyRevision },
+      { sessionId, historyRevision, ...messageList.params },
       (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
-      { limit: TERMINAL_AGGREGATE_MESSAGES, deadline },
+      { limit: TERMINAL_AGGREGATE_MESSAGES, deadline, maxPerPage: messageList.maxPerPage },
     )
 
     const messages: CherryReadMessage[] = []
@@ -6181,11 +6915,24 @@ class CherryToolEngine {
     try {
       layer = this.#deps.subs(deviceId)
     } catch (error) {
-      console.warn(`[cherry-remote] could not re-ensure session ${sessionId} of ${deviceId}`, error)
+      // ONE bounded STRING (issue #161). This accessor's throw is LOCAL (no
+      // record for the device, or the identity never loaded), but the arm is
+      // converted with its sibling so the background re-ensure has ONE failure
+      // shape and no branch can hand the console an unbounded object.
+      console.warn(
+        `[cherry-remote] could not re-ensure session ${sessionId} of ${deviceId}: ${failureText(error)}`,
+      )
       return
     }
     void layer.ensure(sessionId).catch((error: unknown) => {
-      console.warn(`[cherry-remote] re-ensuring session ${sessionId} of ${deviceId} failed`, error)
+      // ONE bounded STRING (issue #161): `ensure` reaches the peer, so the
+      // rejection message is the peer's JSON-RPC `error.message` verbatim (up
+      // to the 512-char failure schema cap) or a transport message. The old
+      // form passed the error OBJECT, so the console printed its stack plus
+      // every own property unbounded.
+      console.warn(
+        `[cherry-remote] re-ensuring session ${sessionId} of ${deviceId} failed: ${failureText(error)}`,
+      )
     })
   }