dsh-cherry-bridge 0.1.11 → 0.2.0

package/src/rpc/jsonRpcClient.ts

@@ -5,6 +5,7 @@ import {
   remoteFailureSchema,
 } from '@cherrystudio/remote-protocol'
 import type { SecureChannel } from '@cherrystudio/remote-transport'
+import { failureText } from '../text.js'
 
 /** Default cap on business requests in flight on a single connection. */
 const DEFAULT_MAX_IN_FLIGHT = 8
@@ -558,7 +559,24 @@ export class JsonRpcClient {
         try {
           handler(method, params)
         } catch (error) {
-          console.warn(`[cherry-remote] notification handler for "${method}" threw`, error)
+          // BOUNDED, and ONE STRING (issue #155; rendered by the shared
+          // `failureText`, issue #161). The old form passed the error OBJECT as
+          // a second argument, so the console chose the rendering: the stack
+          // plus every own property, with nothing bounding it. A handler
+          // failure is not a payload, so the line carries what an operator
+          // needs and nothing else — the METHOD and the MESSAGE under
+          // LOG_TEXT_MAX. The method is already bounded twice over, without
+          // clipText: the notification schema caps `method` at 128 characters
+          // and `bounded()` (the frame-drop path's older, count-less form,
+          // deliberately kept: folding it into clipText would change its bare
+          // `…` marker and the caller's asserted text) clips to 120 + an
+          // ellipsis.
+          // Ceiling: `[cherry-remote] notification handler for "` (42) +
+          // bounded method (≤ 121: FRAME_FIELD_LIMIT 120 + the ellipsis) +
+          // `" threw: ` (9) + LOG_TEXT_MAX (240) = 412.
+          console.warn(
+            `[cherry-remote] notification handler for "${bounded(method)}" threw: ${failureText(error)}`,
+          )
         }
       }
       return

package/src/subscriptions.ts

@@ -1,6 +1,7 @@
 import { JsonRpcRequestError } from './rpc/jsonRpcClient.js'
 import type { JsonRpcClient } from './rpc/jsonRpcClient.js'
 import { DEFAULT_PER_SESSION_CACHE_BYTES } from './defaults.js'
