dsh-cherry-bridge 0.1.6 → 0.1.8

package/src/tools.ts

@@ -6,6 +6,7 @@ import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import {
   INTERACTIONS_LIST_PAGE_CLAMP,
   LIST_PAGE_CLAMP,
+  MAX_RESUME_TOKEN_CHARS,
   PARTS_LIST_PAGE_CLAMP,
 } from './defaults.js'
 import { JsonRpcRequestError, RequestTimeoutError } from './rpc/jsonRpcClient.js'
@@ -390,9 +391,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
@@ -402,6 +409,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
 }
@@ -446,10 +459,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
 }
@@ -2097,13 +2119,33 @@ class CherryToolEngine {
    * #65). What a caller can act on is a token, so that is what is emitted.
    */
   #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: ''`, 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 && page.nextCursor !== undefined
-        ? { resumeCursor: encodeListResumeCursor(binding, page.nextCursor) }
-        : {}),
+      ...(token === undefined ? {} : { resumeCursor: token }),
     }
   }
 
@@ -2206,9 +2248,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: {
@@ -2249,8 +2292,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: {
@@ -2301,9 +2345,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: {
@@ -2373,8 +2418,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 ' +
@@ -2396,15 +2442,18 @@ 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',
+            maxLength: MAX_RESUME_TOKEN_CHARS,
             description:
               'A `messagesResumeCursor` a previous truncated read (this tool, or cherry_send/cherry_wait) ' +
               'returned: `"cursor:<peer position>"` or `"after:<messageId>"`. Continues the walk at that ' +
               'stop point instead of at the newest message; `limit` bounds what comes back from there. ' +
-              'Omit it to read from the newest message.',
+              'Omit it to read from the newest message. A token this tool did not emit is refused locally, ' +
+              `and ${MAX_RESUME_TOKEN_CHARS} characters is the ceiling.`,
           },
         },
         required: ['device', 'sessionId'],
@@ -2575,11 +2624,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 } : {}),
     }
   }
@@ -3742,8 +3810,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: {
@@ -5536,9 +5604,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
@@ -5813,9 +5883,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,
@@ -6085,28 +6156,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
 }
 
 /**
@@ -6213,8 +6367,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(
@@ -6224,9 +6384,36 @@ function parseMessageResume(value: unknown): MessageResume | undefined {
   }
   if (typeof value !== 'string') refuse()
   const token = value as string
+  // Issue #74: the ceiling is judged on the WHOLE token, before either form's
+  // prefix — so `cursor:` and `after:` get the same verdict, and no decoding,
+  // scanning or dial happens for a string that cannot be one of ours. It is the
+  // same bound the list face enforces ({@link MAX_RESUME_TOKEN_CHARS}).
+  if (token.length > MAX_RESUME_TOKEN_CHARS) {
+    throw new Error(
+      `cherry_read: messagesResumeCursor is ${token.length} characters long, over the ` +
+        `${MAX_RESUME_TOKEN_CHARS}-character ceiling for a resume token; omit the argument to read from the ` +
+        'newest message.',
+    )
+  }
   if (token.startsWith(RESUME_CURSOR_PREFIX)) {
     const cursor = token.slice(RESUME_CURSOR_PREFIX.length)
     if (mangledRemainder(cursor)) refuse()
+    // Issue #72, the RELEASED half: a v1 list token (0.1.6 — `cursor:` +
+    // base64url of `{v,m,d,h,p}`) lives under this prefix and its payload is
+    // colon-free base64url, so it arrives here as a perfectly ordinary
+    // position and used to be forwarded to the desktop, which answers a
+    // position it cannot parse by serving its FIRST page. The detector fires
+    // only for a colon-free remainder that base64-decodes to a `{v:1,…}`
+    // object: every real peer position is `<ms>:<id>` (has a colon) or a
+    // numeric offset, so none can be mistaken for one.
+    if (looksLikeV1ListToken(cursor)) {
+      throw new Error(
+        'cherry_read: messagesResumeCursor is a v1 LIST `resumeCursor` (issued by an older plugin version, ' +
+          'before list tokens were compact): it resumes a list walk, not a message history, and it can no ' +
+          'longer be verified. Omit the argument to read from the newest message, or pass the token this ' +
+          'tool returned.',
+      )
+    }
     return { kind: 'cursor', cursor }
   }
   if (token.startsWith(RESUME_ANCHOR_PREFIX)) {
@@ -6234,6 +6421,21 @@ function parseMessageResume(value: unknown): MessageResume | undefined {
     if (mangledRemainder(messageId)) refuse()
     return { kind: 'anchor', messageId }
   }
+  if (token.startsWith(LIST_RESUME_PREFIX)) {
+    // Issue #72, the other direction: a token the four list tools minted. The
+    // two faces are told apart by PREFIX, never by scanning a position for our
+    // own marker — `cursor:list:20` above is still a message cursor. (The branch
+    // above is the one exception, and it is not about the peer's format: it
+    // DECODES our own retired v1 list token, whose payload happens to be
+    // indistinguishable from a position.) Forwarding a list token would hand
+    // the desktop a position it cannot parse, and it answers that by serving
+    // its FIRST page as if it were the continuation.
+    throw new Error(
+      'cherry_read: messagesResumeCursor is a LIST `resumeCursor` (`list:…`) — it resumes a list walk ' +
+        '(cherry_agents / cherry_workspaces / cherry_sessions / cherry_interactions), not a message history. ' +
+        'Omit the argument to read from the newest message, or pass the token this tool returned.',
+    )
+  }
   return refuse()
 }
 
@@ -6247,16 +6449,77 @@ function parseMessageResume(value: unknown): MessageResume | undefined {
  * another query is a perfectly valid number that reads the WRONG slice with no
  * error anywhere. So this token carries a fingerprint of the binding and a
  * mismatched replay is refused HERE — before any RPC.
+ *
+ * Wire format (issue #70):
+ * `list:v2:<tool>:<device12>:<filters8>:<checksum8>:<peer position>` — the
+ * position verbatim and LAST. It replaced a base64 JSON blob (`{v,m,d,h,p}`)
+ * that was ~2.3x longer and had no integrity check: measured over 20,000 random
+ * single-character corruptions, 28.7% of the old tokens were ACCEPTED with a
+ * different position, because the position is the one field a structural check
+ * cannot validate. The compact form plus the checksum makes that class empty.
+ *
+ * The prefix is `list:` and NOT `cursor:` (issue #72): the message face already
+ * owns `cursor:` / `after:`, and while the two faces shared a prefix a list
+ * token was a legal `messagesResumeCursor` payload — it was forwarded to the
+ * desktop, which answers an unparseable position by serving its FIRST page, so
+ * "continue from here" silently re-read the newest page. Two faces, two
+ * prefixes: the refusal is a PREFIX check on either side, never an inspection
+ * of the peer's position (a position that merely starts with `list:` still
+ * travels verbatim inside its own `cursor:` token).
  */
