dsh-cherry-bridge 0.1.5 → 0.1.7

package/README.en.md

@@ -37,14 +37,14 @@ flowchart TB
 > **DSH version requirement**: `>=0.2.0-rc.2 <0.3.0-0` (declared via `engines.dsh` in `package.json`; when unmet the bundle is skipped and its settings-page row disabled — `dsh plugin allow-version` grants an explicit exemption; 0.3.0 needs a fresh compatibility pass before the range widens).
 
 ```bash
-# From GitHub (recommended)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge
+# From npm (recommended, pinned)
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.7
 
-# Pinned to a version tag (recommended for production)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.5
+# Install the latest npm release
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
-# Or from the npm registry
-dsh plugin --profile <name> 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.7
 ```
 
 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). |
-| `cherry_workspaces` | List an agent's **registered** workspaces, and whether a system workspace exists. |
-| `cherry_sessions` | List an agent's sessions, optionally filtered by workspace. |
+| `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_events` | Read the session's buffered events newer than `cursor`, acking them after delivery. |
+| `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). |
+| `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_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. |
@@ -224,7 +224,7 @@ npm run typecheck      # server + UI projects
 npm run build          # tsdown → dist/index.mjs + dist/index.d.mts
 npm run build:client   # vite → lib/client.js
 npm run dev:ui         # settings-page dev server (host must run at 127.0.0.1:23023)
-npm run prepublishOnly # pre-publish gate: typecheck + test + build + build:client
+npm run prepublishOnly # pre-publish gate: typecheck + test + build + build:client + npm pack --dry-run
 ```
 
 `dist/` and `lib/` are **committed** artifacts: after changing `src/` or `ui/`

package/README.md

@@ -35,14 +35,14 @@ flowchart TB
 > **DSH 版本需求**：`>=0.2.0-rc.2 <0.3.0-0`（由 `package.json` 的 `engines.dsh` 声明；不满足时 bundle 被跳过、设置页里该插件的行被禁用，确需在区间外使用可用 `dsh plugin allow-version` 精确豁免。0.3.0 需重新评估兼容性后再放开）。
 
 ```bash
-# 从 GitHub 安装（推荐）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge
+# 从 npm 安装（推荐，钉住版本）
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.7
 
-# 钉住版本标签（生产推荐）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.5
+# 安装 npm 最新发布版
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
-# 或从 npm registry 安装
-dsh plugin --profile <name> add dsh-cherry-bridge
+# 从 GitHub 源码安装（与 npm 发布同一提交）
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.7
 ```
 
 本包自带 `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（分页）。 |
-| `cherry_workspaces` | 列出某 agent 的**已注册**工作区，以及是否存在系统工作区。 |
-| `cherry_sessions` | 列出某 agent 的会话，可按工作区过滤。 |
+| `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_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。 |
+| `cherry_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。返回 `{events, nextCursor}`；把 `nextCursor` 作为下次的 `cursor` 传回即可续读。 |
 | `cherry_create` | 在 agent 工作区创建会话（工作区选择**必填**；创建后回读身份）。 |
 | `cherry_send` | 向会话发消息，默认等待运行到终态并返回助手文本；`wait: false` 立即返回命令回执。内容被截断时 `messagesTruncated`/`messagesTruncationReason` 说的是**消息**被截断（丢更旧的）；`deadline` 表示**回答自身的装配时限**到了（见下），已读到的内容照常返回。 |
 | `cherry_wait` | 只等待该会话在途执行收敛（不发送新消息）。 |
-| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。 |
+| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。被截断时必带 `truncated`+`truncationReason`，并给出 `resumeCursor`——用 `sessionId` 相同的调用回传为 `cursor` 即可续读（`limit` 计的是过滤**前**的对端条目）。 |
 | `cherry_respond` | 应答交互卡：提问必须全量作答，审批走 `decision`。 |
 | `cherry_cancel` | 取消会话在途执行（`expectedExecutionId` 必填）。 |
 | `cherry_pair` | 用「扫码后页面显示的配对信息」建立与桌面端的配对。 |
@@ -176,7 +176,7 @@ npm run typecheck      # 服务端 + UI 两侧
 npm run build          # tsdown → dist/index.mjs + dist/index.d.mts
 npm run build:client   # vite → lib/client.js
 npm run dev:ui         # 设置页 dev server（需宿主在 127.0.0.1:23023 运行）
