dsh-cherry-bridge 0.1.7 → 0.1.9

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
@@ -2690,6 +2695,13 @@ var DeviceConnection = class {
 	#transportRetryWaitMs;
 	#stateListeners = /* @__PURE__ */ new Set();
 	/**
+	* Callers parked in {@link waitForSettled}. Separate from the state listeners
+	* because their lifetime is ONE wait: a listener stays for the lifecycle, a
+	* settle waiter removes itself the moment it is answered (or times out), and
+	* mixing them would leave every answered wait in the multicast set.
+	*/
+	#settleWaiters = /* @__PURE__ */ new Set();
+	/**
 	* Waits parked inside `#awaitReconnect`. close() drains them: a shutdown has
 	* no reconnect to wait for, and — the case that matters — a close() followed
 	* by a fresh connect() must not let an OLD lifecycle's replay ride the new
@@ -2814,6 +2826,46 @@ var DeviceConnection = class {
 		this.#stateListeners.add(cb);
 	}
 	/**
+	* Waits for an attempt that is ALREADY IN FLIGHT to settle, bounded by
+	* `timeoutMs`, and answers with the state it ends on.
+	*
+	* The only state this waits on is `connecting`: an attempt is running, and
+	* its outcome is what the caller asked about. `connected` is answered at
+	* once, and so are `offline` (parked in backoff), `disabled` and
+	* `identity-mismatch` — no wait can change those, and waiting on them would
+	* merely delay the caller's answer by the whole bound. `offline` is the
+	* common case for a genuinely powered-off desktop, so it is the one that
+	* matters: the tools stay fail-fast there.
+	*
+	* This NEVER starts an attempt — it observes one the pool already started.
+	* That is the line the tool face has always drawn (a tool must not dial); the
+	* wait only stops the tool from calling a live dial a failure.
+	*
+	* The bound expiring is not an error: the current state (`connecting`) is
+	* returned, and the caller judges it exactly as it would have without the
+	* wait.
+	*/
+	async waitForSettled(timeoutMs) {
+		if (this.#state !== "connecting" || timeoutMs <= 0) return this.#state;
+		return new Promise((resolve) => {
+			let settled = false;
+			let timer;
+			const finish = (state) => {
+				if (settled) return;
+				settled = true;
+				if (timer !== void 0) clearTimeout(timer);
+				this.#settleWaiters.delete(onState);
+				resolve(state);
+			};
+			const onState = (state) => {
+				if (state !== "connecting") finish(state);
+			};
+			timer = setTimeout(() => finish(this.#state), timeoutMs);
+			this.#settleWaiters.add(onState);
+			if (this.#state !== "connecting") finish(this.#state);
+		});
+	}
+	/**
 	* Starts (or joins) the supervised lifecycle. Resolves once this cycle
 	* reaches `connected`; rejects with the cycle's failure. Transient
 	* failures keep being retried in the background by the backoff loop even
@@ -3303,6 +3355,11 @@ var DeviceConnection = class {
 		} catch (error) {
 			console.warn(`[cherry-remote] state listener threw for ${this.record.deviceId}`, error);
 		}
+		for (const cb of [...this.#settleWaiters]) try {
+			cb(next);
+		} catch (error) {
+			console.warn(`[cherry-remote] settle waiter threw for ${this.record.deviceId}`, error);
+		}
 	}
 };
 //#endregion
@@ -5195,8 +5252,12 @@ var CherryToolEngine = class {
 	* ⑤): the candidate list is the answer. A MISS is a verdict too — see
 	* {@link CherryDeviceNotFound} — and it carries the ids the caller could have
 	* meant so the answer stays actionable.
+	*
+	* ASYNC because of the `connecting` wait below: the pool dials on first touch
+	* and on every reconnect, so a tool called in that window used to be refused
+	* for a connection that comes up a moment later (issue #99).
 	*/
-	#resolve(device) {
+	async #resolve(device) {
 		const resolution = this.#deps.store.resolve(device);
 		if ("ambiguous" in resolution) return {
 			error: "ambiguous-device",
@@ -5206,10 +5267,11 @@ var CherryToolEngine = class {
 		if ("notFound" in resolution) return this.#notFoundVerdict(device);
 		const connection = this.#deps.connect(resolution.deviceId);
 		this.#watchConnection(resolution.deviceId, connection);
-		if (connection.state !== "connected") return {
+		const state = connection.state === "connecting" ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? 5e3) : connection.state;
+		if (state !== "connected") return {
 			error: "device-unavailable",
 			device: resolution.deviceId,
-			state: connection.state
+			state
 		};
 		return {
 			record: resolution,
@@ -5245,6 +5307,10 @@ var CherryToolEngine = class {
 	/**
 	* Resolve-or-verdict: every non-`cherry_devices` tool needs a live link.
 	*
+	* `connecting` is waited out inside {@link #resolve} first, so the
+	* `DeviceUnavailableError` below is only ever raised for a state the wait
+	* could not improve on (bounded by `deviceSettleWaitMs`).
+	*
 	* The failure faces are deliberately DIFFERENT (controller ruling ⑤): an
 	* ambiguous selector and a MISS are ANSWERS — the candidate list, or the
 	* known ids, returned in band, because the caller can act on them — while a
@@ -5257,8 +5323,8 @@ var CherryToolEngine = class {
 	* `cherry_devices` does not come through this method — it goes through
 	* {@link #selectRecords}, which returns the verdict in band.
 	*/
-	#requireConnection(device) {
-		const resolved = this.#resolve(device);
+	async #requireConnection(device) {
+		const resolved = await this.#resolve(device);
 		if (!this.#isVerdict(resolved)) return resolved;
 		if (resolved.error === "ambiguous-device") return resolved;
 		if (resolved.error === "not-found") {
@@ -5277,10 +5343,10 @@ var CherryToolEngine = class {
 	* replace it with a weaker, wrong one — a miss under a READ-ONLY archive
 	* would describe a store that still holds a valid token as "no such device".
 	*/
-	#linkOr(device) {
+	async #linkOr(device) {
 		const quarantined = this.#quarantineVerdict();
 		if (quarantined !== void 0) return { verdict: quarantined };
-		const resolved = this.#requireConnection(device);
+		const resolved = await this.#requireConnection(device);
 		if ("error" in resolved) return { verdict: resolved };
 		return { link: resolved };
 	}
@@ -5477,12 +5543,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() {
@@ -5501,10 +5568,13 @@ var CherryToolEngine = class {
 				const selector = optionalString(args["device"]);
 				const quarantined = this.#quarantineVerdict();
 				if (quarantined !== void 0) return quarantined;
-				if (selector === void 0) return { devices: this.#deps.store.list().map((record) => this.#deviceView(record)) };
+				if (selector === void 0) {
+					const records = this.#deps.store.list();
+					return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) };
+				}
 				const selected = this.#selectRecords(selector);
 				if (!Array.isArray(selected)) return selected;
-				return { devices: selected.map((record) => this.#deviceView(record)) };
+				return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) };
 			}
 		});
 	}
@@ -5534,7 +5604,9 @@ var CherryToolEngine = class {
 		return [resolution];
 	}
 	/**
-	* One device's view WITHOUT dialing.
+	* One device's view WITHOUT dialing — but after waiting out an attempt that is
+	* already in flight, exactly as {@link #resolve} does, so a cold-start row
+	* does not present a transient `connecting` as the device's answer.
 	*
 	* A disabled record is authoritative: the pooled connection is constructed
 	* with its own `record.enabled` snapshot and reports `disabled` only once
@@ -5542,10 +5614,11 @@ var CherryToolEngine = class {
 	* for a device whose connection was never started. Everything else falls back
 	* to the connection's own CLOSED state set.
 	*/
-	#deviceView(record) {
+	async #deviceView(record) {
 		let state = record.enabled ? "offline" : "disabled";
 		if (record.enabled) try {
-			state = this.#deps.connect(record.deviceId).state;
+			const connection = this.#deps.connect(record.deviceId);
+			state = connection.state === "connecting" ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? 5e3) : connection.state;
 		} catch (error) {
 			console.warn(`[cherry-remote] cherry_devices could not read the connection for ${record.deviceId}`, error);
 		}
@@ -5561,7 +5634,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: {
@@ -5581,7 +5654,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const binding = {
@@ -5604,7 +5677,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: {
@@ -5628,7 +5701,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const params = { agentId: requiredString(args, "agentId") };
@@ -5659,7 +5732,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: {
@@ -5687,7 +5760,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const agentId = optionalString(args["agentId"]);
@@ -5716,7 +5789,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 +5805,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",
@@ -5745,7 +5818,7 @@ var CherryToolEngine = class {
 			},
 			execute: async (args) => {
 				const resume = parseMessageResume(args["messagesResumeCursor"]);
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6165,7 +6238,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6228,7 +6301,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const agentId = requiredString(args, "agentId");
@@ -6313,7 +6386,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6437,7 +6510,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6491,7 +6564,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: {
@@ -6519,7 +6592,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6619,7 +6692,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -6696,7 +6769,7 @@ var CherryToolEngine = class {
 				additionalProperties: false
 			},
 			execute: async (args) => {
-				const resolved = this.#linkOr(requiredString(args, "device"));
+				const resolved = await this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
@@ -7674,9 +7747,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 +7978,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 +8211,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 +8392,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/docs/e2e-checklist.md

@@ -175,7 +175,7 @@ schema 已允许 `interrupted`，所以客户端**必须**处理，但当前服
 **W1**（步骤 6 会真的把它删掉），其中有一个**保持开着**的会话；③ 一个不勾选的工作区
 **W2**（含一个会话）；④ 一个**没有工作区**的会话——`cwd` 不属于任何已注册工作区，最省事的造法是：
 注册一个临时工作区 W0 → 在其中建一个会话 → 删掉 W0（该会话转入「未分组」，D7 的判定对象就是它）。
-面板入口：设置页 →「**Cherry Studio 互联**」→「**启用范围**」。`curl -s
+面板入口：设置页 →「**Cherry 互联**」→「**启用范围**」。`curl -s
 http://127.0.0.1:23023/cherry-remote/api/scope`（宿主换过端口就换端口；curl 不带 `Origin`，走
 信任 fence 的放行分支）应返回 `host.state: "ready"`、`host.capable: true`、`host.degraded: []`。
 

package/lib/client.js

@@ -13,7 +13,7 @@ window.__ModuleLoader__.load({
 		*/
 		var dictionaries = {
 			zh: {
-				"app.title": "Cherry Studio 互联",
+				"app.title": "Cherry 互联",
 				"app.subtitle": "通过远程传输把本机 DeepSeek Harness 连接到 Cherry Studio 桌面端；设备档案保存在插件数据目录，页面不接触任何凭据。",
 				"app.eventSourceUnavailable": "此环境不支持 EventSource",
 				"app.devices.heading": "已配对设备",
@@ -113,7 +113,7 @@ window.__ModuleLoader__.load({
 				"list.separator": "、"
 			},
 			en: {
-				"app.title": "Cherry Studio Bridge",
+				"app.title": "Cherry Bridge",
 				"app.subtitle": "Connect this machine’s DeepSeek Harness to a Cherry Studio desktop over the remote transport. Device records live in the plugin data directory; this page never touches a credential.",
 				"app.eventSourceUnavailable": "EventSource is unavailable in this environment",
 				"app.devices.heading": "Paired devices",

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Cherry Studio Bridge",
+    "title": "Cherry Bridge",
     "description": "DeepSeek Harness plugin bridging to Cherry Studio desktop instances over remote transport"
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Cherry Studio 互联",
+    "title": "Cherry 互联",
     "description": "通过远程传输把本机 DeepSeek Harness 连接到 Cherry Studio 桌面端的插件"
   }
 }

package/package.json

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

package/src/connection.ts

@@ -627,6 +627,13 @@ export class DeviceConnection {
   readonly #helloProtocolVersions: readonly number[]
   readonly #transportRetryWaitMs: number
   readonly #stateListeners = new Set<(state: DeviceState) => void>()
+  /**
+   * Callers parked in {@link waitForSettled}. Separate from the state listeners
+   * because their lifetime is ONE wait: a listener stays for the lifecycle, a
+   * settle waiter removes itself the moment it is answered (or times out), and
+   * mixing them would leave every answered wait in the multicast set.
+   */
+  readonly #settleWaiters = new Set<(state: DeviceState) => void>()
   /**
    * Waits parked inside `#awaitReconnect`. close() drains them: a shutdown has
    * no reconnect to wait for, and — the case that matters — a close() followed
@@ -783,6 +790,53 @@ export class DeviceConnection {
     this.#stateListeners.add(cb)
   }
 
+  /**
+   * Waits for an attempt that is ALREADY IN FLIGHT to settle, bounded by
+   * `timeoutMs`, and answers with the state it ends on.
+   *
+   * The only state this waits on is `connecting`: an attempt is running, and
+   * its outcome is what the caller asked about. `connected` is answered at
+   * once, and so are `offline` (parked in backoff), `disabled` and
+   * `identity-mismatch` — no wait can change those, and waiting on them would
+   * merely delay the caller's answer by the whole bound. `offline` is the
+   * common case for a genuinely powered-off desktop, so it is the one that
+   * matters: the tools stay fail-fast there.
+   *
+   * This NEVER starts an attempt — it observes one the pool already started.
+   * That is the line the tool face has always drawn (a tool must not dial); the
+   * wait only stops the tool from calling a live dial a failure.
+   *
+   * The bound expiring is not an error: the current state (`connecting`) is
+   * returned, and the caller judges it exactly as it would have without the
+   * wait.
+   */
+  async waitForSettled(timeoutMs: number): Promise<DeviceState> {
+    if (this.#state !== 'connecting' || timeoutMs <= 0) return this.#state
+    return new Promise<DeviceState>((resolve) => {
+      let settled = false
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const finish = (state: DeviceState): void => {
+        if (settled) return
+        settled = true
+        if (timer !== undefined) clearTimeout(timer)
+        this.#settleWaiters.delete(onState)
+        resolve(state)
+      }
+      // The waiter's own filter: a transition to `offline` IS the attempt
+      // settling (failed); only a transition INTO `connecting` is not an
+      // answer, and `#setState` never reports a state it is already in.
+      const onState = (state: DeviceState): void => {
+        if (state !== 'connecting') finish(state)
+      }
+      timer = setTimeout(() => finish(this.#state), timeoutMs)
+      this.#settleWaiters.add(onState)
+      // The attempt may have settled between the guard above and the
+      // registration; that transition is already gone from the multicast, so
+      // it has to be observed by hand.
+      if (this.#state !== 'connecting') finish(this.#state)
+    })
+  }
+
   /**
    * Starts (or joins) the supervised lifecycle. Resolves once this cycle
    * reaches `connected`; rejects with the cycle's failure. Transient
@@ -1582,5 +1636,12 @@ export class DeviceConnection {
         console.warn(`[cherry-remote] state listener threw for ${this.record.deviceId}`, error)
       }
     }
+    for (const cb of [...this.#settleWaiters]) {
+      try {
+        cb(next)
+      } catch (error) {
+        console.warn(`[cherry-remote] settle waiter threw for ${this.record.deviceId}`, error)
+      }
+    }
   }
 }