-const LIST_RESUME_PREFIX = 'cursor:'
+const LIST_RESUME_PREFIX = 'list:'
 
-/** The `cursor` parameter every list tool shares (issue #65). */
+/**
+ * The token's format marker (issue #70). It is a FIELD, not part of the prefix,
+ * so a token from the PREVIOUS format is recognised and refused by name
+ * ({@link looksLikeV1ListToken}) instead of getting the generic shape error: a
+ * resume token outlives a plugin upgrade (the caller is holding it), and "start
+ * the walk over" is actionable where "not a token this tool emitted" invites
+ * one more attempt with the same string.
+ *
+ * A format NEWER than this one has no detector and falls through to the
+ * generic refusal, which is the honest verdict: this release cannot know that a
+ * future format is a resume token at all.
+ */
+const LIST_TOKEN_VERSION = 'v2'
+
+/**
+ * One character per list tool, replacing the full method name (19 characters of
+ * a 225-character token). Every method a list tool can issue MUST appear here:
+ * {@link encodeListResumeCursor} throws on an unknown one rather than emit a
+ * token the matching parser could never accept.
+ */
+const LIST_TOOL_CODES: Readonly<Record<string, string>> = {
+  'agent.agents.list': 'a',
+  'agent.workspaces.list': 'w',
+  'agent.sessions.list': 's',
+  'agent.interactions.list': 'i',
+}
+
+/** The inverse of {@link LIST_TOOL_CODES}, for {@link parseListResumeCursor}. */
+const LIST_CODE_METHODS: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(LIST_TOOL_CODES).map(([method, code]) => [code, method]),
+)
+
+/**
+ * The fields after the version marker, BEFORE the peer position: tool code,
+ * device digest, filter fingerprint and checksum. The position is the rest of
+ * the token — it is peer-supplied and may contain the delimiter itself (the
+ * desktop's session cursor is `entity:<orderKey>:<uuid>`), so the split stops
+ * at a fixed count and never consumes it.
+ */
+const LIST_TOKEN_FIELDS = 4
+
+/** The `cursor` parameter every list tool shares (issues #65 and #70). */
 const LIST_CURSOR_PARAMETER = {
   type: 'string',
+  maxLength: MAX_RESUME_TOKEN_CHARS,
   description:
     'A `resumeCursor` a previous TRUNCATED answer of this tool returned: replay it with the SAME ' +
     'device and filters to continue from that stop point (`limit` then bounds this answer). A token ' +
-    'from another tool, device or filter set is refused locally.',
+    'from another tool, device or filter set is refused locally, and so is a token this account ' +
+    `cannot have received intact (the token carries a checksum; ${MAX_RESUME_TOKEN_CHARS} characters ` +
+    'is the ceiling).',
 } as const
 
 /** What a list token is valid for. `params` are the CALLER's filters, not the wire page params. */
