dsh-cherry-bridge 0.1.7 → 0.1.9

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,
@@ -391,9 +392,15 @@ export interface CherryReadSnapshot {
    *
    * Present exactly when `truncated` is true and a stop point can be named
    * honestly; because the walk runs newest-first, it marks OLDER messages as
-   * still unread — the only direction a truncation leaves behind. It is ABSENT
-   * when the walk reached the peer's last page having returned everything it
-   * collected: there is nothing older left to name, and no marker is invented.
+   * still unread — the only direction a truncation leaves behind.
+   *
+   * IT IS ABSENT IN TWO OPPOSITE CASES, and `truncated` is what tells them
+   * apart: a COMPLETE walk (`truncated: false` — nothing older left), and a
+   * TRUNCATED walk whose stop point could not be named (`truncated: true` plus
+   * `truncationReason` — older messages still unread). The absence therefore
+   * never means "nothing older left" on its own. WHICH stops can be named is
+   * decided in ONE place ({@link messageResumeToken}); the refusal cases are not
+   * restated here.
    *
    * WHAT REACHES THE UNREAD MESSAGES DEPENDS ON THE REASON. A `'limit'` stop was
    * the caller's own ceiling: raise `limit`, or resume with this token to walk
@@ -403,6 +410,12 @@ export interface CherryReadSnapshot {
    * messages are reached. From the resume point `limit` bounds how many messages
    * ONE answer carries, so a long history is walked in successive answers, each
    * carrying the next stop point.
+   *
+   * WITH NO TOKEN NAMED, the reason is all the caller has: a `'limit'` stop is
+   * still reachable by widening `limit`; a `'safety-bound'` stop is the internal
+   * circuit breaker, which no wider `limit` moves; and an `'aggregate-bytes'`
+   * stop has no remedy in that answer at all — the budget, not the ceiling, is
+   * what stopped it. The loss is stated rather than repaired.
    */
   messagesResumeCursor?: string
 }
@@ -447,10 +460,19 @@ export interface CherryMessageWalkVerdict {
    * `cursor:<peer position>` when the whole collected window was returned;
    * `after:<last returned message id>` when the byte stop happened INSIDE that
    * window, because the peer's position sits past messages this walk trimmed
-   * and `AgentMessage` carries no `createdAt` to synthesise a closer one. The
-   * token is OMITTED when nothing older is left to name (the walk reached the
-   * peer's last page having returned everything it collected) — absence says
-   * "no marker", `messagesTruncated` still says the walk was cut.
+   * and `AgentMessage` carries no `createdAt` to synthesise a closer one.
+   *
+   * IT IS ABSENT IN TWO OPPOSITE CASES, and `messagesTruncated` is what tells
+   * them apart: a COMPLETE walk (`messagesTruncated` absent or false — nothing
+   * older left), and a TRUNCATED walk whose stop point could not be named
+   * (`messagesTruncated: true` plus `messagesTruncationReason` — older history
+   * still unread). The absence never means "nothing older left" on its own.
+   * WHICH stops can be named is decided in ONE place
+   * ({@link messageResumeToken}) and is the same rule as
+   * {@link CherryReadSnapshot.messagesResumeCursor}. THE REMEDY IS NOT THE SAME
+   * ON THIS FACE: a `'limit'` stop here is the walk's own fixed message
+   * allowance — these tools take no `limit` argument — so the way further is
+   * `cherry_read`, which also carries no deadline.
    */
   messagesResumeCursor?: string
 }
@@ -1009,6 +1031,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
 }
 
 // ---------------------------------------------------------------------------
@@ -1596,10 +1626,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 }
@@ -1613,10 +1647,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 }
   }
@@ -1654,6 +1699,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
@@ -1666,8 +1715,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') {
@@ -1689,14 +1738,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 }
   }
