dsh-cherry-bridge 0.1.6 → 0.1.8

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.8
 
 # 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.8
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points
@@ -103,15 +103,15 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 | Tool | What it does |
 | --- | --- |
 | `cherry_devices` | List every paired device and its connection state (`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`). |
-| `cherry_agents` | List the agents available on a device (paginated). A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`, the latter the 1000-item internal ceiling), plus a `resumeCursor`: replay it as `cursor` with the same device and filters to continue from that stop point (`limit` then bounds the next answer). A token from another tool, device or filter set is refused **locally**, never forwarded. |
-| `cherry_workspaces` | List an agent's **registered** workspaces, and whether a system workspace exists. A truncated answer always carries `truncated` + `truncationReason` and a `resumeCursor` — replay it as `cursor` with the same filters to continue. |
-| `cherry_sessions` | List an agent's sessions, optionally filtered by workspace. A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`) plus a `resumeCursor`: replay it as `cursor` with the same device and **identical filters** to continue (`limit` then bounds the next answer); a token from another tool, device or filter set is refused **locally**. |
-| `cherry_read` | Read a session's message history snapshot, **newest-first** (`limit` drops the **oldest** messages). Attachment parts come back as `name`/`mediaType`/`byteLength` with an empty `content` — the bytes are never fetched. A truncated walk always says so (`truncated` + `truncationReason`): `limit` means your own ceiling was reached and raising `limit` helps; `aggregate-bytes` means the answer hit its **output size limit** — independent of `limit` (a larger `limit` only costs more round trips and stops at the same budget). **The older messages are reached by the resume token**: pass the `messagesResumeCursor` a truncated answer returned as this tool's own `messagesResumeCursor` argument to continue from that stop point (`limit` then bounds how many messages come back **from there**), walking a long history in successive answers. Two token forms: `cursor:<peer position>` (the peer page position after a whole window was consumed) and `after:<messageId>` (the walk stopped inside its window; the resume scans from the newest end to that message and returns the older ones). A token this tool did not emit is **refused locally** (never forwarded — the desktop silently falls back to the newest page for one), and an `after:` anchor that is no longer in the history is an **error**, not an empty result. |
+| `cherry_agents` | List the agents available on a device (paginated). A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`, the latter the 1000-item internal ceiling); when the stop point can be named it also carries a `resumeCursor`: replay it as `cursor` with the same device and filters to continue from that stop point (`limit` then bounds the next answer). A token from another tool, device or filter set is refused **locally**, never forwarded. |
+| `cherry_workspaces` | List an agent's **registered** workspaces, and whether a system workspace exists. A truncated answer always carries `truncated` + `truncationReason`; when the stop point can be named it also carries a `resumeCursor` — replay it as `cursor` with the same filters to continue. |
+| `cherry_sessions` | List an agent's sessions, optionally filtered by workspace. A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`); when the stop point can be named it also carries a `resumeCursor`: replay it as `cursor` with the same device and **identical filters** to continue (`limit` then bounds the next answer); a token from another tool, device or filter set is refused **locally**. |
+| `cherry_read` | Read a session's message history snapshot, **newest-first** (`limit` drops the **oldest** messages). Attachment parts come back as `name`/`mediaType`/`byteLength` with an empty `content` — the bytes are never fetched. A truncated walk always says so (`truncated` + `truncationReason`): `limit` means your own ceiling was reached and raising `limit` helps; `aggregate-bytes` means the answer hit its **output size limit** — independent of `limit` (a larger `limit` only costs more round trips and stops at the same budget). **The older messages are reached by the resume token**: pass the `messagesResumeCursor` a truncated answer returned as this tool's own `messagesResumeCursor` argument to continue from that stop point (`limit` then bounds how many messages come back **from there**), walking a long history in successive answers. When the stop point cannot be named the token is **absent** (`truncated` stays `true`, and the absence does **not** mean the history ended); a wider `limit` is not a general remedy — it moves a `limit` stop only, while an `aggregate-bytes` stop leaves the older messages unreachable in that answer (see [Errors and limits](#errors-and-limits)). Two token forms: `cursor:<peer position>` (the peer page position after a whole window was consumed) and `after:<messageId>` (the walk stopped inside its window; the resume scans from the newest end to that message and returns the older ones). A token this tool did not emit is **refused locally** (never forwarded — the desktop silently falls back to the newest page for one), and an `after:` anchor that is no longer in the history is an **error**, not an empty result. |
 | `cherry_events` | Read the session's buffered events newer than `cursor`, acking them after delivery. The answer is `{events, nextCursor}`; pass that `nextCursor` back as `cursor` to continue from it. |
 | `cherry_create` | Create a session in an agent workspace (workspace selection is **required**; identity is read back). |
 | `cherry_send` | Send a message, by default waiting for a terminal state and returning the assistant text; `wait: false` returns the command receipt immediately. `messagesTruncated`/`messagesTruncationReason` report a **message**-level cut (older messages dropped); `deadline` means the **answer's own assembly budget** ran out (see below), with the content read so far still returned. |
 | `cherry_wait` | Wait only for the session's in-flight execution to settle (sends nothing). |
-| `cherry_interactions` | List the session's **pending** interaction cards (questions / approvals). A truncated answer always carries `truncated` + `truncationReason` and a `resumeCursor` — replay it as `cursor` to continue (`limit` counts the peer's pre-filter rows). |
+| `cherry_interactions` | List the session's **pending** interaction cards (questions / approvals). A truncated answer always carries `truncated` + `truncationReason`; when the stop point can be named it also carries a `resumeCursor` — replay it as `cursor` from the same `sessionId` to continue (`limit` counts the peer's pre-filter rows). |
 | `cherry_respond` | Answer an interaction card: questions must be answered in full; approvals take `decision`. |
 | `cherry_cancel` | Cancel the session's in-flight execution (`expectedExecutionId` required). |
 | `cherry_pair` | Pair with a desktop using the pairing information shown by the scanned page. |