@@ -6272,18 +6535,58 @@ function listParamsFingerprint(params: Record<string, unknown>): string {
     .sort()
     .filter((key) => params[key] !== undefined)
     .map((key) => [key, params[key]] as const)
-  return createHash('sha256').update(JSON.stringify(entries)).digest('hex').slice(0, 16)
+  return createHash('sha256').update(JSON.stringify(entries)).digest('hex').slice(0, 8)
+}
+
+/**
+ * The device half of the binding, as a digest rather than the id itself: a
+ * `deviceId` is a 36-character UUID, and the token only ever has to answer "was
+ * this issued for the device I just resolved?", never "which device was it?".
+ * 12 hex characters (48 bits) make an accidental collision between two paired
+ * desktops a non-event, where the old field was a third of the token.
+ */
+function listDeviceFingerprint(deviceId: string): string {
+  return createHash('sha256').update(deviceId).digest('hex').slice(0, 12)
+}
+
+/**
+ * The token's integrity check (issue #70). It covers the peer position, which
+ * is the ONE field no structural check can validate: a substitution there used
+ * to decode as a perfectly well-formed token and was forwarded, and the desktop
+ * silently falls back to its FIRST page for a position it cannot parse — so the
+ * caller's "continue from here" came back as the newest page presented as older
+ * history. 8 hex characters (32 bits) turn every single-character corruption
+ * into a local refusal; the token is not a security boundary, so a MAC would
+ * only make it longer.
+ */
+function listTokenChecksum(body: string, peerPosition: string): string {
+  return createHash('sha256')
+    .update(`${body}\u0000${peerPosition}`)
+    .digest('hex')
+    .slice(0, 8)
 }
 
 function encodeListResumeCursor(binding: ListResumeBinding, peerPosition: string): string {
-  const payload = {
-    v: 1,
-    m: binding.method,
-    d: binding.deviceId,
-    h: listParamsFingerprint(binding.params),
-    p: peerPosition,
+  const code = LIST_TOOL_CODES[binding.method]
+  if (code === undefined) throw new Error(`${binding.method}: no list resume token code`)
+  const body = `${LIST_TOKEN_VERSION}:${code}:${listDeviceFingerprint(binding.deviceId)}:${listParamsFingerprint(
+    binding.params,
+  )}`
+  return `${LIST_RESUME_PREFIX}${body}:${listTokenChecksum(body, peerPosition)}:${peerPosition}`
+}
+
+/**
+ * Whether a `cursor:` remainder is a token from the base64-JSON era (issue #65,
+ * `v: 1`). Only used to explain a refusal: the payload is never replayed.
+ */
+function looksLikeV1ListToken(raw: string): boolean {
+  if (raw === '' || raw.includes(':')) return false
+  try {
+    const decoded: unknown = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'))
+    return typeof decoded === 'object' && decoded !== null && (decoded as Record<string, unknown>)['v'] === 1
+  } catch {
+    return false
   }
-  return LIST_RESUME_PREFIX + Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')
 }
 
 /**
@@ -6302,31 +6605,73 @@ function parseListResumeCursor(value: unknown, binding: ListResumeBinding): stri
         'device and filters.',
     )
   }
-  if (typeof value !== 'string' || !value.startsWith(LIST_RESUME_PREFIX)) {
-    refuse('must be a `cursor:` token this tool emitted')
+  if (typeof value !== 'string') refuse('must be a `list:` token this tool emitted')
+  const token = value as string
+  // Length first: the bound is about CALLER INPUT and must not depend on which
+  // face the string appears to belong to.
+  if (token.length > MAX_RESUME_TOKEN_CHARS) {
+    throw new Error(
+      `cursor is ${token.length} characters long, over the ${MAX_RESUME_TOKEN_CHARS}-character ceiling for a ` +
+        'resume token; omit `cursor` to read from the start.',
+    )
   }
-  const raw = (value as string).slice(LIST_RESUME_PREFIX.length)
-  let decoded: unknown
-  try {
-    decoded = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'))
-  } catch {
-    refuse('is not a token this tool emitted')
+  if (token.startsWith(RESUME_CURSOR_PREFIX)) {
+    // Issue #72. Two faces, two prefixes: a token starting with `cursor:` was
+    // minted by `cherry_read`'s message face, and replaying it here would ask a
+    // LIST method for a slice at an offset taken from a MESSAGE history — a
+    // perfectly valid number that reads the wrong rows with no error anywhere.
+    // Until #70 the list face shared this prefix, so an old token is named
+    // FIRST: "start the walk over" is the only thing that works there, and it
+    // is not what this branch's other verdict says.
+    if (looksLikeV1ListToken(token.slice(RESUME_CURSOR_PREFIX.length))) {
+      throw new Error(
+        'cursor was issued by an older plugin version (a v1 list token, from before list tokens were ' +
+          'compact and checksummed), so it can no longer be verified; start this walk over with `cursor` omitted.',
+      )
+    }
+    refuse(
+      'is a MESSAGE-face token (`cursor:<peer position>`, i.e. a `messagesResumeCursor`), which a list walk ' +
+        'never issues — a list token starts with `list:`',
+    )
   }
-  if (typeof decoded !== 'object' || decoded === null) refuse('is not a token this tool emitted')
-  const payload = decoded as Record<string, unknown>
-  if (
-    payload['v'] !== 1 ||
-    typeof payload['m'] !== 'string' ||
-    typeof payload['d'] !== 'string' ||
-    typeof payload['h'] !== 'string' ||
-    typeof payload['p'] !== 'string'
-  ) {
+  if (!token.startsWith(LIST_RESUME_PREFIX)) {
+    refuse('must be a `list:` token this tool emitted')
+  }
+  const raw = token.slice(LIST_RESUME_PREFIX.length)
+  if (!raw.startsWith(`${LIST_TOKEN_VERSION}:`)) {
+    if (looksLikeV1ListToken(raw)) {
+      // A v1 token cannot be replayed at ALL: the format changed, so "the same
+      // tool, device and filters" would fail again. The generic tail would
+      // therefore tell the caller to do something that can never work — the one
+      // thing this version marker exists to avoid.
+      throw new Error(
+        'cursor was issued by an older plugin version (a v1 token, from before list tokens were compact ' +
+          'and checksummed), so it can no longer be verified; start this walk over with `cursor` omitted.',
+      )
+    }
     refuse('is not a token this tool emitted')
   }
-  if (payload['m'] !== binding.method) refuse('was issued for a different tool')
-  if (payload['d'] !== binding.deviceId) refuse('was issued for a different device')
-  if (payload['h'] !== listParamsFingerprint(binding.params)) refuse('was issued for a different filter set')
-  const peerPosition = payload['p'] as string
+  let rest = raw.slice(LIST_TOKEN_VERSION.length + 1)
+  const fields: string[] = []
+  for (let index = 0; index < LIST_TOKEN_FIELDS; index += 1) {
+    const separator = rest.indexOf(':')
+    if (separator < 0) refuse('is not a token this tool emitted')
+    fields.push(rest.slice(0, separator))
+    rest = rest.slice(separator + 1)
+  }
+  // What is left is the peer position, verbatim — colons and all.
+  const [code, device, filters, checksum] = fields as [string, string, string, string]
+  const peerPosition = rest
+  const body = `${LIST_TOKEN_VERSION}:${code}:${device}:${filters}`
+  // The checksum is judged BEFORE the binding: a corrupted token is not a
+  // statement about the caller's filters, and reporting it as one would send
+  // the caller looking for a filter they never changed.
+  if (checksum !== listTokenChecksum(body, peerPosition)) {
+    refuse('is not a token this tool emitted (its checksum does not match, so it was altered in transit)')
+  }
+  if (LIST_CODE_METHODS[code] !== binding.method) refuse('was issued for a different tool')
+  if (device !== listDeviceFingerprint(binding.deviceId)) refuse('was issued for a different device')
+  if (filters !== listParamsFingerprint(binding.params)) refuse('was issued for a different filter set')
   if (mangledRemainder(peerPosition)) refuse('is not a token this tool emitted')
   return peerPosition
 }