dsh-cherry-bridge 0.2.0 → 0.2.2

package/lib/client.js

@@ -45,6 +45,12 @@ window.__ModuleLoader__.load({
 				"device.remove.confirm": "确认移除",
 				"device.remove.warning": "移除后本机将不再连接该设备，凭据保留在对方一侧。",
 				"device.cancel": "取消",
+				"device.forget": "忘记",
+				"device.remember": "恢复",
+				"device.field.forgotten": "已忘记地址",
+				"device.forgotten.hint": "已忘记的地址不会再被连接；「恢复」只解除标记，桌面下次广播该地址时会重新加入。",
+				"device.error.lastAddress": "不能忘记最后一个候选地址——先补一个地址，再忘记这个",
+				"device.error.timeout": "请求长时间没有回应，已中止——请稍后重试",
 				"device.error.nameRequired": "设备名称不能为空",
 				"device.error.hostsRequired": "至少需要一个主机地址",
 				"device.error.portInvalid": "端口必须是 1..65535 之间的整数",
@@ -65,7 +71,10 @@ window.__ModuleLoader__.load({
 				"wizard.succeeded": "配对成功",
 				"wizard.failed": "配对失败：{stage}",
 				"wizard.unknownError": "未知错误",
+				"app.error.timeout": "请求长时间没有回应，已中止——请确认宿主仍在运行；若反复出现，请重启宿主后再试",
+				"wizard.timedOut": "没有等到配对结果——若桌面端已批准，下面的设备列表里会出现该设备；否则请在 Cherry Studio 重新生成配对码后重试",
 				"wizard.error.payloadRequired": "请先粘贴扫码页显示的配对信息",
+				"wizard.error.timeout": "配对请求迟迟没有回应，已中止——请重试；若反复出现，宿主可能已卡住，重启后再试",
 				"wizard.stage.validate": "正在校验配对信息…",
 				"wizard.stage.connect": "正在连接 Cherry Studio…",
 				"wizard.stage.claim": "正在交换凭据…",
@@ -103,6 +112,7 @@ window.__ModuleLoader__.load({
 				"scope.savedPruned": "保存成功，按服务端修剪清除了失效选择：{list}。",
 				"scope.reread": "重新读取",
 				"scope.saveFailed": "保存失败：{cause}",
+				"scope.error.timeout": "请求长时间没有回应，已中止——请稍后重试",
 				"scope.serverSaid": "服务端返回 {code}（HTTP {status}）。",
 				"scope.degraded.install": "隐藏层应用曾失败（install）：相关 agent 的隐藏层未生效或无法确认，启用范围对它可能不适用",
 				"scope.degraded.workspace-list": "注册表列表当前读不到",
@@ -149,6 +159,12 @@ window.__ModuleLoader__.load({
 				"device.remove.confirm": "Confirm removal",
 				"device.remove.warning": "This machine will stop connecting to the device. Its credentials stay on the peer.",
 				"device.cancel": "Cancel",
+				"device.forget": "Forget",
+				"device.remember": "Restore",
+				"device.field.forgotten": "Forgotten addresses",
+				"device.forgotten.hint": "Forgotten addresses are never dialed. Restore only lifts the mark — the address comes back the next time the desktop advertises it.",
+				"device.error.lastAddress": "The last candidate address cannot be forgotten. Add one first.",
+				"device.error.timeout": "The request stopped answering and was abandoned. Try again in a moment.",
 				"device.error.nameRequired": "Device name cannot be empty",
 				"device.error.hostsRequired": "At least one host address is required",
 				"device.error.portInvalid": "Port must be an integer between 1 and 65535",
@@ -169,7 +185,10 @@ window.__ModuleLoader__.load({
 				"wizard.succeeded": "Paired",
 				"wizard.failed": "Pairing failed: {stage}",
 				"wizard.unknownError": "Unknown error",
+				"app.error.timeout": "The request stopped answering and was abandoned. Check that the host is still running; if it keeps happening, restart it and try again.",
+				"wizard.timedOut": "No pairing result arrived. If the desktop approved it, the device appears in the list below; otherwise generate a new pairing code in Cherry Studio and try again.",
 				"wizard.error.payloadRequired": "Paste the pairing payload shown on the scan page first",
+				"wizard.error.timeout": "The pairing request stopped answering and was abandoned. Try again; if it keeps happening the host may be stuck — restart it and retry.",
 				"wizard.stage.validate": "Validating the pairing payload…",
 				"wizard.stage.connect": "Connecting to Cherry Studio…",
 				"wizard.stage.claim": "Exchanging credentials…",
@@ -207,6 +226,7 @@ window.__ModuleLoader__.load({
 				"scope.savedPruned": "Saved. The server pruned these stale selections: {list}.",
 				"scope.reread": "Reload",
 				"scope.saveFailed": "Save failed: {cause}",
+				"scope.error.timeout": "The request stopped answering and was abandoned. Try again in a moment.",
 				"scope.serverSaid": "The server answered {code} (HTTP {status}).",
 				"scope.degraded.install": "Applying a hidden layer failed earlier (install): the affected agent’s hidden layer is not in effect or cannot be confirmed, so the tool scope may not apply to it",
 				"scope.degraded.workspace-list": "The workspace registry list is currently unreadable",
@@ -411,6 +431,33 @@ window.__ModuleLoader__.load({
 				this.name = "ApiError";
 			}
 		};
+		/**
+		* The marker a request that never answered throws with.
+		*
+		* Internal token, NEVER copy: each surface renders its own sentence for it —
+		* `app.error.timeout`, `wizard.error.timeout`, `scope.error.timeout` — and this
+		* string only travels from `request()` to the catch block that recognizes it, the
+		* same split as `app.eventSourceUnavailable` (see `App.tsx`). That is what keeps
+		* an English literal off a Chinese page.
+		*/
+		var REQUEST_TIMEOUT = "cherry-remote.request-timeout";
+		/**
+		* How long ANY call on this page may stay open, in milliseconds.
+		*
+		* None of these calls is slow: they are same-origin requests to the plugin's own
+		* HTTP face, and the one that looks slowest — a pairing START — does no I/O
+		* before it answers (`src/httpApi.ts` `startPairing` writes its 202 at once).
+		* A request still open after this long is a WEDGED transport, not a busy server,
+		* and it must not be allowed to strand a control: without a ceiling the pairing
+		* wizard's submit button (issue #173), a device card's buttons, the scope panel's
+		* save and the device list's "loading" state each wait for the life of the page
+		* (issue #180).
+		*
+		* So the ceiling lives in `request()`, where every call passes, rather than on
+		* one call site. Each surface turns the {@link REQUEST_TIMEOUT} marker into its
+		* own sentence.
+		*/
+		var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 		/** Reads a JSON body without throwing on an empty (204) or non-JSON response. */
 		async function readBody(response) {
 			const text = await response.text();
@@ -421,22 +468,36 @@ window.__ModuleLoader__.load({
 				return text;
 			}
 		}
-		async function request(url, init) {
-			const response = await fetch(url, {
-				...init,
-				headers: {
-					"content-type": "application/json",
-					...init?.headers ?? {}
+		/**
+		* One bounded request. `timeoutMs` exists so a test can prove the ceiling
+		* without waiting for it; production always takes {@link DEFAULT_REQUEST_TIMEOUT_MS}.
+		*/
+		async function request(url, init, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			try {
+				const response = await fetch(url, {
+					...init,
+					headers: {
+						"content-type": "application/json",
+						...init?.headers ?? {}
+					},
+					signal: controller.signal
+				});
+				const body = await readBody(response);
+				if (!response.ok) {
+					const record = body ?? {};
+					const code = typeof record.error === "string" ? record.error : `http-${response.status}`;
+					const message = typeof record.message === "string" ? record.message : code;
+					throw new ApiError(response.status, code, message);
 				}
-			});
-			const body = await readBody(response);
-			if (!response.ok) {
-				const record = body ?? {};
-				const code = typeof record.error === "string" ? record.error : `http-${response.status}`;
-				const message = typeof record.message === "string" ? record.message : code;
-				throw new ApiError(response.status, code, message);
+				return body;
+			} catch (cause) {
+				if (controller.signal.aborted) throw new Error(REQUEST_TIMEOUT);
+				throw cause;
+			} finally {
+				clearTimeout(timer);
 			}
-			return body;
 		}
 		/** `GET /devices` — the full card list, states projected server-side. */
 		async function listDevices() {
@@ -449,15 +510,19 @@ window.__ModuleLoader__.load({
 		* It deliberately does NOT wait for approval: the 6-digit code and the verdict
 		* arrive as `pairing-progress` SSE frames, which is why the caller must already
 		* be subscribed when this resolves.
+		*
+		* Bounded like every other call (see {@link DEFAULT_REQUEST_TIMEOUT_MS});
+		* `timeoutMs` exists only so a test can prove the ceiling without waiting.
 		*/
-		async function startPairing(payload, name) {
+		async function startPairing(payload, options = {}) {
+			const { name } = options;
 			return await request(`/cherry-remote/api/pair`, {
 				method: "POST",
 				body: JSON.stringify(name === void 0 || name === "" ? { payload } : {
 					payload,
 					name
 				})
-			}) ?? {};
+			}, options.timeoutMs) ?? {};
 		}
 		/** `PATCH /devices/:id` — `hosts` is whole-replace; omitted fields are untouched. */
 		async function patchDevice(deviceId, patch) {
@@ -466,6 +531,35 @@ window.__ModuleLoader__.load({
 				body: JSON.stringify(patch)
 			});
 		}
+		/**
+		* `POST /devices/:id/forget` — stop dialing these addresses AND record them so
+		* the desktop cannot advertise them back (issue #185).
+		*
+		* The answer is the SAME record shape {@link patchDevice} returns, which is why
+		* the card hands either body to the same `onSaved`. The action is its own
+		* request on purpose: folding it into the PATCH would make "replace the dial
+		* list" and "forget one address" one body with an ordering to define.
+		*/
+		async function forgetHosts(deviceId, hosts) {
+			return await request(`${API_BASE}/devices/${encodeURIComponent(deviceId)}/forget`, {
+				method: "POST",
+				body: JSON.stringify({ hosts })
+			});
+		}
+		/**
+		* `POST /devices/:id/remember` — lift the marks.
+		*
+		* It does NOT dial the address again: the record's `hosts` is untouched, and
+		* the address returns when the desktop next advertises it. Putting it back into
+		* the dial list immediately stays the PATCH's job (that PATCH clears the mark in
+		* the same write).
+		*/
+		async function rememberHosts(deviceId, hosts) {
+			return await request(`${API_BASE}/devices/${encodeURIComponent(deviceId)}/remember`, {
+				method: "POST",
+				body: JSON.stringify({ hosts })
+			});
+		}
 		/** `DELETE /devices/:id` — 204, no body. */
 		async function removeDevice(deviceId) {
 			await request(`${API_BASE}/devices/${encodeURIComponent(deviceId)}`, { method: "DELETE" });
@@ -519,6 +613,16 @@ window.__ModuleLoader__.load({
 		* `onSaved`, so the card shows what the archive holds rather than what the
 		* browser hoped for. The live `state` keeps coming from SSE; the patch response
 		* only seeds it.
+		*
+		* The addresses row is also where an address is FORGOTTEN (issue #204), and the
+		* marks it leaves are listed under their own label with a 恢复 each. One click
+		* is one committed action, never a draft: the two controls are INERT while the
+		* address editor is open, because that form PATCHes the whole host list and its
+		* draft is unconditionally sacred (see the resync effect) — a mark chosen
+		* underneath it would be re-sent by the next 保存地址, and the PATCH that names a
+		* forgotten host clears its mark in the same write. Freezing the controls is
+		* what keeps "commit or discard the edit first" true; it is not a stylistic
+		* preference.
 		*/
 		/** Splits the comma-separated host box into the whole-replace list the API wants. */
 		function parseHosts(raw) {
@@ -581,18 +685,59 @@ window.__ModuleLoader__.load({
 				device.port,
 				editor
 			]);
-			/** Runs one mutation, mapping a refusal into the card's error line. */
+			/**
+			* Runs one mutation, mapping a refusal into the card's error line.
+			*
+			* A request that never answered arrives as `api.ts`'s internal marker — the
+			* page-wide ceiling (issue #180) — and a marker must never render. Every card
+			* action is a bounded call (停用 / 重命名 / 移除 are PATCH or DELETE), so this
+			* surface translates it like the other three do instead of echoing
+			* `cherry-remote.request-timeout` onto the page.
+			*/
 			const run = async (action) => {
 				setBusy(true);
 				setError(void 0);
 				try {
 					await action();
 				} catch (cause) {
-					setError(cause instanceof Error ? cause.message : String(cause));
+					setError(describeCause(cause));
 				} finally {
 					setBusy(false);
 				}
 			};
+			/**
+			* One refusal for a cause, so the two markers and the one translated code
+			* cannot drift between this card's arms.
+			*
+			* `ApiError` renders as `<code>: <server message>`, which is right for a
+			* diagnostic and wrong for `last-address`: forgetting the only candidate is a
+			* thing the operator can fix here, and the server's own prose is English on a
+			* Chinese page. Everything else keeps the server's verdict verbatim — that is
+			* what tells `invalid-payload` from `unreachable`.
+			*/
+			const describeCause = (cause) => {
+				if (cause instanceof ApiError && cause.code === "last-address") return t("device.error.lastAddress");
+				if (cause instanceof Error && cause.message === "cherry-remote.request-timeout") return t("device.error.timeout");
+				return cause instanceof Error ? cause.message : String(cause);
+			};
+			/** Forgets ONE address: the store drops it and records the mark in one write. */
+			const forget = (host) => {
+				run(async () => {
+					onSaved(await forgetHosts(device.deviceId, [host]));
+				});
+			};
+			/**
+			* Lifts ONE mark. The server also drops the pooled connection on a change, so
+			* the very handshake that follows re-learns the address if the desktop still
+			* advertises it — without that, a desktop that stays connected would not
+			* re-handshake for as long as the link holds, and this button would look
+			* inert.
+			*/
+			const remember = (host) => {
+				run(async () => {
+					onSaved(await rememberHosts(device.deviceId, [host]));
+				});
+			};
 			const toggleEnabled = () => {
 				const enabled = !device.enabled;
 				run(async () => {
@@ -637,6 +782,13 @@ window.__ModuleLoader__.load({
 					onRemoved(device.deviceId);
 				});
 			};
+			/**
+			* A defensive empty list, the same choice `dialPort` makes for the required
+			* `ports` map: `GET /devices` always emits the key, but this card is one row
+			* in a list, and a record missing one field must not take the whole page down
+			* with a render throw — it shows a card without the mark instead.
+			*/
+			const forgottenHosts = device.forgottenHosts ?? [];
 			const mixedPorts = device.hosts.some((host) => dialPort(device, host) !== device.port);
 			const addressList = device.hosts.map((host) => formatAddress(host, dialPort(device, host))).join(", ");
 			const label = state === void 0 ? t("device.state.unknown") : t(STATE_KEYS[state] ?? state);
@@ -702,7 +854,24 @@ window.__ModuleLoader__.load({
 						className: "cherry-card-facts",
 						children: [
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dt", { children: t("device.field.addresses") }),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dd", { children: device.hosts.join(", ") }),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dd", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+								className: "cherry-address-list",
+								children: device.hosts.map((host) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: host }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									onClick: () => forget(host),
+									disabled: busy || editor === "address",
+									children: t("device.forget")
+								})] }, host))
+							}) }),
+							forgottenHosts.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dt", { children: t("device.field.forgotten") }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("dd", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+								className: "cherry-address-list",
+								children: forgottenHosts.map((host) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: host }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									onClick: () => remember(host),
+									disabled: busy || editor === "address",
+									children: t("device.remember")
+								})] }, host))
+							}) })] }),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dt", { children: t("device.field.port") }),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dd", { children: device.port }),
 							mixedPorts && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("dt", { children: t("device.field.ports") }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("dd", {
@@ -716,6 +885,10 @@ window.__ModuleLoader__.load({
 							})
 						]
 					}),
+					forgottenHosts.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						className: "cherry-hint",
+						children: t("device.forgotten.hint")
+					}),
 					mixedPorts && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 						className: "cherry-hint",
 						children: t("device.ports.hint")
@@ -835,7 +1008,28 @@ window.__ModuleLoader__.load({
 		*/
 		/** The countdown the transient code display gets, in seconds. */
 		var DEFAULT_CODE_LIFETIME_MS = 12e4;
-		function PairingWizard({ subscribed, progress, codeLifetimeMs = DEFAULT_CODE_LIFETIME_MS, onRunStart, onSettled }) {
+		/**
+		* How long one run may sit in `waiting` before the wizard gives the form back.
+		*
+		* The server publishes a terminal stage on EVERY outcome (`src/httpApi.ts`
+		* `startPairing`), but the event stream carries no replay, so a single dropped
+		* frame loses the verdict for good — and nothing else clears `busy`: only a
+		* terminal frame or a refused POST does, and there is no cancel control. Without
+		* this bound a lost frame parks the wizard on 「配对进行中」 until a page reload.
+		*
+		* The bound must be comfortably past a REALISTIC live run: `src/pairing.ts`
+		* bounds the candidate walk to 30 s (`dialBudgetMs`) and the claim/poll phase to
+		* a FRESH 120 s anchored at the claim, so 150 s plus 30 s of margin.
+		*
+		* It is NOT past a pathological one, and it says so rather than pretending: two
+		* round trips inside that walk (`hello`, then the claim) are bounded only by
+		* JsonRpcClient's 60 s default request timeout, so a peer that stalls each just
+		* under it can keep a run legitimately working for ~270 s. A premature alarm is
+		* acceptable because it is not a verdict — it points at the device list, and a
+		* terminal frame arriving later replaces it (see `claimId` below).
+		*/
+		var DEFAULT_RUN_LIFETIME_MS = 18e4;
+		function PairingWizard({ subscribed, progress, codeLifetimeMs = DEFAULT_CODE_LIFETIME_MS, runLifetimeMs = DEFAULT_RUN_LIFETIME_MS, onRunStart, onSettled }) {
 			const t = useT();
 			const [payload, setPayload] = (0, react.useState)("");
 			const [claimId, setClaimId] = (0, react.useState)(void 0);
@@ -844,6 +1038,7 @@ window.__ModuleLoader__.load({
 			const [code, setCode] = (0, react.useState)(void 0);
 			const [busy, setBusy] = (0, react.useState)(false);
 			const [verdict, setVerdict] = (0, react.useState)(void 0);
+			const [timedOut, setTimedOut] = (0, react.useState)(false);
 			const stage = progress?.stage;
 			const frameClaimId = progress?.claimId;
 			(0, react.useEffect)(() => {
@@ -858,6 +1053,7 @@ window.__ModuleLoader__.load({
 				}
 				if (TERMINAL_STAGES.includes(stage)) {
 					setCode(void 0);
+					setTimedOut(false);
 					setVerdict(stage);
 					setPhase(stage === "approved" ? "done" : "failed");
 					setBusy(false);
@@ -875,6 +1071,21 @@ window.__ModuleLoader__.load({
 				const timer = setTimeout(() => setCode(void 0), codeLifetimeMs);
 				return () => clearTimeout(timer);
 			}, [code, codeLifetimeMs]);
+			(0, react.useEffect)(() => {
+				if (phase !== "waiting") return void 0;
+				const timer = setTimeout(() => {
+					setCode(void 0);
+					setTimedOut(true);
+					setPhase("failed");
+					setBusy(false);
+					onSettled?.();
+				}, runLifetimeMs);
+				return () => clearTimeout(timer);
+			}, [
+				phase,
+				runLifetimeMs,
+				onSettled
+			]);
 			const submit = (event) => {
 				event.preventDefault();
 				const trimmed = payload.trim();
@@ -887,12 +1098,13 @@ window.__ModuleLoader__.load({
 				setPhase("submitting");
 				setClaimId(void 0);
 				setVerdict(void 0);
+				setTimedOut(false);
 				onRunStart?.();
 				startPairing(trimmed).then((result) => {
 					setClaimId(result.claimId);
 					setPhase("waiting");
 				}, (cause) => {
-					setError(cause instanceof Error ? cause.message : String(cause));
+					setError(cause instanceof Error && cause.message === "cherry-remote.request-timeout" ? t("wizard.error.timeout") : cause instanceof Error ? cause.message : String(cause));
 					setPhase("idle");
 					setBusy(false);
 				});
@@ -976,7 +1188,7 @@ window.__ModuleLoader__.load({
 					phase === "failed" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 						className: "cherry-error",
 						role: "alert",
-						children: t("wizard.failed", { stage: STAGE_KEYS[verdict ?? ""] === void 0 ? t("wizard.unknownError") : t(STAGE_KEYS[verdict ?? ""]) })
+						children: timedOut ? t("wizard.timedOut") : t("wizard.failed", { stage: STAGE_KEYS[verdict ?? ""] === void 0 ? t("wizard.unknownError") : t(STAGE_KEYS[verdict ?? ""]) })
 					}),
 					error !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 						className: "cherry-error",
@@ -1106,7 +1318,15 @@ window.__ModuleLoader__.load({
 		* code" checkable by eye.
 		*/
 		var SAVE_FAILED_KEY = "scope.saveFailed";
-		var describeCause = (cause) => cause instanceof Error ? cause.message : String(cause);
+		/**
+		* The panel's own description of a failure.
+		*
+		* A request that never answered arrives as `api.ts`'s internal marker (the
+		* page-wide ceiling, issue #180), which must become a sentence before it reaches
+		* any of the three places this feeds — the read error, the save failure and the
+		* re-read error. Everything else is the server's own message, interpolated.
+		*/
+		var describeCause$1 = (t, cause) => cause instanceof Error && cause.message === "cherry-remote.request-timeout" ? t("scope.error.timeout") : cause instanceof Error ? cause.message : String(cause);
 		/**
 		* D11's empty state for the current draft, or `undefined` when nothing may be
 		* claimed yet.
@@ -1167,7 +1387,7 @@ window.__ModuleLoader__.load({
 					if (!live) return;
 					seedFromDocument(response);
 				}, (cause) => {
-					if (live) setLoadError(describeCause(cause));
+					if (live) setLoadError(describeCause$1(t, cause));
 				});
 				return () => {
 					live = false;
@@ -1237,7 +1457,7 @@ window.__ModuleLoader__.load({
 					if (code === "scope-version-unsupported") setVersionBlocked(true);
 					setFailure({
 						code: code ?? "request-failed",
-						label: code === void 0 ? t(SAVE_FAILED_KEY, { cause: describeCause(cause) }) : t(SAVE_FAILURE_KEYS[code] ?? SAVE_FAILED_KEY, { cause: describeCause(cause) }),
+						label: code === void 0 ? t(SAVE_FAILED_KEY, { cause: describeCause$1(t, cause) }) : t(SAVE_FAILURE_KEYS[code] ?? SAVE_FAILED_KEY, { cause: describeCause$1(t, cause) }),
 						detail: status === void 0 ? void 0 : t("scope.serverSaid", {
 							code,
 							status
@@ -1275,7 +1495,7 @@ window.__ModuleLoader__.load({
 					setFailure(void 0);
 				}, (cause) => {
 					setBusy(false);
-					setLoadError(describeCause(cause));
+					setLoadError(describeCause$1(t, cause));
 				});
 			}, [client, seedFromDocument]);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
@@ -1502,6 +1722,18 @@ window.__ModuleLoader__.load({
 		* before this task the literal here rendered in English on a zh page.
 		*/
 		var EVENT_SOURCE_UNAVAILABLE = "event-source-unavailable";
+		/**
+		* One description for a cause, shared by the two catches below so they cannot
+		* drift. Two markers get the dictionary's own sentence — the missing
+		* `EventSource` and a request that never answered (`api.ts`'s ceiling) — because
+		* both are INTERNAL tokens that must never render; everything else is the
+		* foreign message, interpolated verbatim as data.
+		*/
+		function describeCause(t, cause) {
+			if (cause instanceof Error && cause.message === EVENT_SOURCE_UNAVAILABLE) return t("app.eventSourceUnavailable");
+			if (cause instanceof Error && cause.message === "cherry-remote.request-timeout") return t("app.error.timeout");
+			return cause instanceof Error ? cause.message : String(cause);
+		}
 		/** Parses one SSE frame payload, ignoring a malformed one rather than crashing. */
 		function parseFrame(data) {
 			try {
@@ -1510,7 +1742,7 @@ window.__ModuleLoader__.load({
 				return;
 			}
 		}
-		function App({ eventSourceFactory = defaultEventSourceFactory, codeLifetimeMs, scopeClient }) {
+		function App({ eventSourceFactory = defaultEventSourceFactory, codeLifetimeMs, runLifetimeMs, scopeClient }) {
 			const t = useT();
 			const [devices, setDevices] = (0, react.useState)([]);
 			const [states, setStates] = (0, react.useState)({});
@@ -1523,7 +1755,7 @@ window.__ModuleLoader__.load({
 				try {
 					source = eventSourceFactory(`${API_BASE}/events`);
 				} catch (cause) {
-					setError(cause instanceof Error && cause.message === EVENT_SOURCE_UNAVAILABLE ? t("app.eventSourceUnavailable") : cause instanceof Error ? cause.message : String(cause));
+					setError(describeCause(t, cause));
 					return;
 				}
 				const onDeviceState = (event) => {
@@ -1555,7 +1787,7 @@ window.__ModuleLoader__.load({
 					setListed(true);
 					setError(void 0);
 				}, (cause) => {
-					setError(cause instanceof Error ? cause.message : String(cause));
+					setError(describeCause(t, cause));
 					setListed(true);
 				});
 			}, []);
@@ -1604,6 +1836,7 @@ window.__ModuleLoader__.load({
 						subscribed,
 						progress,
 						...codeLifetimeMs === void 0 ? {} : { codeLifetimeMs },
+						...runLifetimeMs === void 0 ? {} : { runLifetimeMs },
 						onRunStart: startRun,
 						onSettled
 					}),
@@ -1616,7 +1849,7 @@ window.__ModuleLoader__.load({
 								id: "cherry-devices-title",
 								children: t("app.devices.heading")
 							}),
-							sorted.length === 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							sorted.length === 0 && error === void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 								className: "cherry-hint",
 								children: listed ? t("app.devices.empty") : t("app.devices.loading")
 							}),
@@ -1636,7 +1869,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region ui/src/styles.css?inline
-		var styles_default = "/**\n * The settings page's own styles.\n *\n * Hand-written CSS, no UI framework (ruling 6). The palette follows the DSH web\n * client's dark-friendly aesthetic: it leans on `currentColor` and a few\n * neutral surface variables so the page reads correctly on both a dark and a\n * light shell, and the five state colours stay distinguishable (and are always paired\n * with a text label — colour alone is never the status).\n */\n.cherry-settings {\n  display: flex;\n  flex-direction: column;\n  gap: 20px;\n  padding: 16px;\n  color: inherit;\n  font-size: 13px;\n  line-height: 1.6;\n}\n\n.cherry-header h2 {\n  margin: 0 0 4px;\n  font-size: 16px;\n}\n\n.cherry-panel {\n  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);\n  border-radius: 10px;\n  padding: 14px 16px;\n  background: color-mix(in srgb, currentColor 4%, transparent);\n}\n\n.cherry-panel h3 {\n  margin: 0 0 8px;\n  font-size: 14px;\n}\n\n.cherry-hint {\n  margin: 4px 0;\n  opacity: 0.7;\n  font-size: 12px;\n}\n\n.cherry-mono {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 12px;\n}\n\n/* --- pairing wizard ------------------------------------------------------ */\n\n.cherry-steps {\n  margin: 8px 0 12px;\n  padding-left: 20px;\n  opacity: 0.85;\n}\n\n.cherry-pair-form {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  align-items: flex-start;\n}\n\n.cherry-pair-form textarea,\n.cherry-inline-form input {\n  width: 100%;\n  box-sizing: border-box;\n  padding: 6px 8px;\n  border-radius: 6px;\n  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);\n  background: color-mix(in srgb, currentColor 6%, transparent);\n  color: inherit;\n  font: inherit;\n}\n\n.cherry-progress {\n  margin-top: 10px;\n  padding: 10px 12px;\n  border-radius: 8px;\n  border: 1px dashed color-mix(in srgb, currentColor 25%, transparent);\n}\n\n.cherry-code {\n  margin-top: 10px;\n  padding: 12px;\n  border-radius: 8px;\n  text-align: center;\n  border: 1px solid color-mix(in srgb, currentColor 30%, transparent);\n}\n\n.cherry-code-digits {\n  display: block;\n  margin-top: 6px;\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 26px;\n  letter-spacing: 0.3em;\n}\n\n.cherry-ok {\n  color: #3fb950;\n}\n\n.cherry-error {\n  color: #f85149;\n}\n\n/* --- enablement scope panel ---------------------------------------------- */\n\n/* All three visible as a group, never as one combined verdict: the mode radio\n   pair, the workspace ticks and the save that commits them (§6.4). */\n.cherry-scope-modes {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 14px;\n  margin: 8px 0;\n  padding: 6px 10px;\n  border: 1px dashed color-mix(in srgb, currentColor 20%, transparent);\n  border-radius: 8px;\n}\n\n.cherry-scope-modes label {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n}\n\n.cherry-scope-degraded,\n.cherry-scope-options,\n.cherry-scope-stale ul,\n.cherry-scope-unmatched ul {\n  margin: 6px 0;\n  padding-left: 18px;\n}\n\n.cherry-scope-degraded li,\n.cherry-scope-options li {\n  margin: 2px 0;\n}\n\n.cherry-scope-options label {\n  display: inline-flex;\n  align-items: baseline;\n  gap: 8px;\n}\n\n.cherry-scope-option-title {\n  font-weight: 600;\n}\n\n/* The two diagnostic boxes are deliberately separate surfaces: a deleted\n   workspace and an unmatched cwd are different answers (§6.1/§6.4). */\n.cherry-scope-stale,\n.cherry-scope-unmatched {\n  margin-top: 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  border: 1px dashed color-mix(in srgb, currentColor 25%, transparent);\n}\n\n.cherry-scope-save {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 10px;\n  margin-top: 12px;\n  padding-top: 10px;\n  border-top: 1px dashed color-mix(in srgb, currentColor 18%, transparent);\n}\n\n/* --- device cards -------------------------------------------------------- */\n\n.cherry-cards {\n  display: grid;\n  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));\n  gap: 12px;\n  margin: 8px 0 0;\n  padding: 0;\n  list-style: none;\n}\n\n.cherry-card {\n  border: 1px solid color-mix(in srgb, currentColor 15%, transparent);\n  border-radius: 10px;\n  padding: 12px;\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n\n.cherry-card-head {\n  display: flex;\n  align-items: center;\n  gap: 10px;\n}\n\n.cherry-card-title {\n  display: flex;\n  flex-direction: column;\n  min-width: 0;\n  flex: 1;\n}\n\n.cherry-state-label {\n  font-size: 11px;\n  opacity: 0.7;\n}\n\n.cherry-card-actions {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 6px;\n}\n\n.cherry-card-facts {\n  display: grid;\n  grid-template-columns: auto 1fr;\n  gap: 2px 10px;\n  margin: 0;\n  font-size: 12px;\n}\n\n.cherry-card-facts dt {\n  opacity: 0.6;\n}\n\n.cherry-card-facts dd {\n  margin: 0;\n  overflow-wrap: anywhere;\n}\n\n.cherry-inline-form {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  align-items: flex-start;\n  padding-top: 6px;\n  border-top: 1px dashed color-mix(in srgb, currentColor 18%, transparent);\n}\n\n/* SCOPED DELIBERATELY. This stylesheet is injected into the HOST page's\n   document head, not a sandboxed frame, so a bare `button {}` rule restyles\n   every button in the host UI — a plugin must not do that. Every top-level\n   selector in this file is therefore rooted at a plugin-owned class in the\n   `cherry-` namespace: the element rules here at the plugin's own\n   `.cherry-settings` container, and the rest at their own component classes\n   (`.cherry-panel`, `.cherry-card`, `.cherry-state`, …). None of them matches\n   anything outside the markup this plugin renders. */\n.cherry-settings button {\n  padding: 4px 10px;\n  border-radius: 6px;\n  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);\n  background: color-mix(in srgb, currentColor 8%, transparent);\n  color: inherit;\n  font: inherit;\n  cursor: pointer;\n}\n\n.cherry-settings button:disabled {\n  opacity: 0.5;\n  cursor: not-allowed;\n}\n\n/* --- five-state light ---------------------------------------------------- */\n\n.cherry-state {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n  flex: none;\n}\n\n.cherry-state-dot {\n  width: 10px;\n  height: 10px;\n  border-radius: 50%;\n  background: var(--cherry-state-color, #8b949e);\n  box-shadow: 0 0 6px var(--cherry-state-color, transparent);\n}\n\n.cherry-state[data-state='connected'] {\n  --cherry-state-color: #3fb950;\n}\n\n.cherry-state[data-state='connecting'] {\n  --cherry-state-color: #d29922;\n}\n\n.cherry-state[data-state='offline'] {\n  --cherry-state-color: #8b949e;\n}\n\n.cherry-state[data-state='disabled'] {\n  --cherry-state-color: #6e7681;\n}\n\n.cherry-state[data-state='identity-mismatch'] {\n  --cherry-state-color: #f85149;\n}\n\n.cherry-state[data-state='unknown'] {\n  --cherry-state-color: #484f58;\n}\n";
+		var styles_default = "/**\n * The settings page's own styles.\n *\n * Hand-written CSS, no UI framework (ruling 6). The palette follows the DSH web\n * client's dark-friendly aesthetic: it leans on `currentColor` and a few\n * neutral surface variables so the page reads correctly on both a dark and a\n * light shell, and the five state colours stay distinguishable (and are always paired\n * with a text label — colour alone is never the status).\n */\n.cherry-settings {\n  display: flex;\n  flex-direction: column;\n  gap: 20px;\n  padding: 16px;\n  color: inherit;\n  font-size: 13px;\n  line-height: 1.6;\n}\n\n.cherry-header h2 {\n  margin: 0 0 4px;\n  font-size: 16px;\n}\n\n.cherry-panel {\n  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);\n  border-radius: 10px;\n  padding: 14px 16px;\n  background: color-mix(in srgb, currentColor 4%, transparent);\n}\n\n.cherry-panel h3 {\n  margin: 0 0 8px;\n  font-size: 14px;\n}\n\n.cherry-hint {\n  margin: 4px 0;\n  opacity: 0.7;\n  font-size: 12px;\n}\n\n.cherry-mono {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 12px;\n}\n\n/* --- pairing wizard ------------------------------------------------------ */\n\n.cherry-steps {\n  margin: 8px 0 12px;\n  padding-left: 20px;\n  opacity: 0.85;\n}\n\n.cherry-pair-form {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  align-items: flex-start;\n}\n\n.cherry-pair-form textarea,\n.cherry-inline-form input {\n  width: 100%;\n  box-sizing: border-box;\n  padding: 6px 8px;\n  border-radius: 6px;\n  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);\n  background: color-mix(in srgb, currentColor 6%, transparent);\n  color: inherit;\n  font: inherit;\n}\n\n.cherry-progress {\n  margin-top: 10px;\n  padding: 10px 12px;\n  border-radius: 8px;\n  border: 1px dashed color-mix(in srgb, currentColor 25%, transparent);\n}\n\n.cherry-code {\n  margin-top: 10px;\n  padding: 12px;\n  border-radius: 8px;\n  text-align: center;\n  border: 1px solid color-mix(in srgb, currentColor 30%, transparent);\n}\n\n.cherry-code-digits {\n  display: block;\n  margin-top: 6px;\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 26px;\n  letter-spacing: 0.3em;\n}\n\n.cherry-ok {\n  color: #3fb950;\n}\n\n.cherry-error {\n  color: #f85149;\n}\n\n/* --- enablement scope panel ---------------------------------------------- */\n\n/* All three visible as a group, never as one combined verdict: the mode radio\n   pair, the workspace ticks and the save that commits them (§6.4). */\n.cherry-scope-modes {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 14px;\n  margin: 8px 0;\n  padding: 6px 10px;\n  border: 1px dashed color-mix(in srgb, currentColor 20%, transparent);\n  border-radius: 8px;\n}\n\n.cherry-scope-modes label {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n}\n\n.cherry-scope-degraded,\n.cherry-scope-options,\n.cherry-scope-stale ul,\n.cherry-scope-unmatched ul {\n  margin: 6px 0;\n  padding-left: 18px;\n}\n\n.cherry-scope-degraded li,\n.cherry-scope-options li {\n  margin: 2px 0;\n}\n\n.cherry-scope-options label {\n  display: inline-flex;\n  align-items: baseline;\n  gap: 8px;\n}\n\n.cherry-scope-option-title {\n  font-weight: 600;\n}\n\n/* The two diagnostic boxes are deliberately separate surfaces: a deleted\n   workspace and an unmatched cwd are different answers (§6.1/§6.4). */\n.cherry-scope-stale,\n.cherry-scope-unmatched {\n  margin-top: 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  border: 1px dashed color-mix(in srgb, currentColor 25%, transparent);\n}\n\n.cherry-scope-save {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 10px;\n  margin-top: 12px;\n  padding-top: 10px;\n  border-top: 1px dashed color-mix(in srgb, currentColor 18%, transparent);\n}\n\n/* --- device cards -------------------------------------------------------- */\n\n.cherry-cards {\n  display: grid;\n  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));\n  gap: 12px;\n  margin: 8px 0 0;\n  padding: 0;\n  list-style: none;\n}\n\n.cherry-card {\n  border: 1px solid color-mix(in srgb, currentColor 15%, transparent);\n  border-radius: 10px;\n  padding: 12px;\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n\n.cherry-card-head {\n  display: flex;\n  align-items: center;\n  gap: 10px;\n}\n\n.cherry-card-title {\n  display: flex;\n  flex-direction: column;\n  min-width: 0;\n  flex: 1;\n}\n\n.cherry-state-label {\n  font-size: 11px;\n  opacity: 0.7;\n}\n\n.cherry-card-actions {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 6px;\n}\n\n.cherry-card-facts {\n  display: grid;\n  grid-template-columns: auto 1fr;\n  gap: 2px 10px;\n  margin: 0;\n  font-size: 12px;\n}\n\n.cherry-card-facts dt {\n  opacity: 0.6;\n}\n\n.cherry-card-facts dd {\n  margin: 0;\n  overflow-wrap: anywhere;\n}\n\n/* A per-host action list (issue #204): the address, then its own control. The\n   buttons stay small so a record with a dozen candidates stays ONE fact row\n   instead of a column of chrome. */\n.cherry-address-list {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 4px 10px;\n  margin: 0;\n  padding: 0;\n  list-style: none;\n}\n\n.cherry-address-list li {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n}\n\n.cherry-address-list button {\n  padding: 0 6px;\n  font-size: 11px;\n  line-height: 1.6;\n}\n\n.cherry-inline-form {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  align-items: flex-start;\n  padding-top: 6px;\n  border-top: 1px dashed color-mix(in srgb, currentColor 18%, transparent);\n}\n\n/* SCOPED DELIBERATELY. This stylesheet is injected into the HOST page's\n   document head, not a sandboxed frame, so a bare `button {}` rule restyles\n   every button in the host UI — a plugin must not do that. Every top-level\n   selector in this file is therefore rooted at a plugin-owned class in the\n   `cherry-` namespace: the element rules here at the plugin's own\n   `.cherry-settings` container, and the rest at their own component classes\n   (`.cherry-panel`, `.cherry-card`, `.cherry-state`, …). None of them matches\n   anything outside the markup this plugin renders. */\n.cherry-settings button {\n  padding: 4px 10px;\n  border-radius: 6px;\n  border: 1px solid color-mix(in srgb, currentColor 25%, transparent);\n  background: color-mix(in srgb, currentColor 8%, transparent);\n  color: inherit;\n  font: inherit;\n  cursor: pointer;\n}\n\n.cherry-settings button:disabled {\n  opacity: 0.5;\n  cursor: not-allowed;\n}\n\n/* --- five-state light ---------------------------------------------------- */\n\n.cherry-state {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n  flex: none;\n}\n\n.cherry-state-dot {\n  width: 10px;\n  height: 10px;\n  border-radius: 50%;\n  background: var(--cherry-state-color, #8b949e);\n  box-shadow: 0 0 6px var(--cherry-state-color, transparent);\n}\n\n.cherry-state[data-state='connected'] {\n  --cherry-state-color: #3fb950;\n}\n\n.cherry-state[data-state='connecting'] {\n  --cherry-state-color: #d29922;\n}\n\n.cherry-state[data-state='offline'] {\n  --cherry-state-color: #8b949e;\n}\n\n.cherry-state[data-state='disabled'] {\n  --cherry-state-color: #6e7681;\n}\n\n.cherry-state[data-state='identity-mismatch'] {\n  --cherry-state-color: #f85149;\n}\n\n.cherry-state[data-state='unknown'] {\n  --cherry-state-color: #484f58;\n}\n";
 		//#endregion
 		//#region ui/src/main.tsx
 		/** The slot a settings page registers into, per the shell's settings contract. */

package/package.json

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