@@ -124,12 +124,12 @@ The `device` argument accepts an **exact `deviceId`**, or a **prefix of a
 `cherry_send(wait: true)` / `cherry_wait` results carry one of **8 `status`
 values**: the four protocol terminal states
 (`completed`/`failed`/`cancelled`/`interrupted`), plus `awaiting-interaction`
-(a pending card appeared while the run is still alive), `timeout` (the window ran
-out, **not a failure** — partial content plus a stop-point cursor come back),
-`idle` (`cherry_wait` met a session with nothing in flight and returned the
-snapshot immediately), and `subscription-lost` (the subscription was lost and
-could not be rebuilt, so the outcome is **unknowable**; repair guidance ships
-with it).
+(a pending card appeared while the run is still alive), `timeout` (the window
+ran out, **not a failure** — partial content comes back, plus a stop-point
+cursor when one can be named), `idle` (`cherry_wait` met a session with nothing
+in flight and returned the snapshot immediately), and `subscription-lost` (the
+subscription was lost and could not be rebuilt, so the outcome is
+**unknowable**; repair guidance ships with it).
 
 ## Errors and limits
 
@@ -152,9 +152,23 @@ with it).
 - A truncated history walk always says so (`truncationReason`; `limit`,
   `aggregate-bytes` and `deadline` mean different things, see above) and,
   whenever a stop point can be named honestly, carries a `messagesResumeCursor`
