dsh-cherry-bridge 0.1.8 → 0.1.10

package/src/tools.ts

@@ -4,6 +4,7 @@ import type { DeviceConnection, DeviceState } from './connection.js'
 import type { DeviceRecord, DeviceResolution, DeviceStore } from './deviceStore.js'
 import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import {
+  DEVICE_SETTLE_WAIT_MS,
   INTERACTIONS_LIST_PAGE_CLAMP,
   LIST_PAGE_CLAMP,
   MAX_RESUME_TOKEN_CHARS,
@@ -11,6 +12,7 @@ import {
 } from './defaults.js'
 import { JsonRpcRequestError, RequestTimeoutError } from './rpc/jsonRpcClient.js'
 import { ContentReadGate } from './contentGate.js'
+import { truncateErrorMessage } from './diagnostics.js'
 import type { ReadResult, SessionSubscriptions } from './subscriptions.js'
 import { PairingError } from './pairing.js'
 import type { PairingErrorKind } from './pairing.js'
@@ -298,12 +300,81 @@ export interface CherryReadPart {
   byteLength?: string
 }
 
+/**
+ * The peer's verdict on a FAILED message, narrowed to what a caller can act on.
+ *
+ * The wire carries more (`failure.failure.source`, `context.responseBody`, the
+ * provider's status code); none of it is projected. `cherry_read` is a text
+ * channel for the conversation, and the provider's raw error body is neither
+ * conversation nor the caller's business — the peer already classified the
+ * cause into `reasonCode`, which is the actionable half.
+ */
+export interface CherryReadFailure {
+  /**
+   * The peer's classification (`provider_unavailable`, `rate_limit`,
+   * `context_length`, … — the protocol's versioned vocabulary).
+   *
+   * Relayed as a SHAPE-checked string rather than matched against a closed
+   * enum: the vocabulary belongs to the peer and grows with it, and relabelling
+   * a new code `'unknown'` would hide a real cause behind a value that means
+   * "the peer could not classify". Absent or unusable values become
+   * `'unknown'`, which is exactly what the contract uses for that case.
+   */
+  reasonCode: string
+  /** Whether the peer judged a retry of the same work worthwhile. */
+  retryable: boolean
+  /**
+   * The peer's one-line explanation, bounded by the diagnostics error cap
+   * (200 characters) with a `…[truncated]` marker when it was cut.
+   */
+  message: string
+}
+
+/** `provider_unavailable`-shaped: lowercase words separated by underscores. */
+const REASON_CODE_SHAPE = /^[a-z][a-z0-9_]{1,63}$/
+
+/**
+ * Projects the wire's `failure` object (present on `status: 'error'` messages)
+ * into {@link CherryReadFailure}, or `undefined` when there is none.
+ *
+ * Deliberately tolerant of a malformed payload: a peer that sends
+ * `failure: { retryable: false }` with no nested record still yields a usable
+ * verdict (`reasonCode: 'unknown'`, empty message) instead of failing the whole
+ * read — the message's TEXT is already in hand, and losing it over a metadata
+ * field would trade the content for the annotation. A degenerate object
+ * (`{}`, `[]`) projects the same way: the peer DID attach a verdict, just an
+ * empty one, and saying so is more honest than reporting "no verdict". Only an
+ * ABSENT or non-object `failure` yields `undefined`.
+ */
+export function projectMessageFailure(raw: Record<string, unknown>): CherryReadFailure | undefined {
+  const failure = raw['failure']
+  if (typeof failure !== 'object' || failure === null) return undefined
+  const record = failure as Record<string, unknown>
+  const nested = record['failure']
+  const detail = typeof nested === 'object' && nested !== null ? (nested as Record<string, unknown>) : {}
+  const rawReason = detail['reasonCode']
+  const reasonCode =
+    typeof rawReason === 'string' && REASON_CODE_SHAPE.test(rawReason) ? rawReason : 'unknown'
+  const rawMessage = record['message']
+  return {
+    reasonCode,
+    retryable: record['retryable'] === true,
+    message: truncateErrorMessage(typeof rawMessage === 'string' ? rawMessage : ''),
+  }
+}
+
 /** One message in a `cherry_read` snapshot. */
 export interface CherryReadMessage {
   messageId: string
   revision: string
   role: string
   status: string
+  /**
+   * Present exactly when the peer sent a `failure` for this message (in
+   * practice: `status: 'error'`). A successful message never carries it, so a
+   * caller can test for the key rather than compare `status` strings.
+   */
+  failure?: CherryReadFailure
   parts: CherryReadPart[]
   /**
    * Present only when this message's parts could NOT all be read: the safety
@@ -1030,6 +1101,14 @@ export interface CherryToolsDeps {
    * this one subscribes the engine to ONE device's transitions.
    */
   watchDeviceState?: (deviceId: string, cb: (state: DeviceState) => void) => void
+  /**
+   * How long a device tool waits for an establishment attempt that is ALREADY
+   * IN FLIGHT (`state === 'connecting'`) before judging the device (issue #99).
+   *
+   * OPTIONAL: production omits it and takes {@link DEVICE_SETTLE_WAIT_MS}; test
+   * rigs drive it down so the bounded case needs no real five seconds.
+   */
+  deviceSettleWaitMs?: number
 }
 
 // ---------------------------------------------------------------------------
@@ -1206,6 +1285,87 @@ function withIdempotencyHint(error: unknown): unknown {
   return error
 }
 
+/**
+ * The phrase this hint leaves behind, so applying it twice reads once. A phrase
+ * from the ADVICE rather than the advice itself, because the wait clause varies
+ * with the peer's `retryAfterMs`; matching the peer's own text would match every
+ * rate-limit refusal, hinted or not.
+ */
+const RATE_LIMIT_HINT_MARK = 'refuses BEFORE dispatch'
+
+/**
+ * How long a refused COMMAND was asked to wait, or undefined when the peer sent
+ * nothing a caller can act on.
+ *
+ * `<= 0` counts as absent rather than "retry immediately": a zero delay is
+ * noise in an error message, and the desktop clamps its own value to `>= 1`
+ * (`RemoteAccessService.ts`). CEILED so a fractional remainder is never
+ * reported as a delay shorter than the one the peer asked for.
+ */
+function rateLimitedWaitMs(error: Error): number | undefined {
+  if (!(error instanceof JsonRpcRequestError)) return undefined
+  const data = error.data
+  if (!isRecord(data)) return undefined
+  const raw = data['retryAfterMs']
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) return undefined
+  return Math.ceil(raw)
+}
+
+/**
+ * The recovery advice appended to a command's `RATE_LIMITED` refusal (desktop
+ * >= 2.1.7; see the transport-loss section of `connection.ts`), issue #109.
+ *
+ * Two facts decide the retry and NEITHER survives the tool boundary on its own:
+ *
+ *  - **THIS attempt was not applied.** The desktop refuses BEFORE dispatch — its
+ *    gateway calls `remote.rpc.refuse(input, …)` INSTEAD of `receive(input)` —
+ *    so, unlike a reply lost on a dead link, this is a certain non-outcome.
+ *    That is what makes a retry safe, and it is why the SAME `commandId` may be
+ *    reused: nothing reached the peer's command ledger, so no
+ *    `IDEMPOTENCY_CONFLICT` is waiting for the retry. The sentence says THIS
+ *    attempt, not "the command", because an earlier attempt under the same
+ *    `commandId` may itself have lost its reply after dispatch: the retry advice
+ *    is right in that sequence too (the ledger replays the original receipt),
+ *    but "never landed" would be a claim about a run this error knows nothing
+ *    of.
+ *  - **How long the peer asked us to wait** — `retryAfterMs`, derived from its
+ *    own 1 s window and already on the error we are holding. The wait clause
+ *    comes BEFORE the retry blessing, so a skimming reader cannot take "safe to
+ *    retry" and act on it without waiting.
+ *
+ * The cause is named because at the DEFAULT pacing this refusal is unreachable:
+ * the desktop's counter is per SOCKET (locals inside its `run()` loop, one per
+ * accepted connection) and we pace 32/s shared / 256/s content against its
+ * 64-or-256/s shared and 512/s content lines. Seeing one at all therefore
+ * normally means the configured budget is above the peer's allowance — the knob
+ * to look at, not a transient blip — and a caller told to "retry later" without
+ * that pointer would keep retrying into the same wall. Only the 256/s figure is
+ * quoted: this refusal exists only from 2.1.7, so the older 64/s line cannot be
+ * the one an operator has to compare against.
+ *
+ * Like {@link withIdempotencyHint} this only ever EXTENDS `message`: the reason,
+ * the `data` and the `JsonRpcRequestError` identity are the peer's, and one
+ * command is still never replayed (the advice is for the CALLER's retry).
+ */
+export function withRateLimitHint(error: unknown): unknown {
+  if (!(error instanceof Error)) return error
+  if (failureReason(error) !== 'RATE_LIMITED') return error
+  if (error.message.includes(RATE_LIMIT_HINT_MARK)) return error
+  const waitMs = rateLimitedWaitMs(error)
+  const advice = [
+    'this attempt was not applied: the desktop refuses BEFORE dispatch, so nothing reached its ' +
+      'command ledger',
+    waitMs === undefined
+      ? 'A retry is safe, and it may reuse the SAME commandId'
+      : `Wait about ${waitMs} ms first (the peer's retryAfterMs); a retry is then safe, and it may ` +
+        'reuse the SAME commandId',
+    'The default budget (32/s) does not come close to the desktop\'s allowance, so a refusal ' +
+      'normally means `rateBudgetPerSecond` was raised too far (2.1.7+ allows 256/s shared)',
+  ]
+  error.message = `${error.message} — ${advice.join('. ')}.`
+  return error
+}
+
 function optionalString(value: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined
 }