@@ -2100,19 +2148,31 @@ class CherryToolEngine {
   #listPage(page: CherryPage<Record<string, unknown>>, binding: ListResumeBinding): Record<string, unknown> {
     // A position this face would REFUSE is not a position it may name. The
     // round-trip symmetry (a token a tool emits is a token that tool accepts) is
-    // the whole point of the token, so a peer answering `nextCursor: ''` — or a
-    // position carrying whitespace/control characters, which `mangledRemainder`
-    // rejects on the way back — gets NO token; `truncated` still says the walk
-    // was cut and a wider `limit` is the remedy. `messageResumeToken` guards the
-    // same hole for the message face.
-    const position = optionalString(page.nextCursor)
+    // the whole point of the token, so a peer answering `nextCursor: ''`, one
+    // carrying whitespace/control characters, or one shaped like our retired v1
+    // token gets NO token. The absence has TWO opposite cases — a COMPLETE walk,
+    // and a TRUNCATED one whose stop could not be named — and only `truncated`
+    // tells them apart. The remedy follows the REASON: a `'limit'` stop answers
+    // to a wider `limit`; a `'safety-bound'` stop does not, because it is an
+    // internal circuit breaker a caller cannot move. The rule is NOT restated
+    // here or in the message face:
+    // `nameablePeerPosition` is the one place it lives, so the emitters and
+    // their parsers cannot drift (issue #85).
+    const position = nameablePeerPosition(optionalString(page.nextCursor))
+    // The same refusal one dimension further: an encoded token over
+    // {@link MAX_RESUME_TOKEN_CHARS} is one this face would refuse on replay, so
+    // it is not named ({@link withinResumeTokenCeiling}, issue #76). Judged only
+    // on the arm that NAMES it — a complete walk has nothing to name, so it must
+    // not pay for the encoding.
+    const token =
+      !page.truncated || position === undefined
+        ? undefined
+        : withinResumeTokenCeiling(encodeListResumeCursor(binding, position))
     return {
       items: page.items,
       truncated: page.truncated,
       ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
-      ...(page.truncated && position !== undefined && !mangledRemainder(position)
-        ? { resumeCursor: encodeListResumeCursor(binding, position) }
-        : {}),
+      ...(token === undefined ? {} : { resumeCursor: token }),
     }
   }
 
@@ -2139,11 +2199,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))) }
       },
     })
   }
