dsh-cherry-bridge 0.1.8 → 0.1.9

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.8
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.9
 
 # 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.8
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.9
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points
@@ -203,7 +203,7 @@ subscription was lost and could not be rebuilt, so the outcome is
 
 The plugin is also a **web client bundle** (`package.json`'s `dsh.client`,
 exporting `./client`). Through the `settings.section` slot it registers a
-**`cherry-remote`** page (nav label “Cherry Studio Bridge”): device cards
+**`cherry-remote`** page (nav label “Cherry Bridge”): device cards
 (enable/disable/remove), a pairing wizard (paste → 6-digit code → verdict), a
 scope panel, and live state pushed over the same-origin SSE feed
 (`/cherry-remote/api/events`).

package/README.md

@@ -36,13 +36,13 @@ flowchart TB
 
 ```bash
 # 从 npm 安装（推荐，钉住版本）
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.8
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.9
 
 # 安装 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.8
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.9
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），
@@ -159,7 +159,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 ## 设置页与启用范围
 
 插件同时是 **web client bundle**（`package.json` 的 `dsh.client`，导出 `./client`），通过
-`settings.section` 槽位注册 **`cherry-remote`**（导航标签「Cherry Studio 互联」）页面：
+`settings.section` 槽位注册 **`cherry-remote`**（导航标签「Cherry 互联」）页面：
 设备卡片（启用/停用/删除）、配对向导（粘贴 → 6 位验证码 → 终态）、启用范围面板，以及经
 `/cherry-remote/api/events` SSE 推送的实时状态。
 

package/dist/index.mjs

@@ -2695,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
@@ -2819,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
@@ -3308,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
@@ -5200,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",
@@ -5211,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,
@@ -5250,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
@@ -5262,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") {
@@ -5282,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 };
 	}
@@ -5507,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))) };
 			}
 		});
 	}
@@ -5540,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
@@ -5548,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);
 		}
@@ -5587,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 = {
@@ -5634,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") };
@@ -5693,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"]);
@@ -5751,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");
@@ -6171,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");
@@ -6234,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");
@@ -6319,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");
@@ -6443,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");
@@ -6525,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");
@@ -6625,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");
@@ -6702,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");

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.8",
+  "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)
+      }
+    }
   }
 }

package/src/defaults.ts

@@ -81,6 +81,24 @@ export const DEFAULT_CONTENT_READ_BUDGET_PER_SECOND = 256
  */
 export const DEFAULT_TRANSPORT_RETRY_WAIT_MS = 5_000
 
+/**
+ * How long a DEVICE TOOL waits for an establishment attempt that is already in
+ * flight (`state === 'connecting'`) before judging the device.
+ *
+ * WHY THIS EXISTS: the connection pool builds a `DeviceConnection` on FIRST
+ * TOUCH and that constructor dials immediately, so every tool called in the
+ * same tick as the first touch — and every tool called during a reconnect —
+ * observed `connecting` and answered `device-unavailable` about a connection
+ * that comes up a moment later. The state is a transient, not a verdict.
+ *
+ * It is deliberately NOT a reconnect budget: an `offline` device is parked in
+ * its backoff, where waiting cannot change anything, so the tools answer at
+ * once. Five seconds is ~15x a LAN dial plus handshake; a bound longer than
+ * that only delays the unavoidable answer, and the tool call is the caller's
+ * unit of patience.
+ */
+export const DEVICE_SETTLE_WAIT_MS = 5_000
+
 /** 2 MiB of event text cached per session (spec §3.5). */
 export const DEFAULT_PER_SESSION_CACHE_BYTES = 2 * 1024 * 1024
 

package/src/tools.ts

@@ -4,6 +4,7 @@ import type { DeviceConnection, DeviceState } from './connection.js'
 import type { DeviceRecord, DeviceResolution, DeviceStore } from './deviceStore.js'
 import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import {
+  DEVICE_SETTLE_WAIT_MS,
   INTERACTIONS_LIST_PAGE_CLAMP,
   LIST_PAGE_CLAMP,
   MAX_RESUME_TOKEN_CHARS,
@@ -1030,6 +1031,14 @@ export interface CherryToolsDeps {
    * this one subscribes the engine to ONE device's transitions.
    */
   watchDeviceState?: (deviceId: string, cb: (state: DeviceState) => void) => void
+  /**
+   * How long a device tool waits for an establishment attempt that is ALREADY
+   * IN FLIGHT (`state === 'connecting'`) before judging the device (issue #99).
+   *
+   * OPTIONAL: production omits it and takes {@link DEVICE_SETTLE_WAIT_MS}; test
+   * rigs drive it down so the bounded case needs no real five seconds.
+   */
+  deviceSettleWaitMs?: number
 }
 
 // ---------------------------------------------------------------------------
@@ -1617,10 +1626,14 @@ class CherryToolEngine {
    * ⑤): 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(
+  async #resolve(
     device: string,
-  ): ResolvedDevice | CherryAmbiguousDevice | CherryDeviceNotFound | CherryDeviceUnavailable {
+  ): Promise<ResolvedDevice | CherryAmbiguousDevice | CherryDeviceNotFound | CherryDeviceUnavailable> {
     const resolution: DeviceResolution = this.#deps.store.resolve(device)
     if ('ambiguous' in resolution) {
       return { error: 'ambiguous-device', device, candidates: resolution.ambiguous }
@@ -1634,10 +1647,21 @@ class CherryToolEngine {
     // transition this exists for can land while the device is already offline,
     // and the watch must be in place from the first call either way.
     this.#watchConnection(resolution.deviceId, connection)
-    if (connection.state !== 'connected') {
+    // `connecting` is an attempt IN FLIGHT, not a verdict (issue #99): the pool
+    // dials on first touch and on every reconnect, so refusing here used to
+    // report a failure about a connection that comes up a moment later. Wait for
+    // that attempt — bounded, and never starting one — then judge the state it
+    // settled on. Every other non-connected state is answered at once: no wait
+    // can change `offline` (parked in backoff), `disabled` or
+    // `identity-mismatch`, and waiting would only delay the answer.
+    const state =
+      connection.state === 'connecting'
+        ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? DEVICE_SETTLE_WAIT_MS)
+        : connection.state
+    if (state !== 'connected') {
       // The established Task 5 shape: the tool never dials implicitly, and the
       // caller gets the same `{device, state}` verdict the RPC layer throws.
-      return { error: 'device-unavailable', device: resolution.deviceId, state: connection.state }
+      return { error: 'device-unavailable', device: resolution.deviceId, state }
     }
     return { record: resolution, connection }
   }
@@ -1675,6 +1699,10 @@ class CherryToolEngine {
   /**
    * 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
@@ -1687,8 +1715,8 @@ class CherryToolEngine {
    * `cherry_devices` does not come through this method — it goes through
    * {@link #selectRecords}, which returns the verdict in band.
    */
-  #requireConnection(device: string): ResolvedDevice | CherryAmbiguousDevice {
-    const resolved = this.#resolve(device)
+  async #requireConnection(device: string): Promise<ResolvedDevice | CherryAmbiguousDevice> {
+    const resolved = await this.#resolve(device)
     if (!this.#isVerdict(resolved)) return resolved
     if (resolved.error === 'ambiguous-device') return resolved
     if (resolved.error === 'not-found') {
@@ -1710,14 +1738,13 @@ class CherryToolEngine {
    * 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: string,
-  ):
+  async #linkOr(device: string): Promise<
     | { link: ResolvedDevice; verdict?: undefined }
-    | { link?: undefined; verdict: CherryAmbiguousDevice | CherryArchiveQuarantined } {
+    | { link?: undefined; verdict: CherryAmbiguousDevice | CherryArchiveQuarantined }
+  > {
     const quarantined = this.#quarantineVerdict()
     if (quarantined !== undefined) return { verdict: quarantined }
-    const resolved = this.#requireConnection(device)
+    const resolved = await this.#requireConnection(device)
     if ('error' in resolved) return { verdict: resolved }
     return { link: resolved }
   }
@@ -2172,11 +2199,12 @@ class CherryToolEngine {
         const quarantined = this.#quarantineVerdict()
         if (quarantined !== undefined) return quarantined
         if (selector === undefined) {
-          return { devices: this.#deps.store.list().map((record) => this.#deviceView(record)) }
+          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))) }
       },
     })
   }
@@ -2208,7 +2236,9 @@ class CherryToolEngine {
   }
 
   /**
-   * 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
@@ -2216,11 +2246,18 @@ class CherryToolEngine {
    * for a device whose connection was never started. Everything else falls back
    * to the connection's own CLOSED state set.
    */
-  #deviceView(record: DeviceRecord): CherryDeviceView {
+  async #deviceView(record: DeviceRecord): Promise<CherryDeviceView> {
     let state: DeviceState = record.enabled ? 'offline' : 'disabled'
     if (record.enabled) {
       try {
-        state = this.#deps.connect(record.deviceId).state
+        const connection = this.#deps.connect(record.deviceId)
+        // Same transient as {@link #resolve} (issue #99): a row rendered while
+        // the first dial is in flight must not present `connecting` as the
+        // device's answer. Bounded, and only for an attempt already running.
+        state =
+          connection.state === 'connecting'
+            ? await connection.waitForSettled(this.#deps.deviceSettleWaitMs ?? DEVICE_SETTLE_WAIT_MS)
+            : connection.state
       } catch (error) {
         // A device that cannot even be resolved to a connection still deserves a
         // truthful row; `offline` is the fallback verdict.
@@ -2268,7 +2305,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const binding: ListResumeBinding = { method: 'agent.agents.list', deviceId: record.deviceId, params: {} }
@@ -2312,7 +2349,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const agentId = requiredString(args, 'agentId')
@@ -2367,7 +2404,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const agentId = optionalString(args['agentId'])
@@ -2466,7 +2503,7 @@ class CherryToolEngine {
         // a malformed cursor, which would present the newest page again as
         // "continued history" — the refusal has to be ours.
         const resume = parseMessageResume(args['messagesResumeCursor'])
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3201,7 +3238,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3319,7 +3356,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
 
@@ -3440,7 +3477,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3671,7 +3708,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3835,7 +3872,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -3945,7 +3982,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
@@ -4051,7 +4088,7 @@ class CherryToolEngine {
         additionalProperties: false,
       },
       execute: async (args) => {
-        const resolved = this.#linkOr(requiredString(args, 'device'))
+        const resolved = await this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')

package/ui/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Cherry Studio 互联 — 开发预览</title>
+    <title>Cherry 互联 — 开发预览</title>
   </head>
   <body>
     <!--

package/ui/src/i18n.ts

@@ -57,7 +57,7 @@ export const LOCALE_IDS: readonly LocaleId[] = ['zh', 'en']
  */
 const zh: Dict = {
   // -- app shell ------------------------------------------------------------
-  'app.title': 'Cherry Studio 互联',
+  'app.title': 'Cherry 互联',
   'app.subtitle':
     '通过远程传输把本机 DeepSeek Harness 连接到 Cherry Studio 桌面端；设备档案保存在插件数据目录，页面不接触任何凭据。',
   // The one string that used to reach a Chinese page in English (App.tsx's
@@ -210,7 +210,7 @@ const zh: Dict = {
  */
 const en: Dict = {
   // -- app shell ------------------------------------------------------------
-  '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',