+import { failureText } from './text.js'
 import type { AgentCursor, AgentEvent } from '@cherrystudio/remote-protocol/agent'
 
 /**
@@ -760,8 +761,15 @@ export class SessionSubscriptions {
       await this.#rpc.request('agent.subscriptions.close', { subscriptionId })
     } catch (error) {
       // Closing is best-effort: the peer may already have reset it, and the
-      // caller is about to establish a replacement either way.
-      console.warn(`[cherry-remote] closing subscription ${subscriptionId} failed`, error)
+      // caller is about to establish a replacement either way. ONE bounded
+      // STRING (issue #161): the refusal is the PEER's JSON-RPC
+      // `error.message` verbatim, so the old object print let the console
+      // render peer text with no local bound. Ceiling:
+      // `[cherry-remote] closing subscription ` (37) + subscriptionId +
+      // ` failed: ` (9) + LOG_TEXT_MAX (240).
+      console.warn(
+        `[cherry-remote] closing subscription ${subscriptionId} failed: ${failureText(error)}`,
+      )
     }
   }
 

package/src/text.ts

@@ -0,0 +1,158 @@
+/**
+ * Bounded rendering for peer- and payload-controlled text (issue #155).
+ *
+ * The ONE helper this audit STANDARDISED ON — not the first attempt at the
+ * idea: `src/diagnostics.ts`'s `truncateErrorMessage` (the diagnostics error
+ * digest) and `src/rpc/jsonRpcClient.ts`'s `bounded()` (the frame-drop
+ * warning's classification fields) predate it and stay where they are, for
+ * their own callers. #155 is where the rendering rule was stated once and
+ * applied to the SIX sites the audit found — four files: pairing's unknown-key
+ * warning and stage verdict, the link-recovery line, the two connection error
+ * lines, and the JSON-RPC notification-handler line. Each was unbounded for a
+ * different "why not" (a 10 KiB payload cap, a hello-advertised field, the
+ * 64 KiB record budget), which is exactly how the class of defect recurs: each
+ * site answered the question for itself.
+ *
+ * The rule these helpers establish is stated once, here: bound the text where
+ * it is RENDERED (never where it is carried — an error message is a value
+ * until a log line or a verdict makes it text), name the amount removed with
+ * the `… (+N chars)` marker, and never drop a list ENTRY silently (the
+ * `(+K more)` count is explicit).
+ *
+ * Issue #161 swept the SAME SHAPE at the sites #155 did not name — a catch
+ * handing an error OBJECT to `console.warn`'s second argument — on the paths
+ * PEER traffic reaches. One renderer states the answer there, {@link
+ * failureText}: the message alone, bounded. A purely LOCAL catch keeps the
+ * object print, deliberately: its stack is the useful part and no peer text
+ * can reach it (fs quarantine, the host registry, our own listener / settle
+ * fan-out, a REST route's synchronous construction). The two earlier forms it
+ * did NOT absorb — `truncateErrorMessage` (the diagnostics digest) and
+ * `bounded()` (the frame-drop path) — are left alone: each emits a different
+ * marker (`…[truncated]`, a bare `…`) that callers and docs depend on, so
+ * folding would change output rather than converge on the rule.
+ */
+
+/**
+ * Clips `text` into `max` characters, the `… (+N chars)` marker included in
+ * the count. `kept` is a fixed point — the number of removed characters sets
+ * the marker's own digits — and it is the LARGEST prefix that fits, so a
+ * caller's ceiling is used without ever being exceeded.
+ *
+ * The final guard never ends the kept prefix between a UTF-16 surrogate pair: a
+ * clip there would emit a lone surrogate, which is not valid unicode text (the
+ * peer's `unicodeText` params face refuses it) and would travel in a
+ * user-visible verdict. Dropping one char pays for a marker that can grow by
+ * one digit at a 9→10 boundary, and the marker is re-derived from the new
+ * dropped count. Pinned by `tests/unit/text.test.ts` — the branch used to be a
+ * declared coverage gap while the clip point was private to pairing.
+ */
+export function clipText(text: string, max: number): string {
+  if (text.length <= max) return text
+  let kept = max
+  for (;;) {
+    const next = max - `… (+${text.length - kept} chars)`.length
+    if (next === kept) break
+    // A room too small for the marker cannot carry both; admit the loss with
+    // the bare ellipsis rather than overrun the caller's bound.
+    if (next < 0) return '…'.slice(0, max)
+    kept = next
+  }
+  const before = text.charCodeAt(kept - 1)
+  const after = text.charCodeAt(kept)
+  if (kept > 0 && before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff) {
+    kept -= 1
+  }
+  return `${text.slice(0, kept)}… (+${text.length - kept} chars)`
+}
+
+/**
+ * Renders `items` as a comma-joined list under `limits.max`, each item clipped
+ * to `limits.itemMax` FIRST. When anything is left out the list says so:
+ * ` (+K more)` where K is the number of items NOT named.
+ *
+ * Caller contract: `itemMax <= max`, so the first item always fits and a list
+ * carrying a single over-long entry never renders an empty one. The marker
+ * rides ON TOP of `limits.max` — it is a count, not an item, so the named text
+ * never has to absorb its length. `[]` renders as `''`.
+ *
+ * Pairing's progress line (`stageHosts`) deliberately does NOT use this helper:
+ * it always shows the FIRST host in full even above its own budget, because
+ * that host is the run's identity. That is not an oversight, and it is not a
+ * reason to weaken the contract here.
+ */
+export function boundedJoin(
+  items: readonly string[],
+  limits: { max: number; itemMax: number },
+): string {
+  const rendered = items.map((item) => clipText(item, limits.itemMax))
+  const first = rendered[0]
+  if (first === undefined) return ''
+  let text = first
+  let shown = 1
+  for (; shown < rendered.length; shown += 1) {
+    // The separator is charged to the same budget as the item: a list that
+    // stops two characters early on paper would still refuse an entry it could
+    // have named.
+    if (text.length + 2 + rendered[shown]!.length > limits.max) break
+    text += `, ${rendered[shown]}`
+  }
+  const omitted = items.length - shown
+  return omitted > 0 ? `${text} (+${omitted} more)` : text
+}
+
+/**
+ * The ceiling for ONE peer- or payload-controlled detail interpolated into a
+ * log line: 240 characters, the `… (+N chars)` marker included.
+ *
+ * It is deliberately NOT the same budget as pairing's `FAILURE_SEGMENT_MAX`,
+ * although both read 240: that one bounds the WHOLE `<label>: <detail>`, so
+ * the label eats from it and the detail there is at most 218 (a
+ * `pairing hello failed` label — 20 characters — plus its `': '`) and often
+ * less. Same number, different quantity: this one is the detail alone.
+ *
+ * Call sites. Two shapes are rendered with it:
+ *
+ *  - peer-controlled DETAIL through {@link clipText}: `src/connection.ts`'s
+ *    protocol-version console.error (the cause is the peer's own hello-echo
+ *    text) and transient-failure console.warn (the transport's own message).
+ *  - a caught FAILURE through {@link failureText} (issue #161), on the catches
+ *    peer traffic reaches: `src/index.ts`'s notification routing and
+ *    subscription recovery, `src/tools.ts`'s ack and both background re-ensure
+ *    arms plus its `#assemblyFailed` log line, `src/subscriptions.ts`'s
+ *    subscription-close catch, `src/httpApi.ts`'s `warnConnect` rejection, and
+ *    the JSON-RPC notification-handler catch in `src/rpc/jsonRpcClient.ts`
+ *    (#155). None of them passes the error object.
+ *
+ * Other bounded faces state their own value beside the line they bound
+ * (`UNKNOWN_FIELDS_MAX` / `RECOVERY_SESSIONS_MAX`), because what they bound is
+ * a rendered LIST or a joined field, not one detail.
+ */
+export const LOG_TEXT_MAX = 240
+
+/**
+ * Renders ONE caught failure for a log line: the message alone, clipped to
+ * {@link LOG_TEXT_MAX}.
+ *
+ * This is the ONE form a caught failure takes in a PEER-TRIGGERED catch (issue
+ * #161): a catch reached from peer traffic or a peer-triggered callback. The
+ * old shape — `console.warn(prefix, error)` — handed the console the OBJECT.
+ * On Node the console prints the error's name, message and stack (own
+ * properties only when inspected), so the peer-controlled message and the
+ * stack were both unbounded; for a defensive catch the stack is the noise.
+ *
+ * A caught failure from a purely LOCAL path (an fs copy, the host registry, our
+ * own observers) keeps the object print: its stack is the useful part and no
+ * peer text can reach it.
+ *
+ * TOTAL by construction: it runs INSIDE catch blocks, so a captured value whose
+ * `toString` (or an Error subclass whose `message` getter) throws must not
+ * escape the catch. The extraction is guarded and falls back to the fixed token
+ * `<unrenderable failure>`.
+ */
+export function failureText(error: unknown): string {
+  try {
+    return clipText(error instanceof Error ? error.message : String(error), LOG_TEXT_MAX)
+  } catch {
+    return '<unrenderable failure>'
+  }
+}

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'
 
 /**
@@ -606,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
 /**
@@ -751,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". */
@@ -1295,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).
@@ -1757,7 +1870,19 @@ export function registerCherryToolsWithEngine(
   }
 }
 