-npm run prepublishOnly # 发布前闸门：typecheck + test + build + build:client
+npm run prepublishOnly # 发布前闸门：typecheck + test + build + build:client + npm pack --dry-run
 ```
 
 `dist/` 与 `lib/` 是**随仓库提交**的产物：改完 `src/` 或 `ui/` 必须重跑

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
 /**
@@ -5445,6 +5460,31 @@ var CherryToolEngine = class {
 			...pageOverflow === void 0 ? {} : { pageOverflow }
 		};
 	}
+	/** Decode one list `cursor` argument, or undefined when none was given. */
+	#listResume(raw, binding) {
+		if (raw === void 0 || raw === null) return void 0;
+		return {
+			kind: "cursor",
+			cursor: parseListResumeCursor(raw, binding)
+		};
+	}
+	/**
+	* The public shape of a list walk's result: items, the stop verdict, and — only
+	* when the walk really stopped at a peer position — the RESUMABLE token.
+	*
+	* The peer's own position never leaves this method: it is opaque, unusable as
+	* an input on its own, and exposing it invited callers to replay it (issue
+	* #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 && position !== void 0 && !mangledRemainder(position) ? { resumeCursor: encodeListResumeCursor(binding, position) } : {}
+		};
+	}
 	#devicesTool() {
 		return defineCherryTool({
 			name: "cherry_devices",
@@ -5521,7 +5561,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.",
+			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).",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5534,7 +5574,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of agents to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device"],
 				additionalProperties: false
@@ -5542,18 +5583,28 @@ var CherryToolEngine = class {
 			execute: async (args) => {
 				const resolved = this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
-				const { connection } = resolved.link;
-				return this.#aggregate(connection, "agent.agents.list", {}, (page) => ({
-					...arrayOf(page["items"]),
-					nextCursor: page["nextCursor"]
-				}), { limit: aggregateLimit(args["limit"]) });
+				const { connection, record } = resolved.link;
+				const binding = {
+					method: "agent.agents.list",
+					deviceId: record.deviceId,
+					params: {}
+				};
+				const resume = this.#listResume(args["cursor"], binding);
+				const page = await this.#aggregate(connection, "agent.agents.list", {}, (result) => ({
+					...arrayOf(result["items"]),
+					nextCursor: result["nextCursor"]
+				}), {
+					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume }
+				});
+				return this.#listPage(page, binding);
 			}
 		});
 	}
 	#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.",
+			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.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5570,7 +5621,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of workspaces to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device", "agentId"],
 				additionalProperties: false
@@ -5578,21 +5630,28 @@ var CherryToolEngine = class {
 			execute: async (args) => {
 				const resolved = this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
-				const { connection } = resolved.link;
-				const agentId = requiredString(args, "agentId");
+				const { connection, record } = resolved.link;
+				const params = { agentId: requiredString(args, "agentId") };
+				const binding = {
+					method: "agent.workspaces.list",
+					deviceId: record.deviceId,
+					params
+				};
+				const resume = this.#listResume(args["cursor"], binding);
 				let systemWorkspace = false;
-				const page = await this.#aggregate(connection, "agent.workspaces.list", { agentId }, (result) => {
+				const page = await this.#aggregate(connection, "agent.workspaces.list", params, (result) => {
 					if (typeof result["systemWorkspace"] === "boolean") systemWorkspace = result["systemWorkspace"];
 					return {
 						...arrayOf(result["items"]),
 						nextCursor: result["nextCursor"]
 					};
-				}, { limit: aggregateLimit(args["limit"]) });
+				}, {
+					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume }
+				});
 				return {
-					items: page.items,
-					systemWorkspace,
-					truncated: page.truncated,
-					...page.truncationReason === void 0 ? {} : { truncationReason: page.truncationReason }
+					...this.#listPage(page, binding),
+					systemWorkspace
 				};
 			}
 		});
@@ -5600,7 +5659,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.",
+			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).",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5621,7 +5680,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of sessions to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device"],
 				additionalProperties: false
@@ -5629,16 +5689,27 @@ var CherryToolEngine = class {
 			execute: async (args) => {
 				const resolved = this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
-				const { connection } = resolved.link;
+				const { connection, record } = resolved.link;
 				const agentId = optionalString(args["agentId"]);
 				const workspaceId = optionalString(args["workspaceId"]);
-				return this.#aggregate(connection, "agent.sessions.list", {
+				const params = {
 					...agentId === void 0 ? {} : { agentId },
 					...workspaceId === void 0 ? {} : { workspaceId }
-				}, (page) => ({
-					...arrayOf(page["items"]),
-					nextCursor: page["nextCursor"]
-				}), { limit: aggregateLimit(args["limit"]) });
+				};
+				const binding = {
+					method: "agent.sessions.list",
+					deviceId: record.deviceId,
+					params
+				};
+				const resume = this.#listResume(args["cursor"], binding);
+				const page = await this.#aggregate(connection, "agent.sessions.list", params, (result) => ({
+					...arrayOf(result["items"]),
+					nextCursor: result["nextCursor"]
+				}), {
+					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume }
+				});
+				return this.#listPage(page, binding);
 			}
 		});
 	}
@@ -5665,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"],
@@ -6061,7 +6133,7 @@ var CherryToolEngine = class {
 	#eventsTool() {
 		return defineCherryTool({
 			name: "cherry_events",
-			description: "Read the session's buffered events newer than `cursor`, delivering them and then acknowledging the advanced cursor to the peer. While the window has dropped no events, every cursor this plugin handed out is servable, including the baseline `cherry_send`/`cherry_wait` report on an empty window. Once the window DISCARDS events, the boundary it reports is not: that boundary and everything below it answer a structured `cursor-out-of-window` verdict, and only positions strictly past it are served — rebuild the baseline with `cherry_read` and resume from that instead.",
+			description: "Read the session's buffered events newer than `cursor`, delivering them and then acknowledging the advanced cursor to the peer. While the window has dropped no events, every cursor this plugin handed out is servable, including the baseline `cherry_send`/`cherry_wait` report on an empty window. Once the window DISCARDS events, the boundary it reports is not: that boundary and everything below it answer a structured `cursor-out-of-window` verdict, and only positions strictly past it are served — rebuild the baseline with `cherry_read` and resume from that instead. The answer is `{events, nextCursor}`; pass that `nextCursor` back as `cursor` on the next call to continue from it.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6419,7 +6491,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`.",
+			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.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6440,7 +6512,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of interactions to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device", "sessionId"],
 				additionalProperties: false
