dsh-cherry-bridge 0.1.7 → 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.7
+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.7
+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.7
+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.7
+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

@@ -2274,6 +2274,11 @@ const INTERACTIONS_LIST_PAGE_CLAMP = Math.floor(RECORD_BUDGET_BYTES / 25088);
 * 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
@@ -5477,12 +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 = optionalString(page.nextCursor);
+		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 && position !== void 0 && !mangledRemainder(position) ? { resumeCursor: encodeListResumeCursor(binding, position) } : {}
+			...token === void 0 ? {} : { resumeCursor: token }
 		};
 	}
 	#devicesTool() {
@@ -5561,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: {
@@ -5604,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: {
@@ -5659,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: {
@@ -5716,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: {
@@ -5732,7 +5738,7 @@ 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",
@@ -6491,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: {
@@ -7674,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
@@ -7903,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"]);
@@ -8135,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.
@@ -8240,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;

package/package.json

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

package/src/defaults.ts

@@ -151,5 +151,10 @@ export const LIST_PAGE_CLAMP = 16
  * 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.
  */
 export const MAX_RESUME_TOKEN_CHARS = 4_096

package/src/tools.ts

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