-/** 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
@@ -2399,7 +2524,12 @@ export 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
@@ -3018,15 +3148,18 @@ export 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
@@ -3348,7 +3481,7 @@ export class CherryToolEngine {
    * '{\"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
+   * 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.
@@ -3825,7 +3958,16 @@ export 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 }
@@ -6577,15 +6719,25 @@ export 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,
@@ -6681,12 +6833,14 @@ export 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[] = []
@@ -6761,11 +6915,24 @@ export 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)}`,
+      )
     })
   }
 

package/ui/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md — `ui/`
+
+The settings page: pairing wizard, device cards and the tool-scope panel. It
+builds to `lib/client.js` (`npm run build:client`) and that bundle is COMMITTED
+with its source. Loaded automatically when a file tool touches `ui/**`.
+
+- **One view, no router.** `App.tsx` owns the two things that outlive both
+  children: the SSE stream and the device map.
+- **The stream opens ONCE on mount and closes on unmount, in that order.** The
+  verification code exists only as a frame with no replay, so the stream must
+  exist before the wizard can `POST /pair` — which is why the submit button
+  stays disabled until `subscribed` flips true.
+- **`device-state` is a FIRST-FRAME contract.** The REST list supplies the
+  static fields; a card's light shows only a state the server actually sent.
+- **Every user-visible string goes through `t()`** (`i18n.ts`, zh and en in the
+  same change). A token that must never render — the missing-`EventSource`
+  marker — is a constant, not a sentence, and the component translates it.
+- **HTTP lives in `api.ts`** (same-origin `/cherry-remote/api`); a component
+  never fetches directly. Both seams are injected for tests
+  (`eventSourceFactory`, `scopeClient`), so no test stands up a server.
+- **jsdom only.** `tests/unit/ui.test.ts` and `uiScopePanel.test.ts` render the
+  page; a browser-only API needs a fake in the test, not a guard in the page.
+

package/ui/src/DeviceCard.tsx

@@ -42,6 +42,22 @@ function parseHosts(raw: string): string[] {
     .filter((entry) => entry !== '')
 }
 
+/** The dial port for one host: its own stored port, else the record-level one. */
+function dialPort(device: DeviceSummary, host: string): number {
+  return device.ports?.[host] ?? device.port
+}
+
+/**
+ * `host:port` as one readable address.
+ *
+ * An IPv6 literal contains colons, so `fe80::1:4343` reads as an ambiguous
+ * host; stored hosts are bare (`normalizeHost` strips the brackets), so the
+ * brackets are added here, for display only.
+ */
+function formatAddress(host: string, port: number): string {
+  return host.includes(':') ? `[${host}]:${port}` : `${host}:${port}`
+}
+
 export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProps): ReturnType<typeof Object> {
   const t = useT()
   const [editor, setEditor] = useState<Editor>('none')
@@ -141,6 +157,13 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
     })
   }
 