-  resume token (absent when the walk reached the peer's last page); a message
-  whose own parts could not be fully read carries `incomplete: true` (inside a
-  wait answer, a message cut by the deadline carries
+  resume token. **When it cannot be named the token is absent**: the peer's
+  position is empty, carries leading/trailing whitespace or a control character,
+  looks like a retired v1 token, the token would exceed the 4,096-character
+  ceiling, or there is no message id to anchor on. The absence does **not** mean
+  the history ended (`truncated` stays `true`); the remedy follows the reason —
+  a `limit` stop answers to a wider `limit` only where the caller owns that
+  ceiling (`cherry_read` and the four list tools; a **wait answer's** `limit` is
+  its own fixed allowance, so read further with `cherry_read`), an
+  `aggregate-bytes` stop does not (nothing reaches past it in that answer), a
+  `safety-bound` stop is an internal circuit breaker no caller can move, and a
+  wait answer cut by its deadline is continued with `cherry_read`, which carries
+  no deadline. **Both faces obey one rule**:
+  the message face's `messagesResumeCursor` and the four list tools'
+  `resumeCursor` are emitted only when this tool would accept them back; an
+  interior plain space is legal and is not a reason to withhold one.
+  A message whose own parts could not be fully read carries `incomplete: true`
+  (inside a wait answer, a message cut by the deadline carries
   `partsTruncated: "deadline"`).
 - **A wait answer has an assembly budget of its own.** After the window ends,
   `cherry_send(wait: true)` / `cherry_wait` still read some history (the message

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.8
 
 # 安装 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.8
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），
@@ -94,15 +94,15 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 | 工具 | 作用 |
 | --- | --- |
 | `cherry_devices` | 列出已配对设备及连接状态（`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`）。 |
-| `cherry_agents` | 列出某设备上可用的 agent（分页）。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`，后者是 1000 条内部上限），并给出 `resumeCursor`——用同一 device 与过滤条件把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**，不会转发给对端。 |
-| `cherry_workspaces` | 列出某 agent 的**已注册**工作区，以及是否存在系统工作区。被截断时必带 `truncated`+`truncationReason`，并给出 `resumeCursor`——用相同过滤条件回传为 `cursor` 即可续读。 |
-| `cherry_sessions` | 列出某 agent 的会话，可按工作区过滤。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`），并给出 `resumeCursor`——用同一 device 与**相同过滤条件**把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**。 |
-| `cherry_read` | 读会话消息历史快照，**从新到旧**返回（`limit` 丢掉的是**最旧**的消息）。附件 part 只回 `name`/`mediaType`/`byteLength`，`content` 为空——字节不取。被截断时 `truncated` + `truncationReason` 一定说明：`limit` 表示你设的条数到了，提高 `limit` 即可；`aggregate-bytes` 表示单次回答达到了**输出大小上限**——与 `limit` 无关，提高 `limit` 只会多付往返、仍停在同一预算。**被挡下的更旧消息用 `messagesResumeCursor` 续读**：把本次返回的 `messagesResumeCursor` 原样传给下一次调用的 `messagesResumeCursor` 参数即可从停点继续（`limit` 此时约束的是**从停点起**本次最多返回多少条），长历史分几次回答读完。两种令牌：`cursor:<peer position>`（整窗读完后的 peer 分页位置）与 `after:<messageId>`（停在窗内，续读从最新端扫到该消息、返回它更旧的那些）。不是本工具发出的令牌会被**本地拒绝**（不转发给桌面端——桌面端会静默回退到最新页）；`after:` 锚点在历史里找不到则**报错**，不会返回空结果。 |
+| `cherry_agents` | 列出某设备上可用的 agent（分页）。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`，后者是 1000 条内部上限）；停点可命名时还给出 `resumeCursor`——用同一 device 与过滤条件把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**，不会转发给对端。 |
+| `cherry_workspaces` | 列出某 agent 的**已注册**工作区，以及是否存在系统工作区。被截断时必带 `truncated`+`truncationReason`；停点可命名时还给出 `resumeCursor`——用相同过滤条件回传为 `cursor` 即可续读。 |
+| `cherry_sessions` | 列出某 agent 的会话，可按工作区过滤。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`），停点可命名时还给出 `resumeCursor`——用同一 device 与**相同过滤条件**把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**。 |
+| `cherry_read` | 读会话消息历史快照，**从新到旧**返回（`limit` 丢掉的是**最旧**的消息）。附件 part 只回 `name`/`mediaType`/`byteLength`，`content` 为空——字节不取。被截断时 `truncated` + `truncationReason` 一定说明：`limit` 表示你设的条数到了，提高 `limit` 即可；`aggregate-bytes` 表示单次回答达到了**输出大小上限**——与 `limit` 无关，提高 `limit` 只会多付往返、仍停在同一预算。**被挡下的更旧消息用 `messagesResumeCursor` 续读**：把本次返回的 `messagesResumeCursor` 原样传给下一次调用的 `messagesResumeCursor` 参数即可从停点继续（`limit` 此时约束的是**从停点起**本次最多返回多少条），长历史分几次回答读完。停点不可命名时**没有**这个令牌（`truncated` 仍为 `true`，**缺失本身不代表历史已到底**；补救按 `truncationReason` 分：`limit` 可以提高 `limit`，`aggregate-bytes` 不行——被挡住的旧消息在这一回答里拿不到，详见[错误与限制](#错误与限制)）。两种令牌：`cursor:<peer position>`（整窗读完后的 peer 分页位置）与 `after:<messageId>`（停在窗内，续读从最新端扫到该消息、返回它更旧的那些）。不是本工具发出的令牌会被**本地拒绝**（不转发给桌面端——桌面端会静默回退到最新页）；`after:` 锚点在历史里找不到则**报错**，不会返回空结果。 |
 | `cherry_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。返回 `{events, nextCursor}`；把 `nextCursor` 作为下次的 `cursor` 传回即可续读。 |
 | `cherry_create` | 在 agent 工作区创建会话（工作区选择**必填**；创建后回读身份）。 |
 | `cherry_send` | 向会话发消息，默认等待运行到终态并返回助手文本；`wait: false` 立即返回命令回执。内容被截断时 `messagesTruncated`/`messagesTruncationReason` 说的是**消息**被截断（丢更旧的）；`deadline` 表示**回答自身的装配时限**到了（见下），已读到的内容照常返回。 |
 | `cherry_wait` | 只等待该会话在途执行收敛（不发送新消息）。 |
-| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。被截断时必带 `truncated`+`truncationReason`，并给出 `resumeCursor`——用 `sessionId` 相同的调用回传为 `cursor` 即可续读（`limit` 计的是过滤**前**的对端条目）。 |
+| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。被截断时必带 `truncated`+`truncationReason`；停点可命名时还给出 `resumeCursor`——用 `sessionId` 相同的调用回传为 `cursor` 即可续读（`limit` 计的是过滤**前**的对端条目）。 |
 | `cherry_respond` | 应答交互卡：提问必须全量作答，审批走 `decision`。 |
 | `cherry_cancel` | 取消会话在途执行（`expectedExecutionId` 必填）。 |
 | `cherry_pair` | 用「扫码后页面显示的配对信息」建立与桌面端的配对。 |
@@ -113,7 +113,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 
 `cherry_send(wait: true)` / `cherry_wait` 的 `status` 有 **8 个取值**：四个协议终态
 （`completed`/`failed`/`cancelled`/`interrupted`），加上 `awaiting-interaction`（出现待答
-交互卡，运行仍活着）、`timeout`（窗口用尽，**不是失败**，随附部分内容与停点游标）、
+交互卡，运行仍活着）、`timeout`（窗口用尽，**不是失败**，随附部分内容，停点可命名时再带游标）、
 `idle`（`cherry_wait` 遇到没有在途执行的会话，立即返回快照）、`subscription-lost`
 （事件订阅丢失且重建失败，运行结局**不可知**，随附修复指引）。
 
@@ -128,9 +128,17 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
   不在这个乘积里（每次并发读最多再带一整条消息，因为输出预算只在消息之间检查），parts 缓存另计。
   等待槽位也计入等待类回答的时限：排到时限就放弃并把这一 part 标 `unavailable`。
 - 历史走查被截断时一定说明（`truncationReason`，`limit` / `aggregate-bytes` / `deadline` 三种含义不同，见上），
-  并在能诚实标出停点时给出 `messagesResumeCursor` 续读令牌（走到对端末页时没有可标的位置，就不给）；
-  某条消息自身 parts 没读全时带 `incomplete: true`（wait 类回答里被时限截断的那条消息会带
-  `partsTruncated: "deadline"`）。
+  并在停点可命名时给出 `messagesResumeCursor` 续读令牌。**停点不可命名时就不给**：对端位置为空、
+  带首尾空白或任意控制字符、形如已停用的 v1 令牌、令牌会超过 4096 字符上限、或没有可当锚点的
+  消息 id——此时 `truncated` 仍为 `true`，**缺失本身不代表历史已到底**。补救按 `truncationReason`
+  分：`limit` 停点只有在调用方自己握着上限时才靠更宽的 `limit`（`cherry_read` 与四个列表工具）；
+  **wait 类回答的 `limit` 是它自己的固定条数额度**，更旧的历史要用 `cherry_read` 去读。
+  `aggregate-bytes` 停点不行——预算是它停下的原因，更宽的 `limit` 只会多付往返，被挡住的旧消息
+  在这一回答里拿不到；`safety-bound` 停点是内部熔断，调用方动不了它；`deadline`（只出现在 wait
+  类回答）同样改用 `cherry_read` 续读，它没有时限。
+  **两个面是同一条规则**：消息面的 `messagesResumeCursor` 与四个列表工具的
+  `resumeCursor` 都只发出本工具会收回的令牌；位置内部的普通空格合法，不会因此被拒。
+  某条消息自身 parts 没读全时带 `incomplete: true`（wait 类回答里被时限截断的那条消息会带 `partsTruncated: "deadline"`）。
 - **等待类回答有自己的装配时限**：`cherry_send(wait: true)` / `cherry_wait` 在窗口结束后仍要读一段历史
   （消息页 + 每条消息的 parts + 每个外置 `{ref}` 内容），这一步现在是**有时限的**——截至「你的窗口 +
   同样长度的时间」，下限 1 秒、上限 15 秒（即窗口 1 秒 → 最多再等 1 秒；窗口 20 秒 → 最多再等 15 秒）。

package/dist/index.mjs

@@ -2261,6 +2261,26 @@ 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.
+*
+* The emit side enforces it too (#76): a stop point whose token would exceed
+* this is not named at all, because a token this tool refuses to replay is
+* worse than no token — `truncated` still says the walk was cut. One number,
+* judged in both directions.
+*/
+const MAX_RESUME_TOKEN_CHARS = 4096;
 //#endregion
 //#region src/urlHost.ts
 /**
@@ -5462,11 +5482,13 @@ var CherryToolEngine = class {
 	* #65). What a caller can act on is a token, so that is what is emitted.
 	*/
 	#listPage(page, binding) {
+		const position = nameablePeerPosition(optionalString(page.nextCursor));
+		const token = !page.truncated || position === void 0 ? void 0 : withinResumeTokenCeiling(encodeListResumeCursor(binding, position));
 		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) } : {}
+			...token === void 0 ? {} : { resumeCursor: token }
 		};
 	}
 	#devicesTool() {
@@ -5545,7 +5567,7 @@ var CherryToolEngine = class {
 	#agentsTool() {
 		return defineCherryTool({
 			name: "cherry_agents",
-			description: "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).",
+			description: "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). 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: {
@@ -5588,7 +5610,7 @@ var CherryToolEngine = class {
 	#workspacesTool() {
 		return defineCherryTool({
 			name: "cherry_workspaces",
-			description: "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.",
+			description: "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; when the stop point can be named it carries `resumeCursor` — replay it as `cursor` with the same filters to continue.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5643,7 +5665,7 @@ var CherryToolEngine = class {
 	#sessionsTool() {
 		return defineCherryTool({
 			name: "cherry_sessions",
-			description: "List an agent's sessions, optionally filtered by workspace. The `agentId` and `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).",
+			description: "List an agent's sessions, optionally filtered by workspace. The `agentId` and `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). 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: {
@@ -5700,7 +5722,7 @@ var CherryToolEngine = class {
 	#readTool() {
 		return defineCherryTool({
 			name: "cherry_read",
-			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. A binary attachment is reported as `kind: \"file\"` with `name`/`mediaType`/`byteLength` and an EMPTY `content` — the bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (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 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 `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
+			description: "Read a session's message history snapshot. Two-level baseline: `agent.sessions.get` supplies the history revision, `agent.messages.list` the messages, and each message's own revision the parts. Large part text is externalized by the peer and fetched and sha256-verified through `agent.content.read`. An unchanged message (same message revision) reuses its cached part LIST, fenced by that revision, so a repeated read of a quiet session costs no `agent.parts.list` RPC; externalized content is still fetched and sha256-verified on every read, so unverified bytes are never served from memory. A binary attachment is reported as `kind: \"file\"` with `name`/`mediaType`/`byteLength` and an EMPTY `content` — the bytes are deliberately not fetched into a text channel. Messages come NEWEST-first, so the first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts inside a retained message's parts; a message whose own parts could not be fully read carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. The answer is ALSO bounded by an output budget: `truncated` with `truncationReason: \"aggregate-bytes\"` means the walk stopped because the result reached its size limit, not because `limit` was reached — raising `limit` does NOT reach the messages left out (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` 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 `\"after:<messageId>\"` (it stopped inside the window; the read restarts at the newest end and resumes strictly after that message). A token this tool did not emit is refused locally rather than forwarded, and an `after:` anchor that no longer exists in the history is an error, not an empty page. A `truncationReason` of \"limit\" is the caller's own ceiling and is reached by raising `limit`. Either way the newest message is always returned whole.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5716,11 +5738,12 @@ var CherryToolEngine = class {
 						type: "integer",
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
-						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."
+						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, when one is returned, is how older messages are reached."
 					},
 					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"],
@@ -6474,7 +6497,7 @@ var CherryToolEngine = class {
 	#interactionsTool() {
 		return defineCherryTool({
 			name: "cherry_interactions",
-			description: "List the session's PENDING interactions (questions and approval decisions) that need an answer. The peer serves the full four-state set (pending/approved/denied/expired) — the 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.",
+			description: "List the session's PENDING interactions (questions and approval decisions) that need an answer. The peer serves the full four-state set (pending/approved/denied/expired) — the 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; when the stop point can be named it carries `resumeCursor` — replay it as `cursor` from the same `sessionId` to continue.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -7657,9 +7680,11 @@ var CherryToolEngine = class {
 	}
 	/**
 	* 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
@@ -7886,9 +7911,10 @@ var CherryToolEngine = class {
 	*    `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, sessionId, session, deadline) {
 		const historyRevision = optionalString(session["historyRevision"]);
@@ -8118,14 +8144,90 @@ function parseQuestionInput(input) {
 * 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(page, returned, lastReturnedId) {
-	const anchor = optionalString(lastReturnedId);
-	if (returned < page.items.length || page.pageOverflow === true) return anchor === void 0 ? void 0 : `${RESUME_ANCHOR_PREFIX}${anchor}`;
-	const position = optionalString(page.nextCursor);
-	return position === void 0 ? void 0 : `${RESUME_CURSOR_PREFIX}${position}`;
+	const anchor = nameableRemainder(optionalString(lastReturnedId));
+	if (returned < page.items.length || page.pageOverflow === true) return anchor === void 0 ? void 0 : withinResumeTokenCeiling(`${RESUME_ANCHOR_PREFIX}${anchor}`);
+	const position = nameablePeerPosition(optionalString(page.nextCursor));
+	return position === void 0 ? void 0 : 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) {
+	return value === void 0 || mangledRemainder(value) ? void 0 : 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) {
+	const remainder = nameableRemainder(value);
+	return remainder === void 0 || looksLikeV1ListToken(remainder) ? void 0 : 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) {
+	return token.length <= 4096 ? token : void 0;
 }
 /**
 * The message-walk verdict, projected off an aggregate page.
@@ -8223,6 +8325,12 @@ function messageIdOf(raw) {
 * `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) {
 	if (value === void 0 || value === null) return void 0;
@@ -8231,9 +8339,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 +8357,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 +8370,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 +8490,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.8",
   "type": "module",
   "private": false,
   "packageManager": "npm@10.9.9",