dsh-cherry-bridge 0.1.11 → 0.2.1

package/src/tools.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto'
 import { DeviceUnavailableError, RpcDeadlineExceededError } from './connection.js'
 import type { DeviceConnection, DeviceState } from './connection.js'
 import type { DeviceRecord, DeviceResolution, DeviceStore } from './deviceStore.js'
-import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
+import { LastCandidateHostError, QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import {
   DEVICE_SETTLE_WAIT_MS,
   INTERACTIONS_LIST_PAGE_CLAMP,
@@ -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'
 
 /**
@@ -110,6 +111,13 @@ export interface CherryDeviceView {
   enabled: boolean
   hosts: string[]
   port: number
+  /**
+   * The addresses the operator has FORGOTTEN (issue #185): not dialed, and not
+   * re-learned from the desktop's advertisements until they are remembered.
+   * Always present on a view (empty when nothing was ever forgotten) so a
+   * caller never has to distinguish "absent" from "none".
+   */
+  forgottenHosts: string[]
 }
 
 /** The shared `{device, state}` verdict (spec §6: 设备离线). */
@@ -606,6 +614,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 +795,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". */
@@ -1152,8 +1223,11 @@ export interface CherryToolsDeps {
    * `DeviceConnection` captures its record at construction, so a pooled
    * instance can never observe an edited address or a flipped `enabled` flag.
    *
-   * `cherry_unpair` is the other caller: it evicts (drop + close) and then
-   * removes the archive entry, so no live socket outlives its record.
+   * `cherry_unpair` evicts (drop + close) and then removes the archive entry,
+   * so no live socket outlives its record, and `cherry_devices`' `forget` /
+   * `remember` actions evict ON A CHANGE for the same reason: a pooled
+   * connection captured the pre-write record, so a forget that only rewrote the
+   * archive would keep dialing the address (and locally re-learning it).
    */
   evict(deviceId: string): void | Promise<void>
   /**
@@ -1295,6 +1369,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).
@@ -1529,6 +1652,59 @@ function optionalString(value: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined
 }
 
+/**
+ * The `hosts` argument of `cherry_devices`' write actions (issue #185): a
+ * non-empty list of non-empty host names, with no case-variant duplicate.
+ *
+ * Each rule is a state the store would have to interpret: an empty name can
+ * never match a dialed host, and two spellings of one host would make "is this
+ * address forgotten?" depend on which entry a comparison hit first. Values are
+ * TRIMMED here (the model-facing surface is where a stray space is caught);
+ * the archive then stores the spelling it already had for a dialed host.
+ */
+function hostListArgument(value: unknown): string[] | Record<string, unknown> {
+  if (!Array.isArray(value) || value.length === 0) {
+    return { error: 'invalid-hosts', message: '`hosts` must be a non-empty array of host names' }
+  }
+  const hosts: string[] = []
+  const seen = new Set<string>()
+  for (const entry of value) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+      return { error: 'invalid-hosts', message: '`hosts` entries must be non-empty strings' }
+    }
+    let host = entry.trim()
+    // The archive stores BARE hosts, and the PATCH path unwraps a bracketed
+    // IPv6 literal (`normalizeHost`). This face must agree: a mark for
+    // `[fd00::1]` would never match the `fd00::1` a dial or an advertisement
+    // carries, so it would be a mark with no effect. The ceiling mirrors the
+    // PATCH path's `HOST_MAX`.
+    if (host.startsWith('[') && host.endsWith(']')) {
+      try {
+        new URL(`http://${host}/`)
+      } catch {
+        return {
+          error: 'invalid-hosts',
+          message: `\`hosts\` entry "${host}" is not a valid IPv6 literal`,
+        }
+      }
+      host = host.slice(1, -1)
+    }
+    if (host.length > 256) {
+      return { error: 'invalid-hosts', message: '`hosts` entry exceeds 256 characters' }
+    }
+    const key = host.toLowerCase()
+    if (seen.has(key)) {
+      return {
+        error: 'invalid-hosts',
+        message: `\`hosts\` names "${host}" more than once (host names are case-insensitive)`,
+      }
+    }
+    seen.add(key)
+    hosts.push(host)
+  }
+  return hosts
+}
+
 /**
  * The peer's `agent.messages.send` refusal for a STALE `expectedIdleRevision`,
  * in the exact shape Cherry Studio answers it: a `rejected` receipt whose
@@ -1757,7 +1933,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 +2587,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
@@ -2599,25 +2792,100 @@ export class CherryToolEngine {
       description:
         'List every paired Cherry Studio desktop with its connection state ' +
         '(connected/connecting/offline/disabled/identity-mismatch). An optional `device` ' +
-        'narrows the list to one device (display name prefix or deviceId).',
+        'narrows the list to one device (display name prefix or deviceId). ' +
+        '`action: "forget"` removes the named `hosts` from that device\'s dial candidates AND ' +
+        'stops the desktop\'s advertisements from adding them back; `action: "remember"` lifts ' +
+        'that mark, so the next handshake may learn them again. Both write actions require ' +
+        '`device` and `hosts`.',
       parameters: {
         type: 'object',
         properties: {
           device: { type: 'string', description: 'Optional device selector: exact deviceId, or a unique prefix of a deviceId or display name.' },
+          action: {
+            type: 'string',
+            enum: ['list', 'forget', 'remember'],
+            description:
+              'What to do: `list` (the default) reads the devices; `forget`/`remember` edit ONE ' +
+              "device's forgotten addresses and require `device` and `hosts`.",
+          },
+          hosts: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              'For `forget`/`remember`: the host names to act on, matched case-insensitively. ' +
+              '`forget` refuses to remove the last remaining address.',
+          },
         },
         additionalProperties: false,
       },
       execute: async (args) => {
+        const action = optionalString(args['action']) ?? 'list'
+        if (action !== 'list' && action !== 'forget' && action !== 'remember') {
+          return {
+            error: 'invalid-action',
+            message: '`action` accepts exactly "list", "forget" or "remember"',
+          } satisfies Record<string, unknown>
+        }
         const selector = optionalString(args['device'])
-        const quarantined = this.#quarantineVerdict()
-        if (quarantined !== undefined) return quarantined
+        if (action === 'list') {
+          const quarantined = this.#quarantineVerdict()
+          if (quarantined !== undefined) return quarantined
+          if (selector === undefined) {
+            const records = this.#deps.store.list()
+            return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) }
+          }
+          const selected = this.#selectRecords(selector)
+          if (!Array.isArray(selected)) return selected
+          return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) }
+        }
         if (selector === undefined) {
-          const records = this.#deps.store.list()
-          return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) }
+          return {
+            error: 'device-required',
+            message:
+              '`action` "forget"/"remember" needs `device`: a selector that names exactly one device',
+          } satisfies Record<string, unknown>
         }
+        const hosts = hostListArgument(args['hosts'])
+        if (!Array.isArray(hosts)) return hosts
+        const quarantined = this.#quarantineVerdict()
+        if (quarantined !== undefined) return quarantined
         const selected = this.#selectRecords(selector)
         if (!Array.isArray(selected)) return selected
-        return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) }
+        const record = selected[0]!
+        let removed: string[] = []
+        let marked: string[] = []
+        let restored: string[] = []
+        try {
+          if (action === 'forget') {
+            ;({ removed, marked } = this.#deps.store.forgetEndpoints(record.deviceId, hosts))
+          } else {
+            ;({ restored } = this.#deps.store.rememberEndpoints(record.deviceId, hosts))
+          }
+        } catch (error) {
+          if (error instanceof LastCandidateHostError) {
+            return {
+              error: 'last-address',
+              device: record.deviceId,
+              message: error.message,
+            } satisfies Record<string, unknown>
+          }
+          throw error
+        }
+        const changed = removed.length > 0 || marked.length > 0 || restored.length > 0
+        // ADDRESS MAINTENANCE reaches the LIVE connection, exactly like the HTTP
+        // PATCH's eviction: a pooled `DeviceConnection` captures its record at
+        // construction, so an instance built before this write would keep
+        // dialing the forgotten host and locally re-adding it on every
+        // reconnect. Evicting drops that socket and makes the next `connect()`
+        // rebuild from the archive we just wrote.
+        if (changed) await this.#deps.evict(record.deviceId)
+        // The resolved record is STALE (hosts/forgottenHosts moved), so the
+        // view is built from the archive's current row, never from the object
+        // the selector handed us.
+        const fresh = this.#deps.store.list().find((entry) => entry.deviceId === record.deviceId)
+        if (fresh === undefined) return this.#notFoundVerdict(selector)
+        const device = await this.#deviceView(fresh)
+        return action === 'forget' ? { device, removed, marked } : { device, restored }
       },
     })
   }
@@ -2684,6 +2952,7 @@ export class CherryToolEngine {
       enabled: record.enabled,
       hosts: record.hosts,
       port: record.port,
+      forgottenHosts: record.forgottenHosts ?? [],
     }
   }
 
@@ -3018,15 +3287,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 +3620,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 +4097,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 +6858,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 +6972,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 +7054,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,44 @@
+# 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.
+- **A run always ends, and the deadline is not a verdict.** The server publishes
+  a terminal stage on every outcome, but the stream has no replay, so one lost
+  frame would otherwise park the wizard on 「配对进行中」 with the submit button
+  disabled and no cancel. The run deadline (`runLifetimeMs`, same injection
+  style as `codeLifetimeMs`) restores the form and re-reads the device list;
+  its copy points at that list instead of claiming failure, and it keeps
+  `claimId` so a terminal frame that arrives late still wins. Arm it on the
+  `waiting` phase only — never at mount.
+- **The bundle carries the SOURCE COMMENTS.** `ui/vite.config.ts` sets
+  `minify: false`, so the docblocks that hold most of this page's reasoning ship
+  inside `lib/client.js`: a comment-only edit in `ui/src/**` changes the
+  artifact's bytes and needs the rebuild in the same commit. Two follow-ons from
+  that: `artifactFreshness` compares against `git show HEAD:<path>`, so it only
+  goes green once the rebuild is COMMITTED — running the full suite before
+  committing reports it red for the same reason its sibling case ("neither check
+  mutates the committed artifacts") is red. Neither red is a real failure.
+- **A per-host action is INERT while a whole-list editor is open.** The address
+  editor's draft is sacred (the card does not reseed it while an editor is
+  open), so a 忘记/恢复 chosen under it would be re-sent by the next 保存地址 — and
+  that PATCH clears the mark for any host it names. Hence
+  `disabled={busy || editor === 'address'}` on both controls, pinned by `#204m`.
+- **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/App.tsx

@@ -20,8 +20,9 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
 import { DeviceCard } from './DeviceCard'
 import { PairingWizard } from './PairingWizard'
 import { ToolScopePanel } from './ToolScopePanel'
-import { listDevices } from './api'
+import { REQUEST_TIMEOUT, listDevices } from './api'
 import { useT } from './i18n'
+import type { T } from './i18n'
 import { API_BASE } from './types'
 import type {
   DeviceState,
@@ -40,6 +41,8 @@ export interface AppProps {
   eventSourceFactory?: EventSourceFactory
   /** Transient verification-code lifetime, forwarded to the wizard. */
   codeLifetimeMs?: number