@@ -6450,12 +6523,20 @@ var CherryToolEngine = class {
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
+				const params = { sessionId };
+				const binding = {
+					method: "agent.interactions.list",
+					deviceId: record.deviceId,
+					params
+				};
+				const resume = this.#listResume(args["cursor"], binding);
 				await this.#ensureSubscription(record.deviceId, sessionId);
-				const page = await this.#aggregate(connection, "agent.interactions.list", { sessionId }, (result) => ({
+				const page = await this.#aggregate(connection, "agent.interactions.list", params, (result) => ({
 					...arrayOf(result["items"]),
 					nextCursor: result["nextCursor"]
 				}), {
 					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume },
 					safetyBound: MAX_AGGREGATE_LIMIT,
 					maxPerPage: INTERACTIONS_LIST_PAGE_CLAMP
 				});
@@ -6463,9 +6544,8 @@ var CherryToolEngine = class {
 				const items = page.items.filter((item) => includeAnswered || item["status"] === "pending").map((item) => this.#interactionView(item));
 				for (const item of page.items) this.#rememberInteraction(record.deviceId, sessionId, item);
 				return {
-					items,
-					truncated: page.truncated,
-					...page.truncationReason === void 0 ? {} : { truncationReason: page.truncationReason }
+					...this.#listPage(page, binding),
+					items
 				};
 			}
 		});