@@ -1617,10 +1777,14 @@ class CherryToolEngine {
    * ⑤): the candidate list is the answer. A MISS is a verdict too — see
    * {@link CherryDeviceNotFound} — and it carries the ids the caller could have
    * meant so the answer stays actionable.
+   *
+   * ASYNC because of the `connecting` wait below: the pool dials on first touch
+   * and on every reconnect, so a tool called in that window used to be refused
+   * for a connection that comes up a moment later (issue #99).
    */
-  #resolve(
+  async #resolve(
     device: string,
-  ): ResolvedDevice | CherryAmbiguousDevice | CherryDeviceNotFound | CherryDeviceUnavailable {
+  ): Promise<ResolvedDevice | CherryAmbiguousDevice | CherryDeviceNotFound | CherryDeviceUnavailable> {
     const resolution: DeviceResolution = this.#deps.store.resolve(device)
     if ('ambiguous' in resolution) {
       return { error: 'ambiguous-device', device, candidates: resolution.ambiguous }
@@ -1634,10 +1798,21 @@ class CherryToolEngine {
     // transition this exists for can land while the device is already offline,
     // and the watch must be in place from the first call either way.
     this.#watchConnection(resolution.deviceId, connection)
-    if (connection.state !== 'connected') {
+    // `connecting` is an attempt IN FLIGHT, not a verdict (issue #99): the pool
+    // dials on first touch and on every reconnect, so refusing here used to
+    // report a failure about a connection that comes up a moment later. Wait for
+    // that attempt — bounded, and never starting one — then judge the state it
+    // settled on. Every other non-connected state is answered at once: no wait
+    // can change `offline` (parked in backoff), `disabled` or
+    // `identity-mismatch`, and waiting would only delay the answer.
+    const state =
+      connection.state === 'connecting'
+        ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? DEVICE_SETTLE_WAIT_MS)
+        : connection.state
+    if (state !== 'connected') {
       // The established Task 5 shape: the tool never dials implicitly, and the
       // caller gets the same `{device, state}` verdict the RPC layer throws.
-      return { error: 'device-unavailable', device: resolution.deviceId, state: connection.state }
+      return { error: 'device-unavailable', device: resolution.deviceId, state }
     }
     return { record: resolution, connection }
   }
@@ -1675,6 +1850,10 @@ class CherryToolEngine {
   /**
    * Resolve-or-verdict: every non-`cherry_devices` tool needs a live link.
    *
+   * `connecting` is waited out inside {@link #resolve} first, so the
+   * `DeviceUnavailableError` below is only ever raised for a state the wait
+   * could not improve on (bounded by `deviceSettleWaitMs`).
+   *
    * The failure faces are deliberately DIFFERENT (controller ruling ⑤): an
    * ambiguous selector and a MISS are ANSWERS — the candidate list, or the
    * known ids, returned in band, because the caller can act on them — while a
@@ -1687,8 +1866,8 @@ class CherryToolEngine {
    * `cherry_devices` does not come through this method — it goes through
    * {@link #selectRecords}, which returns the verdict in band.
    */
-  #requireConnection(device: string): ResolvedDevice | CherryAmbiguousDevice {
-    const resolved = this.#resolve(device)
+  async #requireConnection(device: string): Promise<ResolvedDevice | CherryAmbiguousDevice> {
+    const resolved = await this.#resolve(device)
     if (!this.#isVerdict(resolved)) return resolved
     if (resolved.error === 'ambiguous-device') return resolved
     if (resolved.error === 'not-found') {
@@ -1710,14 +1889,13 @@ class CherryToolEngine {
    * replace it with a weaker, wrong one — a miss under a READ-ONLY archive
    * would describe a store that still holds a valid token as "no such device".
    */
-  #linkOr(
-    device: string,
-  ):
+  async #linkOr(device: string): Promise<
     | { link: ResolvedDevice; verdict?: undefined }
-    | { link?: undefined; verdict: CherryAmbiguousDevice | CherryArchiveQuarantined } {
+    | { link?: undefined; verdict: CherryAmbiguousDevice | CherryArchiveQuarantined }
+  > {
     const quarantined = this.#quarantineVerdict()
     if (quarantined !== undefined) return { verdict: quarantined }
-    const resolved = this.#requireConnection(device)
+    const resolved = await this.#requireConnection(device)
     if ('error' in resolved) return { verdict: resolved }
     return { link: resolved }
   }
@@ -2172,11 +2350,12 @@ class CherryToolEngine {
         const quarantined = this.#quarantineVerdict()
         if (quarantined !== undefined) return quarantined
         if (selector === undefined) {
-          return { devices: this.#deps.store.list().map((record) => this.#deviceView(record)) }
+          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: selected.map((record) => this.#deviceView(record)) }
+        return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) }
       },
     })
   }
@@ -2208,7 +2387,9 @@ class CherryToolEngine {
   }
 
   /**
-   * One device's view WITHOUT dialing.
+   * One device's view WITHOUT dialing — but after waiting out an attempt that is
+   * already in flight, exactly as {@link #resolve} does, so a cold-start row
+   * does not present a transient `connecting` as the device's answer.
    *
    * A disabled record is authoritative: the pooled connection is constructed
    * with its own `record.enabled` snapshot and reports `disabled` only once
@@ -2216,11 +2397,18 @@ class CherryToolEngine {
    * for a device whose connection was never started. Everything else falls back
    * to the connection's own CLOSED state set.
    */
-  #deviceView(record: DeviceRecord): CherryDeviceView {
+  async #deviceView(record: DeviceRecord): Promise<CherryDeviceView> {
     let state: DeviceState = record.enabled ? 'offline' : 'disabled'
     if (record.enabled) {
       try {
-        state = this.#deps.connect(record.deviceId).state
+        const connection = this.#deps.connect(record.deviceId)
+        // Same transient as {@link #resolve} (issue #99): a row rendered while
+        // the first dial is in flight must not present `connecting` as the
+        // device's answer. Bounded, and only for an attempt already running.
+        state =
+          connection.state === 'connecting'
+            ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? DEVICE_SETTLE_WAIT_MS)
+            : connection.state
       } catch (error) {
         // A device that cannot even be resolved to a connection still deserves a
         // truthful row; `offline` is the fallback verdict.
@@ -2268,7 +2456,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const binding: ListResumeBinding = { method: 'agent.agents.list', deviceId: record.deviceId, params: {} }
@@ -2312,7 +2500,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const agentId = requiredString(args, 'agentId')
@@ -2367,7 +2555,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const agentId = optionalString(args['agentId'])
@@ -2413,7 +2601,11 @@ class CherryToolEngine {
         'are deliberately not fetched into a text channel. Messages come NEWEST-first, so the ' +
         'first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts ' +
         'inside a retained message\'s parts; a message whose own parts could not be fully read ' +
-        'carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. The ' +
+        'carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A ' +
+        'failed message (`status: "error"`) may carry `failure: {reasonCode, retryable, ' +
+        'message}` when the peer sent one — its classification, whether it judged a retry ' +
+        'worthwhile, and a bounded summary; the peer\'s `source` and `context.responseBody` ' +
+        'are never projected. The ' +
         'answer is ALSO bounded by an output budget: `truncated` with `truncationReason: ' +
         '"aggregate-bytes"` means the walk stopped because the result reached its size limit, ' +
         'not because `limit` was reached — raising `limit` does NOT reach the messages left out ' +
@@ -2466,7 +2658,7 @@ class CherryToolEngine {
         // a malformed cursor, which would present the newest page again as
         // "continued history" — the refusal has to be ours.
         const resume = parseMessageResume(args['messagesResumeCursor'])
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -2742,11 +2934,13 @@ class CherryToolEngine {
     // stays absent rather than claiming a zero.
     const unavailableParts = parts.filter((part) => part.unavailable !== undefined).length
     const incomplete = unavailableParts > 0 || partsTruncated !== undefined
+    const failure = projectMessageFailure(raw)
     return {
       messageId,
       revision,
       role: String(raw['role'] ?? ''),
       status: String(raw['status'] ?? ''),
+      ...(failure === undefined ? {} : { failure }),
       parts,
       // A circuit-broken part list advertises itself: the caller can see that
       // this message is incomplete and that later parts are still unread, so
@@ -2930,13 +3124,23 @@ class CherryToolEngine {
    *    back a snapshot that looks complete while containing content the peer
    *    never certified. That is worse than an error: the caller cannot tell it
    *    apart from a good read. It keeps failing loudly.
+   *  - **NOT degradable — a RATE LIMIT.** A `RATE_LIMITED` refusal is
+   *    SESSION-wide, not part-specific: the peer refused the arrival, it did not
+   *    fail to serve THIS part. Degrading would hand back a "complete" message
+   *    whose text is empty for a reason the caller could act on (wait and ask
+   *    again) — and if one slice is refused the others will be too, so the
+   *    snapshot would be missing precisely what was requested. The connection
+   *    already waited out `retryAfterMs` and replayed the slice ONCE, so a
+   *    second refusal is a real failure and the whole read fails with it.
    *
    * The discriminator is the DIGEST CHECK specifically, which is why
    * {@link CherryToolEngine.#readExternalized} marks it: matching on message
-   * text would break the moment the wording changed.
+   * text would break the moment the wording changed. The rate-limit arm keys on
+   * the peer's REASON, never on wording.
    */
   #degradableReadFailure(error: unknown): boolean {
-    return !(error instanceof ContentIntegrityError)
+    if (error instanceof ContentIntegrityError) return false
+    return failureReason(error) !== 'RATE_LIMITED'
   }
 
   /**
@@ -3201,7 +3405,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3319,7 +3523,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
 
@@ -3440,7 +3644,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3671,7 +3875,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3835,7 +4039,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3945,7 +4149,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -4051,7 +4255,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -4293,12 +4497,12 @@ class CherryToolEngine {
    * subscription failures still reject this call: the two surfaces stay
    * distinct all the way to the caller (spec §6).
    *
-   * ONE exception, and it is a HINT rather than a translation: the peer's
+   * TWO exceptions, and both are HINTS rather than translations: the peer's
    * `IDEMPOTENCY_CONFLICT` — the same `commandId` re-used with a DIFFERENT body
-   * — carries the §6 recovery advice on the rethrown error (see
-   * {@link withIdempotencyHint}). The reason, the `data` and the failure
-   * currency are untouched; only the prose a caller reads grows the actionable
-   * half.
+   * — and its `RATE_LIMITED` refusal (desktop >= 2.1.7) each carry their
+   * recovery advice on the rethrown error (see {@link withIdempotencyHint} /
+   * {@link withRateLimitHint}). The reason, the `data` and the failure currency
+   * are untouched; only the prose a caller reads grows the actionable half.
    */
   async #command(
     connection: DeviceConnection,
@@ -4308,7 +4512,7 @@ class CherryToolEngine {
     try {
       return (await connection.rpc.request(method, params)) as Record<string, unknown>
     } catch (error) {
-      throw withIdempotencyHint(error)
+      throw withRateLimitHint(withIdempotencyHint(error))
     }
   }
 

package/ui/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Cherry Studio 互联 — 开发预览</title>
+    <title>Cherry 互联 — 开发预览</title>
   </head>
   <body>
     <!--

package/ui/src/i18n.ts

@@ -57,7 +57,7 @@ export const LOCALE_IDS: readonly LocaleId[] = ['zh', 'en']
  */
 const zh: Dict = {
   // -- app shell ------------------------------------------------------------
-  'app.title': 'Cherry Studio 互联',
+  'app.title': 'Cherry 互联',
   'app.subtitle':
     '通过远程传输把本机 DeepSeek Harness 连接到 Cherry Studio 桌面端；设备档案保存在插件数据目录，页面不接触任何凭据。',
   // The one string that used to reach a Chinese page in English (App.tsx's
@@ -210,7 +210,7 @@ const zh: Dict = {
  */
 const en: Dict = {
   // -- app shell ------------------------------------------------------------
-  'app.title': 'Cherry Studio Bridge',
+  'app.title': 'Cherry Bridge',
   'app.subtitle':
     'Connect this machine’s DeepSeek Harness to a Cherry Studio desktop over the remote transport. Device records live in the plugin data directory; this page never touches a credential.',
   'app.eventSourceUnavailable': 'EventSource is unavailable in this environment',