@@ -2175,7 +2236,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
@@ -2183,11 +2246,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.
@@ -2215,9 +2285,10 @@ class CherryToolEngine {
         'List the Cherry Studio agents available on a device. Paginated: `limit` bounds ' +
         'the TOTAL across pages (default 100, max 1000) and is aggregated internally. ' +
         'A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran ' +
-        'out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). A truncated ' +
-        'answer also carries `resumeCursor`: replay it as `cursor` with the same tool, device and ' +
-        'filters to continue from that stop point (`limit` then bounds the next answer).',
+        'out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). When the ' +
+        'stop point can be named it carries `resumeCursor`: replay it as `cursor` with the same ' +
+        'tool, device and filters to continue from that stop point (`limit` then bounds the next ' +
+        'answer).',
       parameters: {
         type: 'object',
         properties: {
@@ -2234,7 +2305,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: {} }
@@ -2258,8 +2329,9 @@ class CherryToolEngine {
         'List an agent\'s REGISTERED workspaces, plus whether a system workspace exists. ' +
         'The system workspace has no enumerable id: it is not in `items`, and its identity ' +
         'is only observable by creating a session in it and reading it back. A truncated ' +
-        'answer (`truncated` + `truncationReason`) stopped before the peer ran out and carries ' +
-        '`resumeCursor`: replay it as `cursor` with the same filters to continue.',
+        'answer (`truncated` + `truncationReason`) stopped before the peer ran out; when the stop ' +
+        'point can be named it carries `resumeCursor` — replay it as `cursor` with the same ' +
+        'filters to continue.',
       parameters: {
         type: 'object',
         properties: {
@@ -2277,7 +2349,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')
@@ -2310,9 +2382,10 @@ class CherryToolEngine {
         '`workspaceId` filters pass straight through to the peer. Paginated: `limit` bounds ' +
         'the TOTAL across pages (default 100, max 1000) and is aggregated internally. ' +
         'A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran ' +
-        'out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). A truncated ' +
-        'answer also carries `resumeCursor`: replay it as `cursor` with the same tool, device and ' +
-        'filters to continue from that stop point (`limit` then bounds the next answer).',
+        'out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). When the ' +
+        'stop point can be named it carries `resumeCursor`: replay it as `cursor` with the same ' +
+        'tool, device and filters to continue from that stop point (`limit` then bounds the next ' +
+        'answer).',
       parameters: {
         type: 'object',
         properties: {
@@ -2331,7 +2404,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'])
@@ -2382,8 +2455,9 @@ class CherryToolEngine {
         '"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 ' +
         '(it only costs more round trips and stops at the same budget). THE OLDER MESSAGES ARE ' +
-        'REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` whenever a ' +
-        'stop point can be named honestly (it is absent when the walk reached the peer\'s last page), and ' +
+        'REACHED BY THE RESUME TOKEN: a truncated answer carries `messagesResumeCursor` when the ' +
+        'stop point can be named — absent when it cannot, e.g. an empty or malformed position, a ' +
+        'token past the length ceiling, or no anchor id — and ' +
         'passing it back as `messagesResumeCursor` continues the walk from there (`limit` then ' +
         'bounds how many messages are returned FROM that point). The two token forms are ' +
         '`"cursor:<peer position>"` (the walk consumed its whole page window) and ' +
@@ -2405,7 +2479,8 @@ class CherryToolEngine {
             description:
               'Maximum number of messages to return in total across pages (default 100). Distinct from ' +
               'the output budget: the answer may stop earlier with `truncationReason: "aggregate-bytes"`, ' +
-              'which a larger `limit` does not extend — the resume token is how older messages are reached.',
+              'which a larger `limit` does not extend — the resume token, when one is returned, is how ' +
+              'older messages are reached.',
           },
           messagesResumeCursor: {
             type: 'string',
@@ -2428,7 +2503,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')
@@ -2586,11 +2661,30 @@ class CherryToolEngine {
       ...(truncationReason === undefined ? {} : { truncationReason }),
       // Only a TRUNCATED walk has unread history, and the token then marks the
       // stop point (OLDER messages remain unread) —
-      // {@link CherryReadSnapshot.messagesResumeCursor}. When the walk's own
-      // verdict names no stop (it reached the peer's last page AND returned
-      // every message it collected) the key is OMITTED rather than emitted
-      // undefined: the absence says "nothing older left", the `truncated` flag
-      // still says whether the walk was cut.
+      // {@link CherryReadSnapshot.messagesResumeCursor}. Whether that stop can
+      // be NAMED is not the walk's verdict: it depends on the peer's payload,
+      // and {@link messageResumeToken} is the ONE place that judges it — content
+      // through `nameableRemainder`, length through `withinResumeTokenCeiling`,
+      // and, for a POSITION only, the retired-v1 check
+      // ({@link nameablePeerPosition}; the anchor arm deliberately skips it,
+      // exactly as `parseMessageResume`'s `after:` branch does). The refusal
+      // cases are therefore not enumerated again here.
+      //
+      // The key is OMITTED rather than emitted `undefined`, and its absence only
+      // means something once read together with `truncated`: the two cases have
+      // opposite meanings —
+      //
+      //  - a COMPLETE walk (nothing older left): `truncated: false`, no token —
+      //    the absence really does say "nothing older left";
+      //  - a TRUNCATED walk whose stop point cannot be named: `truncated: true`
+      //    plus a `truncationReason`, no token — OLDER MESSAGES REMAIN UNREAD,
+      //    and the absence never means they ran out. The remedy follows the
+      //    REASON: only a `limit` stop answers to a wider `limit`; a
+      //    `safety-bound` stop is the internal circuit breaker, and an
+      //    `aggregate-bytes` stop is this answer's own output budget, which a
+      //    wider `limit` does not move (more round trips, same budget). A
+      //    `deadline` stop is a WAIT face's reason — `cherry_read` carries no
+      //    deadline — so it is never this literal's.
       ...(truncated && resumeToken !== undefined ? { messagesResumeCursor: resumeToken } : {}),
     }
   }
@@ -3144,7 +3238,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')
@@ -3262,7 +3356,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
 
@@ -3383,7 +3477,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')
@@ -3614,7 +3708,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')
@@ -3753,8 +3847,8 @@ class CherryToolEngine {
         'pending filter is applied here. Each entry carries its `kind` (question|decision) and a ' +
         'summary; answer questions with cherry_respond\'s `response` form and decisions with ' +
         '`decision`. A truncated answer (`truncated` + `truncationReason`) stopped before the ' +
-        'peer ran out and carries `resumeCursor`: replay it as `cursor` with the same filters to ' +
-        'continue.',
+        'peer ran out; when the stop point can be named it carries `resumeCursor` — replay it as ' +
+        '`cursor` from the same `sessionId` to continue.',
       parameters: {
         type: 'object',
         properties: {
@@ -3778,7 +3872,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')
@@ -3888,7 +3982,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')
@@ -3994,7 +4088,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')
@@ -5547,9 +5641,11 @@ class CherryToolEngine {
 
   /**
    * The timeout result: NOT a failure. Partial content read so far +, whenever a
-   * stop point can be named honestly, a `messagesResumeCursor` token marking where
-   * the unread history begins — absent when the walk reached the peer's last page
-   * or its last returned message carried no id.
+   * stop point can be named honestly, a `messagesResumeCursor` token marking
+   * where the unread history begins. The token is missing in TWO OPPOSITE cases
+   * — a COMPLETE walk, or a TRUNCATED one whose stop point could not be named —
+   * and `messagesTruncated` is what tells them apart; see
+   * {@link CherryMessageWalkVerdict.messagesResumeCursor}.
    *
    * The spec's own sentence (§3.6, 2026-10-09 design: 「超时不是失败：返回已收到
    * 的部分内容 + 当前游标，agent 可续查」) is a statement of that contract in
@@ -5824,9 +5920,10 @@ class CherryToolEngine {
    *    `messagesResumeCursor`: the read scans from the newest end to the anchor
    *    and continues strictly after it.
    *
-   * The token is absent only when there is nothing older to point at (the walk
-   * reached the peer's last page having returned everything it collected).
-   * See {@link CherryMessageWalkVerdict.messagesResumeCursor}.
+   * The token is missing in TWO OPPOSITE cases — a COMPLETE walk, and a
+   * TRUNCATED one whose stop point could not be named — and `messagesTruncated`
+   * is what tells them apart; absence never means "nothing older left" on its
+   * own. See {@link CherryMessageWalkVerdict.messagesResumeCursor}.
    */
   async #readTerminalMessages(
     connection: DeviceConnection,
@@ -6096,28 +6193,111 @@ function parseQuestionInput(input: unknown): string[] | undefined {
  * invented: a wrong anchor is worse than no anchor, and `truncated` still says
  * the walk was cut. Otherwise the whole collected window was consumed, and the
  * peer's page position is exactly where the unread history begins
- * (`cursor:<pos>`) — unless the peer answered an EMPTY position, which names
- * nothing and is therefore not emitted at all.
+ * (`cursor:<pos>`).
+ *
+ * BOTH arms name a remainder only when the PARSER would accept it
+ * ({@link mangledRemainder}): empty, not equal to its own `.trim()` (which is
+ * leading/trailing whitespace), or carrying a control character anywhere is
+ * refused HERE exactly as `parseMessageResume` refuses it on replay. The
+ * emitter must never mint what the parser refuses — a token this tool will not
+ * take back is worse than none, because the refusal then surfaces at the RESUME
+ * call instead of at the answer that produced it. This is the CONTENT
+ * dimension; {@link withinResumeTokenCeiling} is the sibling LENGTH one. The
+ * `after:` anchor is covered by the same rule, not just the `cursor:` position:
+ * a message id is an `opaqueId` too, and padding is schema-valid, so a padded
+ * id really can reach the anchor.
+ *
+ * EXPORTED FOR ITS OWN TESTS. The LENGTH guard on the `after:` arm cannot be
+ * driven through a tool: an anchor is a message ID, and projecting that message
+ * means asking the peer for `agent.parts.list` with it, whose `messageId` is an
+ * `opaqueId` (256 characters). A peer item carrying an id above the token
+ * ceiling therefore fails its parts walk and is never RETURNED, so no walk
+ * reaches the point of naming it. The length guard on that arm is still
+ * required — the emitter must never mint what the parser refuses, whatever the
+ * peer's cap becomes — and this export is how a unit test pins it
+ * (`tests/unit/resumeTokenEmit.test.ts`). The CONTENT guard on both arms IS
+ * reachable, because `opaqueId` allows padding: `tests/integration/
+ * toolsReadResume.test.ts` ⑭d/⑭e drive it through the tools.
  */
-function messageResumeToken(
+export function messageResumeToken(
   page: CherryPage<unknown>,
   returned: number,
   lastReturnedId: string | undefined,
 ): string | undefined {
-  const anchor = optionalString(lastReturnedId)
+  const anchor = nameableRemainder(optionalString(lastReturnedId))
   // TWO forms of "the walk stopped inside what it was given": it returned fewer
   // items than it collected, or the PEER overshot the requested page and items
   // were left in it ({@link CherryPage.pageOverflow}). Either way the page's own
   // position sits past messages this walk never returned, so only the anchor is
   // exact.
   if (returned < page.items.length || page.pageOverflow === true) {
-    return anchor === undefined ? undefined : `${RESUME_ANCHOR_PREFIX}${anchor}`
+    // The ANCHOR takes the content predicate only — NOT the v1 detector, and
+    // that is not an oversight: `parseMessageResume`'s `after:` branch runs
+    // `mangledRemainder` and nothing else, so an id-shaped `after:` remainder is
+    // a token it ACCEPTS back. Applying the detector here would be the mirror
+    // image of this issue — refusing to name a token the parser takes.
+    return anchor === undefined ? undefined : withinResumeTokenCeiling(`${RESUME_ANCHOR_PREFIX}${anchor}`)
   }
-  // An empty position is not a position: a peer answering `nextCursor: ''` on a
-  // non-terminal page would otherwise make this face emit a bare `cursor:`,
-  // which the same face REFUSES on the way back (review P3-4).
-  const position = optionalString(page.nextCursor)
-  return position === undefined ? undefined : `${RESUME_CURSOR_PREFIX}${position}`
+  // A POSITION takes both: the content predicate, and the retired-format
+  // detector its own parser applies before anything else (issue #85).
+  const position = nameablePeerPosition(optionalString(page.nextCursor))
+  return position === undefined ? undefined : withinResumeTokenCeiling(`${RESUME_CURSOR_PREFIX}${position}`)
+}
+
+/**
+ * The CONTENT dimension of "a remainder this bridge may name", or `undefined`
+ * when it must not name one.
+ *
+ * The parsers run `mangledRemainder` on every remainder they read, so one that
+ * fails it is a remainder this tool would refuse on replay: naming it hands the
+ * caller a stop point that can never be used, and the refusal then surfaces at
+ * the RESUME call instead of at the answer that produced it (issues #70, #80).
+ * What it rejects, exactly: empty, not equal to its own `.trim()` (leading/
+ * trailing whitespace), or a control character ANYWHERE — an interior plain space
+ * is legal and round-trips.
+ *
+ * This is the parser's own predicate, not a copy of it, so the two sides cannot
+ * drift into two dialects. The sibling dimension is the LENGTH ceiling, judged
+ * on the FINAL token ({@link withinResumeTokenCeiling}).
+ */
+function nameableRemainder(value: string | undefined): string | undefined {
+  return value === undefined || mangledRemainder(value) ? undefined : value
+}
+
+/**
+ * A remainder this bridge may name AS A PAGE POSITION: {@link nameableRemainder}
+ * plus the one refusal that applies to positions and NOT to anchors.
+ *
+ * `looksLikeV1ListToken` exists because a v1 list token (0.1.6: base64url of
+ * `{v,m,d,h,p}`) lives under `cursor:` and is indistinguishable from a peer
+ * position, so both parsers NAME and refuse it rather than forwarding it to a
+ * desktop that would silently serve its FIRST page. An emitter that wrapped such
+ * a position would mint `cursor:<v1 shape>` and then have its own parser answer
+ * "issued by an older plugin version" about a token this tool had just printed —
+ * the same broken round trip as #76/#80, one detector further out (issue #85).
+ *
+ * The `after:` arm deliberately does NOT use this: `parseMessageResume`'s
+ * `after:` branch never consults the detector, so an `after:` remainder of that
+ * shape is a token it accepts.
+ */
+function nameablePeerPosition(value: string | undefined): string | undefined {
+  const remainder = nameableRemainder(value)
+  return remainder === undefined || looksLikeV1ListToken(remainder) ? undefined : remainder
+}
+
+/**
+ * The token ceiling, enforced on the way OUT as well as in. A token this tool
+ * refuses to replay is worse than no token at all: `truncated` already says the
+ * walk was cut, and the remedy then follows the reason — a `'limit'` stop
+ * answers to a wider `limit` only where the caller owns that ceiling — so a
+ * stop point whose token would push past
+ * {@link MAX_RESUME_TOKEN_CHARS} is simply not named. Measured on the FINAL
+ * string, never on a reconstruction of its length, so a format change cannot
+ * leave the guard behind. Exactly at the ceiling is accepted — it is a length
+ * the parser takes back.
+ */
+function withinResumeTokenCeiling(token: string): string | undefined {
+  return token.length <= MAX_RESUME_TOKEN_CHARS ? token : undefined
 }
 
 /**
@@ -6224,8 +6404,14 @@ function messageIdOf(raw: Record<string, unknown>): string {
  * `undefined`/`null` means "from the newest message", which is the ordinary
  * read. An empty remainder (`'cursor:'`, `'after:'`) is refused like any other
  * foreign token: an empty anchor could never match a message.
+ *
+ * EXPORTED FOR ITS OWN TESTS — specifically for the round-trip property, which
+ * is the invariant this whole file is built around: every token the emitters
+ * NAME must be one this function ACCEPTS. Pinning that with a probe table is
+ * what turns "we mirrored every refusal" from a promise into a check
+ * (`tests/unit/resumeTokenEmit.test.ts`, issue #85).
  */
-function parseMessageResume(value: unknown): MessageResume | undefined {
+export function parseMessageResume(value: unknown): MessageResume | undefined {
   if (value === undefined || value === null) return undefined
   const refuse = (): never => {
     throw new 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',