@@ -8168,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
@@ -8184,9 +8266,170 @@ 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();
 }
 /**
+* The LIST face's stop point (issue #65): a self-describing token that the SAME
+* tool accepts back, bound to the query that produced it.
+*
+* The message face wraps the peer position in `cursor:` / `after:` and is done,
+* because a message walk is scoped by its session. A list walk is scoped by
+* (method, device, filters), and the peer position is opaque: a position from
+* 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_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, 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, 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 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
+* THIS binding. The refusal names the dimension that differs (tool / device /
+* filters) and never echoes the peer position, which is peer-supplied data.
+*
+* An `after:` token is refused by the prefix check: list walks have no anchor
+* form (they never trim a page, so a peer position always exists for a stop the
+* peer reported).
+*/
+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") 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");
+	}
+	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;
+}
+/**
 * The assistant text a terminal aggregate reports: the awaited RUN's assistant
 * message text parts, joined.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cherry-bridge",
-  "version": "0.1.5",
+  "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'
@@ -2082,6 +2083,39 @@ class CherryToolEngine {
     }
   }
 
+  /** Decode one list `cursor` argument, or undefined when none was given. */
+  #listResume(raw: unknown, binding: ListResumeBinding): { kind: 'cursor'; cursor: string } | undefined {
+    if (raw === undefined || raw === null) return undefined
+    return { kind: 'cursor', cursor: parseListResumeCursor(raw, binding) }
+  }
+
+  /**
+   * The public shape of a list walk's result: items, the stop verdict, and — only
+   * when the walk really stopped at a peer position — the RESUMABLE token.
+   *
+   * The peer's own position never leaves this method: it is opaque, unusable as
+   * an input on its own, and exposing it invited callers to replay it (issue
+   * #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 && position !== undefined && !mangledRemainder(position)
+        ? { resumeCursor: encodeListResumeCursor(binding, position) }
+        : {}),
+    }
+  }
+
   // -------------------------------------------------------------------------
   // ① cherry_devices
   // -------------------------------------------------------------------------
@@ -2179,7 +2213,11 @@ class CherryToolEngine {
       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.',
+        '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).',
       parameters: {
         type: 'object',
         properties: {
@@ -2190,6 +2228,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of agents to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device'],
         additionalProperties: false,
@@ -2197,14 +2236,17 @@ class CherryToolEngine {
       execute: async (args) => {
         const resolved = this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
-        const { connection } = resolved.link
-        return this.#aggregate(
+        const { connection, record } = resolved.link
+        const binding: ListResumeBinding = { method: 'agent.agents.list', deviceId: record.deviceId, params: {} }
+        const resume = this.#listResume(args['cursor'], binding)
+        const page = await this.#aggregate(
           connection,
           'agent.agents.list',
           {},
-          (page) => ({ ...arrayOf(page['items']), nextCursor: page['nextCursor'] }),
-          { limit: aggregateLimit(args['limit']) },
+          (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
+          { limit: aggregateLimit(args['limit']), ...(resume === undefined ? {} : { resume }) },
         )
+        return this.#listPage(page, binding)
       },
     })
   }
@@ -2215,7 +2257,9 @@ class CherryToolEngine {
       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.',
+        '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.',
       parameters: {
         type: 'object',
         properties: {
@@ -2227,6 +2271,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of workspaces to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device', 'agentId'],
         additionalProperties: false,
@@ -2234,27 +2279,25 @@ class CherryToolEngine {
       execute: async (args) => {
         const resolved = this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
-        const { connection } = resolved.link
+        const { connection, record } = resolved.link
         const agentId = requiredString(args, 'agentId')
+        const params = { agentId }
+        const binding: ListResumeBinding = { method: 'agent.workspaces.list', deviceId: record.deviceId, params }
+        const resume = this.#listResume(args['cursor'], binding)
         let systemWorkspace = false
         const page = await this.#aggregate(
           connection,
           'agent.workspaces.list',
-          { agentId },
+          params,
           (result) => {
             // The flag rides on every page; the last page read wins, and the
             // real peer always sends it.
             if (typeof result['systemWorkspace'] === 'boolean') systemWorkspace = result['systemWorkspace']
             return { ...arrayOf(result['items']), nextCursor: result['nextCursor'] }
           },
-          { limit: aggregateLimit(args['limit']) },
+          { limit: aggregateLimit(args['limit']), ...(resume === undefined ? {} : { resume }) },
         )
-        return {
-          items: page.items,
-          systemWorkspace,
-          truncated: page.truncated,
-          ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
-        }
+        return { ...this.#listPage(page, binding), systemWorkspace }
       },
     })
   }
@@ -2265,7 +2308,11 @@ class CherryToolEngine {
       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.',
+        '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).',
       parameters: {
         type: 'object',
         properties: {
@@ -2278,6 +2325,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of sessions to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device'],
         additionalProperties: false,
@@ -2285,21 +2333,27 @@ class CherryToolEngine {
       execute: async (args) => {
         const resolved = this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
-        const { connection } = resolved.link
+        const { connection, record } = resolved.link
         const agentId = optionalString(args['agentId'])
         const workspaceId = optionalString(args['workspaceId'])
         // Filter passthrough: the params carry the caller's filters verbatim,
-        // and `#aggregate` adds only `limit`/`cursor`.
-        return this.#aggregate(
+        // and `#aggregate` adds only `limit`/`cursor`. The SAME object is the
+        // token's binding, so a replay with other filters cannot read another
+        // query's page position.
+        const params = {
+          ...(agentId === undefined ? {} : { agentId }),
+          ...(workspaceId === undefined ? {} : { workspaceId }),
+        }
+        const binding: ListResumeBinding = { method: 'agent.sessions.list', deviceId: record.deviceId, params }
+        const resume = this.#listResume(args['cursor'], binding)
+        const page = await this.#aggregate(
           connection,
           'agent.sessions.list',
-          {
-            ...(agentId === undefined ? {} : { agentId }),
-            ...(workspaceId === undefined ? {} : { workspaceId }),
-          },
-          (page) => ({ ...arrayOf(page['items']), nextCursor: page['nextCursor'] }),
-          { limit: aggregateLimit(args['limit']) },
+          params,
+          (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
+          { limit: aggregateLimit(args['limit']), ...(resume === undefined ? {} : { resume }) },
         )
+        return this.#listPage(page, binding)
       },
     })
   }
@@ -2355,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'],
@@ -3064,7 +3120,9 @@ class CherryToolEngine {
         '`cherry_send`/`cherry_wait` report on an empty window. Once the window DISCARDS events, ' +
         'the boundary it reports is not: that boundary and everything below it answer a structured ' +
         '`cursor-out-of-window` verdict, and only positions strictly past it are served — rebuild ' +
-        'the baseline with `cherry_read` and resume from that instead.',
+        'the baseline with `cherry_read` and resume from that instead. The answer is ' +
+        '`{events, nextCursor}`; pass that `nextCursor` back as `cursor` on the next call to ' +
+        'continue from it.',
       parameters: {
         type: 'object',
         properties: {
@@ -3694,7 +3752,9 @@ class CherryToolEngine {
         '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`.',
+        '`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.',
       parameters: {
         type: 'object',
         properties: {
@@ -3712,6 +3772,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of interactions to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device', 'sessionId'],
         additionalProperties: false,
@@ -3721,6 +3782,9 @@ class CherryToolEngine {
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
+        const params = { sessionId }
+        const binding: ListResumeBinding = { method: 'agent.interactions.list', deviceId: record.deviceId, params }
+        const resume = this.#listResume(args['cursor'], binding)
 
         await this.#ensureSubscription(record.deviceId, sessionId)
 
@@ -3730,10 +3794,11 @@ class CherryToolEngine {
         const page = await this.#aggregate(
           connection,
           'agent.interactions.list',
-          { sessionId },
+          params,
           (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
           {
             limit: aggregateLimit(args['limit']),
+            ...(resume === undefined ? {} : { resume }),
             safetyBound: MAX_AGGREGATE_LIMIT,
             // An interaction record carries an inline input AND an inline
             // summary, the fattest item of the plain lists.
@@ -3752,11 +3817,7 @@ class CherryToolEngine {
         // docblock): priming from it is what makes every listed card answerable.
         for (const item of page.items) this.#rememberInteraction(record.deviceId, sessionId, item)
 
-        return {
-          items,
-          truncated: page.truncated,
-          ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
-        }
+        return { ...this.#listPage(page, binding), items }
       },
     })
   }
@@ -6174,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)) {
@@ -6184,9 +6272,261 @@ 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()
 }
 
+/**
+ * The LIST face's stop point (issue #65): a self-describing token that the SAME
+ * tool accepts back, bound to the query that produced it.
+ *
+ * The message face wraps the peer position in `cursor:` / `after:` and is done,
+ * because a message walk is scoped by its session. A list walk is scoped by
+ * (method, device, filters), and the peer position is opaque: a position from
+ * 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: 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, 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. */
+interface ListResumeBinding {
+  method: string
+  deviceId: string
+  params: Record<string, unknown>
+}
+
+/** Canonical, key-sorted rendering of the caller's filters (undefined keys dropped). */
+function listParamsFingerprint(params: Record<string, unknown>): string {
+  const entries = Object.keys(params)
+    .sort()
+    .filter((key) => params[key] !== undefined)
+    .map((key) => [key, params[key]] as const)
+  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 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
+  }
+}
+
+/**
+ * Decode a list token, refusing anything that is not one this tool emitted for
+ * THIS binding. The refusal names the dimension that differs (tool / device /
+ * filters) and never echoes the peer position, which is peer-supplied data.
+ *
+ * An `after:` token is refused by the prefix check: list walks have no anchor
+ * form (they never trim a page, so a peer position always exists for a stop the
+ * peer reported).
+ */
+function parseListResumeCursor(value: unknown, binding: ListResumeBinding): string {
+  const refuse = (why: string): never => {
+    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') 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.',
+    )
+  }
+  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 (!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')
+  }
+  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
+}
+
 /**
  * The assistant text a terminal aggregate reports: the awaited RUN's assistant
  * message text parts, joined.