+  // The record-level `port` alone would claim every host dials it, which is
+  // false for a record whose map disagrees. `mixedPorts` decides whether the
+  // card has anything to say beyond that single number; `addressList` is the
+  // per-host truth (map value, record port as the fallback).
+  const mixedPorts = device.hosts.some((host) => dialPort(device, host) !== device.port)
+  const addressList = device.hosts.map((host) => formatAddress(host, dialPort(device, host))).join(', ')
+
   // `?? state` keeps an unknown future state transparent — the enum is the only
   // honest thing left to show for one this build has no copy for — while every
   // state it DOES know renders through the dictionary.
@@ -183,10 +206,18 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
         <dd>{device.hosts.join(', ')}</dd>
         <dt>{t('device.field.port')}</dt>
         <dd>{device.port}</dd>
+        {mixedPorts && (
+          <>
+            <dt>{t('device.field.ports')}</dt>
+            <dd className="cherry-mono">{addressList}</dd>
+          </>
+        )}
         <dt>{t('device.field.id')}</dt>
         <dd className="cherry-mono">{device.deviceId}</dd>
       </dl>
 
+      {mixedPorts && <p className="cherry-hint">{t('device.ports.hint')}</p>}
+
       {editor === 'rename' && (
         <form className="cherry-inline-form" onSubmit={saveName}>
           <label htmlFor={`name-${device.deviceId}`}>{t('device.field.name')}</label>
@@ -210,6 +241,9 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
             onChange={(event: ChangeEvent<HTMLInputElement>) => setHostsText(event.target.value)}
           />
           <span className="cherry-hint">{t('device.hosts.hint')}</span>
+          <span className="cherry-hint">
+            {t('device.ports.current')} <span className="cherry-mono">{addressList}</span>
+          </span>
           <label htmlFor={`port-${device.deviceId}`}>{t('device.field.port')}</label>
           <input
             id={`port-${device.deviceId}`}
@@ -217,6 +251,7 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
             value={portText}
             onChange={(event: ChangeEvent<HTMLInputElement>) => setPortText(event.target.value)}
           />
+          <span className="cherry-hint">{t('device.port.hint')}</span>
           <button type="submit" disabled={busy}>
             {t('device.save.addresses')}
           </button>

package/ui/src/i18n.ts

@@ -86,6 +86,10 @@ const zh: Dict = {
   'device.field.name': '设备名称',
   'device.field.hosts': '主机地址',
   'device.hosts.hint': '多个候选地址用逗号分隔（整体替换）',
+  'device.field.ports': '每地址端口',
+  'device.ports.hint': '部分候选地址的端口与上方的端口不同；在「地址维护」里改动端口会把所有候选地址改为同一端口。',
+  'device.ports.current': '当前端口映射：',
+  'device.port.hint': '保持当前值会保留各地址自己的端口；改成新值会把所有候选地址重指到该端口。',
   'device.save.name': '保存名称',
   'device.save.addresses': '保存地址',
   'device.remove.confirm': '确认移除',
@@ -236,6 +240,12 @@ const en: Dict = {
   'device.field.name': 'Device name',
   'device.field.hosts': 'Host addresses',
   'device.hosts.hint': 'Separate candidate addresses with commas (the whole list is replaced)',
+  'device.field.ports': 'Ports per address',
+  'device.ports.hint':
+    'Some candidate addresses dial a different port than the one above; changing the port in address maintenance moves every candidate address to that one port.',
+  'device.ports.current': 'Current port map:',
+  'device.port.hint':
+    'Keeping the current value preserves each address’s own port; a new value re-points every candidate address.',
   'device.save.name': 'Save name',
   'device.save.addresses': 'Save addresses',
   'device.remove.confirm': 'Confirm removal',

package/ui/src/types.ts

@@ -23,7 +23,14 @@ export const API_BASE = '/cherry-remote/api'
 /** The five device states the connection layer reports. */
 export type DeviceState = 'connected' | 'connecting' | 'offline' | 'disabled' | 'identity-mismatch'
 
-/** One device exactly as `GET /devices` returns it. Never carries a credential. */
+/**
+ * One device exactly as `GET /devices` returns it. Never carries a credential.
+ *
+ * `ports` is the per-HOST dial port map: each candidate address dials its own
+ * port, and the record-level `port` is the fallback for a host the map does not
+ * carry (a stored v4 record has an entry for every host, so the card's `??` arm
+ * only fires on a malformed map). Required — `GET /devices` always emits it.
+ */
 export interface DeviceSummary {
   deviceId: string
   displayName: string
@@ -31,6 +38,7 @@ export interface DeviceSummary {
   enabled: boolean
   hosts: string[]
   port: number
+  ports: Record<string, number>
 }
 
 /** A `PATCH /devices/:id` body; every field optional, `hosts` is whole-replace. */