+  /** Run deadline (the exit for a lost terminal frame), forwarded to the wizard. */
+  runLifetimeMs?: number
   /**
    * The scope panel's HTTP seam. Defaults to the real same-origin client;
    * injected by tests in the same style as `eventSourceFactory`, so no test has
@@ -69,6 +72,19 @@ const defaultEventSourceFactory: EventSourceFactory = (url) => {
  */
 const EVENT_SOURCE_UNAVAILABLE = 'event-source-unavailable'
 
+/**
+ * One description for a cause, shared by the two catches below so they cannot
+ * drift. Two markers get the dictionary's own sentence — the missing
+ * `EventSource` and a request that never answered (`api.ts`'s ceiling) — because
+ * both are INTERNAL tokens that must never render; everything else is the
+ * foreign message, interpolated verbatim as data.
+ */
+function describeCause(t: T, cause: unknown): string {
+  if (cause instanceof Error && cause.message === EVENT_SOURCE_UNAVAILABLE) return t('app.eventSourceUnavailable')
+  if (cause instanceof Error && cause.message === REQUEST_TIMEOUT) return t('app.error.timeout')
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
 /** Parses one SSE frame payload, ignoring a malformed one rather than crashing. */
 function parseFrame<T>(data: string): T | undefined {
   try {
@@ -81,6 +97,7 @@ function parseFrame<T>(data: string): T | undefined {
 export function App({
   eventSourceFactory = defaultEventSourceFactory,
   codeLifetimeMs,
+  runLifetimeMs,
   scopeClient,
 }: AppProps): ReturnType<typeof Object> {
   const t = useT()
@@ -101,13 +118,7 @@ export function App({
       // The opener's own token means "no EventSource here", which has a
       // sentence of its own in both dictionaries; anything else is a foreign
       // message and is interpolated verbatim (data, not copy).
-      setError(
-        cause instanceof Error && cause.message === EVENT_SOURCE_UNAVAILABLE
-          ? t('app.eventSourceUnavailable')
-          : cause instanceof Error
-            ? cause.message
-            : String(cause),
-      )
+      setError(describeCause(t, cause))
       return undefined
     }
 
@@ -142,7 +153,7 @@ export function App({
         setError(undefined)
       },
       (cause: unknown) => {
-        setError(cause instanceof Error ? cause.message : String(cause))
+        setError(describeCause(t, cause))
         setListed(true)
       },
     )
@@ -211,6 +222,7 @@ export function App({
         subscribed={subscribed}
         progress={progress}
         {...(codeLifetimeMs === undefined ? {} : { codeLifetimeMs })}
+        {...(runLifetimeMs === undefined ? {} : { runLifetimeMs })}
         onRunStart={startRun}
         onSettled={onSettled}
       />
@@ -221,7 +233,11 @@ export function App({
 
       <section className="cherry-panel" aria-labelledby="cherry-devices-title">
         <h3 id="cherry-devices-title">{t('app.devices.heading')}</h3>
-        {sorted.length === 0 && (
+        {/* Three states, not two: the list is EMPTY only once a read said so.
+            After a failed read it is UNKNOWN, and claiming 「暂无已配对设备」 beside
+            the error that says the read failed would contradict that error — so the
+            error line speaks alone. */}
+        {sorted.length === 0 && error === undefined && (
           <p className="cherry-hint">{listed ? t('app.devices.empty') : t('app.devices.loading')}</p>
         )}
         <ul className="cherry-cards">