dsh-cherry-bridge 0.1.6 → 0.1.7

package/README.en.md

@@ -38,13 +38,13 @@ flowchart TB
 
 ```bash
 # From npm (recommended, pinned)
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.6
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.7
 
 # Install the latest npm release
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # From GitHub source (same commit as the npm release)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.6
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.7
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points

package/README.md

@@ -36,13 +36,13 @@ flowchart TB
 
 ```bash
 # 从 npm 安装（推荐，钉住版本）
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.6
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.7
 
 # 安装 npm 最新发布版
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # 从 GitHub 源码安装（与 npm 发布同一提交）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.6
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.7
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），

package/dist/index.mjs

@@ -2261,6 +2261,21 @@ const RECORD_BUDGET_BYTES = 63488;
 const PARTS_LIST_PAGE_CLAMP = Math.floor(RECORD_BUDGET_BYTES / 16896);
 /** Interactions per interactions.list page: inline input + inline summary. */
 const INTERACTIONS_LIST_PAGE_CLAMP = Math.floor(RECORD_BUDGET_BYTES / 25088);
+/**
+* Hard ceiling on ONE resume token (issues #70 and #74), in characters.
+*
+* BOTH faces take a token back from the caller — `cursor` on the four list
+* tools, `messagesResumeCursor` on `cherry_read` — and both tail it with a
+* peer-supplied position whose length we do not control: the desktop's session
+* cursor is `entity:<orderKey>:<uuid>` (~57 characters), a message cursor
+* `<ms>:<uuid>`, the numeric `pageOf` faces a handful of digits, and a future
+* desktop may use something longer — but nothing legitimate comes near this.
+* The bound exists so a hand-built or model-mangled string is refused by a
+* BOUND instead of being split, hashed and carried to the peer, and so both
+* parameters can declare `maxLength` honestly. ONE number for both faces: it
+* bounds caller INPUT, not what a token means.
+*/
+const MAX_RESUME_TOKEN_CHARS = 4096;
 //#endregion
 //#region src/urlHost.ts
 /**
@@ -5462,11 +5477,12 @@ var CherryToolEngine = class {
 	* #65). What a caller can act on is a token, so that is what is emitted.
 	*/
 	#listPage(page, binding) {
+		const position = optionalString(page.nextCursor);
 		return {
 			items: page.items,
 			truncated: page.truncated,
 			...page.truncationReason === void 0 ? {} : { truncationReason: page.truncationReason },
-			...page.truncated && page.nextCursor !== void 0 ? { resumeCursor: encodeListResumeCursor(binding, page.nextCursor) } : {}
+			...page.truncated && position !== void 0 && !mangledRemainder(position) ? { resumeCursor: encodeListResumeCursor(binding, position) } : {}
 		};
 	}
 	#devicesTool() {
@@ -5720,7 +5736,8 @@ var CherryToolEngine = class {
 					},
 					messagesResumeCursor: {
 						type: "string",
-						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."
+						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. A token this tool did not emit is refused locally, and ${MAX_RESUME_TOKEN_CHARS} characters is the ceiling.`
 					}
 				},
 				required: ["device", "sessionId"],
@@ -8231,9 +8248,11 @@ function parseMessageResume(value) {
 	};
 	if (typeof value !== "string") refuse();
 	const token = value;
+	if (token.length > 4096) 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(7);
 		if (mangledRemainder(cursor)) refuse();
+		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
@@ -8247,6 +8266,7 @@ function parseMessageResume(value) {
 			messageId
 		};
 	}
+	if (token.startsWith(LIST_RESUME_PREFIX)) 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();
 }
 /**
@@ -8259,27 +8279,112 @@ function parseMessageResume(value) {
 * 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 = "list:";
+/**
+* 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 = {
+	"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 = 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_RESUME_PREFIX = "cursor:";
-/** The `cursor` parameter every list tool shares (issue #65). */
+const LIST_TOKEN_FIELDS = 4;
+/** The `cursor` parameter every list tool shares (issues #65 and #70). */
 const LIST_CURSOR_PARAMETER = {
 	type: "string",
-	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."
+	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, and so is a token this account cannot have received intact (the token carries a checksum; ${MAX_RESUME_TOKEN_CHARS} characters is the ceiling).`
 };
 /** Canonical, key-sorted rendering of the caller's filters (undefined keys dropped). */
 function listParamsFingerprint(params) {
 	const entries = Object.keys(params).sort().filter((key) => params[key] !== void 0).map((key) => [key, params[key]]);
-	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) {
+	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, peerPosition) {
+	return createHash("sha256").update(`${body}\u0000${peerPosition}`).digest("hex").slice(0, 8);
 }
 function encodeListResumeCursor(binding, peerPosition) {
-	const payload = {
-		v: 1,
-		m: binding.method,
-		d: binding.deviceId,
-		h: listParamsFingerprint(binding.params),
-		p: peerPosition
-	};
-	return LIST_RESUME_PREFIX + Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+	const code = LIST_TOOL_CODES[binding.method];
+	if (code === void 0) 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) {
+	if (raw === "" || raw.includes(":")) return false;
+	try {
+		const decoded = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+		return typeof decoded === "object" && decoded !== null && decoded["v"] === 1;
+	} catch {
+		return false;
+	}
 }
 /**
 * Decode a list token, refusing anything that is not one this tool emitted for
@@ -8294,21 +8399,33 @@ function parseListResumeCursor(value, binding) {
 	const refuse = (why) => {
 		throw new Error(`cursor ${why}; omit \`cursor\` to read from the start, or replay the token with the same tool, device and filters.`);
 	};
-	if (typeof value !== "string" || !value.startsWith(LIST_RESUME_PREFIX)) refuse("must be a `cursor:` token this tool emitted");
-	const raw = value.slice(7);
-	let decoded;
-	try {
-		decoded = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
-	} catch {
+	if (typeof value !== "string") refuse("must be a `list:` token this tool emitted");
+	const token = value;
+	if (token.length > 4096) 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.`);
+	if (token.startsWith(RESUME_CURSOR_PREFIX)) {
+		if (looksLikeV1ListToken(token.slice(7))) 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 (!token.startsWith(LIST_RESUME_PREFIX)) refuse("must be a `list:` token this tool emitted");
+	const raw = token.slice(5);
+	if (!raw.startsWith(`${LIST_TOKEN_VERSION}:`)) {
+		if (looksLikeV1ListToken(raw)) 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 (typeof decoded !== "object" || decoded === null) refuse("is not a token this tool emitted");
-	const payload = decoded;
-	if (payload["v"] !== 1 || typeof payload["m"] !== "string" || typeof payload["d"] !== "string" || typeof payload["h"] !== "string" || typeof payload["p"] !== "string") 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"];
+	let rest = raw.slice(3);
+	const fields = [];
+	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);
+	}
+	const [code, device, filters, checksum] = fields;
+	const peerPosition = rest;
+	if (checksum !== listTokenChecksum(`${LIST_TOKEN_VERSION}:${code}:${device}:${filters}`, 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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cherry-bridge",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "private": false,
   "packageManager": "npm@10.9.9",

package/src/defaults.ts

@@ -137,3 +137,19 @@ export const INTERACTIONS_LIST_PAGE_CLAMP = Math.floor(
 
 /** Items per every other aggregated list page (agents/sessions/messages). */
 export const LIST_PAGE_CLAMP = 16
+
+/**
+ * Hard ceiling on ONE resume token (issues #70 and #74), in characters.
+ *
+ * BOTH faces take a token back from the caller — `cursor` on the four list
+ * tools, `messagesResumeCursor` on `cherry_read` — and both tail it with a
+ * peer-supplied position whose length we do not control: the desktop's session
+ * cursor is `entity:<orderKey>:<uuid>` (~57 characters), a message cursor
+ * `<ms>:<uuid>`, the numeric `pageOf` faces a handful of digits, and a future
+ * desktop may use something longer — but nothing legitimate comes near this.
+ * The bound exists so a hand-built or model-mangled string is refused by a
+ * BOUND instead of being split, hashed and carried to the peer, and so both
+ * parameters can declare `maxLength` honestly. ONE number for both faces: it
+ * bounds caller INPUT, not what a token means.
+ */
+export const MAX_RESUME_TOKEN_CHARS = 4_096

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'
@@ -2097,12 +2098,20 @@ 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: ''` — 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)
     return {
       items: page.items,
       truncated: page.truncated,
       ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
-      ...(page.truncated && page.nextCursor !== undefined
-        ? { resumeCursor: encodeListResumeCursor(binding, page.nextCursor) }
+      ...(page.truncated && position !== undefined && !mangledRemainder(position)
+        ? { resumeCursor: encodeListResumeCursor(binding, position) }
         : {}),
     }
   }
@@ -2400,11 +2409,13 @@ class CherryToolEngine {
           },
           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'],
@@ -6224,9 +6235,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 +6272,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 +6300,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 +6386,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 +6456,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
 }