dsh-plugin-notify-sounds 1.6.9 → 1.8.0

package/lib/client.js

@@ -97,6 +97,18 @@ window.__ModuleLoader__.load({
 		 */
 		const isMac = () => typeof navigator !== "undefined" && /Mac/i.test(`${navigator.platform ?? ""} ${navigator.userAgent ?? ""}`);
 
+		/**
+		 * Whether the window-title mark has anywhere to appear.
+		 *
+		 * Only the macOS Desktop shell fails this, for the reason above. The
+		 * row's switch is DISABLED rather than merely re-described: an enabled
+		 * switch that the user can turn on and that then never does anything is
+		 * worse than one that says it is not available yet — the old copy read
+		 * like a working feature with a caveat, so people turned it on and
+		 * waited.
+		 */
+		const titleFlashUnavailable = () => isMac() && isDesktopShell();
+
 		/** Stylesheet class names, one projection the components read. */
 		const css = {
 			section: "dsh-notify-sounds-section",
@@ -161,6 +173,8 @@ window.__ModuleLoader__.load({
 			"question.description": "智能体向你提问时播放",
 			"completion.title": "任务完成时",
 			"completion.description": "会话由运行转为空闲时播放",
+			"goalFinalOnly.title": "目标模式下只在最终轮提醒",
+			"goalFinalOnly.description": "目标模式会自动进行多轮；开启后中间轮结束时保持安静，只在目标结束（或暂停、受阻）时响一次。普通对话不受影响",
 			"subagent.title": "子智能体的提醒",
 			"subagent.description": "子智能体（后台任务）完成或需要决策时也提醒；关闭后只提醒主对话",
 			"onlyWhenHidden.title": "仅在页面不可见时提示",
@@ -178,7 +192,7 @@ window.__ModuleLoader__.load({
 			"systemNotify.unsupported": "当前环境不支持系统通知",
 			"titleFlash.title": "窗口标题提醒",
 			"titleFlash.description": "页面处于后台时，在窗口标题前加文字标记（待处理 / 已完成），便于在任务栏察觉；回到页面后自动清除",
-			"titleFlash.macUnsupported": "macOS 暂不支持：标题栏隐藏、Dock 也没有窗口标题，标记无处显示（只在「窗口」菜单 / Mission Control 里可见）",
+			"titleFlash.macUnsupported": "macOS 暂不支持，开关已禁用：标题栏隐藏、Dock 也没有窗口标题，标记无处显示（只在「窗口」菜单 / Mission Control 里可见）",
 			"titleFlash.pending": "待处理",
 			"titleFlash.done": "已完成",
 			"renotify.title": "未处理决策重复提醒",
@@ -219,10 +233,21 @@ window.__ModuleLoader__.load({
 			"update.available": "有新版",
 			"update.failed": "检查失败（网络不可用）",
 			"update.apply": "立即更新",
+			"update.desktopGuidance": "升级请走包管理器：设置 → 插件 → 卸载本插件，再重新添加 dsh-plugin-notify-sounds。安装由包管理器完成，升级才能留在新版（本插件不再自己替换文件）",
+			"update.webGuidance": "在终端执行 dsh plugin --profile {profile} add dsh-plugin-notify-sounds@{version}",
+			"update.unregistered": "这个安装没有被包管理器登记（记录仍为 {recorded}），下次安装其他插件时可能被退回。请按上面的方式重新安装一次。",
 			"update.updating": "更新中…",
-			"update.done": "更新完成",
-			"update.restart": "重启 DSH 后生效",
+			"update.doneDetail": "更新完成：{from} → {to}，重启 DSH 后生效",
 			"update.applyFailed": "更新失败（{stage}），已恢复原状",
+			"update.stage.check": "检查",
+			"update.stage.download": "下载",
+			"update.stage.verify": "校验",
+			"update.stage.unpack": "解包",
+			"update.stage.manifest": "核对包信息",
+			"update.stage.replace": "替换文件",
+			"update.stage.unknown": "未知阶段",
+			"update.retry": "通常是网络或代理的临时问题，稍后重试即可；若反复失败，可到 {url} 手动安装",
+			"update.reinstall": "可在 DSH 的 设置 → 插件 里先卸载本插件，再添加 dsh-plugin-notify-sounds 重新安装；仓库：{url}",
 		};
 
 		/** English dictionary, checked complete against the zh key set. */
@@ -257,7 +282,7 @@ window.__ModuleLoader__.load({
 			"systemNotify.unsupported": "System notifications are unavailable in this environment",
 			"titleFlash.title": "Window title alert",
 			"titleFlash.description": "While the page is hidden, mark the window title as waiting for you or finished, so the taskbar shows it; cleared when you return",
-			"titleFlash.macUnsupported": "Not supported on macOS: the title bar is hidden and the Dock shows no window title, so the mark has nowhere to appear (only the Window menu and Mission Control would show it)",
+			"titleFlash.macUnsupported": "Not supported on macOS, so this switch is disabled: the title bar is hidden and the Dock shows no window title, so the mark has nowhere to appear (only the Window menu and Mission Control would show it)",
 			"titleFlash.pending": "Waiting for you",
 			"titleFlash.done": "Finished",
 			"renotify.title": "Repeat unanswered decisions",
@@ -266,6 +291,8 @@ window.__ModuleLoader__.load({
 			"renotify.interval": "Interval",
 			"renotify.minutes": "{n} min",
 			"quiet.title": "Quiet hours",
+			"goalFinalOnly.title": "Only alert on the final goal round",
+			"goalFinalOnly.description": "A goal runs several automatic rounds; with this on, intermediate rounds stay silent and one chime marks the end of the goal (or a pause or block). Ordinary sessions are unaffected",
 			"quiet.description": "No alerts during this daily time range (may wrap past midnight, e.g. 22:00 to 08:00)",
 			"quiet.start": "Start time",
 			"quiet.end": "End time",
@@ -298,10 +325,21 @@ window.__ModuleLoader__.load({
 			"update.available": "New version available",
 			"update.failed": "Check failed (no network)",
 			"update.apply": "Update now",
+			"update.desktopGuidance": "Update through the package manager: Settings → Plugins → remove this plugin, then add dsh-plugin-notify-sounds again. The installer keeps the upgrade (this plugin no longer replaces its own files)",
+			"update.webGuidance": "Run dsh plugin --profile {profile} add dsh-plugin-notify-sounds@{version} in a terminal",
+			"update.unregistered": "This install is not registered with the package manager (it still records {recorded}), so a later plugin install may roll it back. Reinstall it with the step above.",
 			"update.updating": "Updating…",
-			"update.done": "Updated",
-			"update.restart": "restart DSH to load it",
+			"update.doneDetail": "Updated: {from} → {to} — restart DSH to load it",
 			"update.applyFailed": "Update failed ({stage}) — the previous version is intact",
+			"update.stage.check": "check",
+			"update.stage.download": "download",
+			"update.stage.verify": "checksum",
+			"update.stage.unpack": "unpack",
+			"update.stage.manifest": "package check",
+			"update.stage.replace": "file replacement",
+			"update.stage.unknown": "unknown step",
+			"update.retry": "This is usually a temporary network or proxy problem — try again later. If it keeps failing, install manually from {url}",
+			"update.reinstall": "Remove this plugin under Settings → Plugins, then add dsh-plugin-notify-sounds again. Repository: {url}",
 		};
 		//#endregion
 
@@ -443,19 +481,27 @@ window.__ModuleLoader__.load({
 		 * Peak-normalization gain for one decoded buffer: scales the loudest
 		 * sample toward full scale, boosting at most 4× so near-silent files
 		 * do not get blown up.
+		 *
+		 * Every sample is visited, deliberately. An earlier version stepped
+		 * through the buffer taking every 8th frame and claimed the peak would
+		 * be caught anyway because "neighbouring samples carry the same
+		 * magnitude" — that only holds for a heavily oversampled signal. At
+		 * 44.1 kHz a 10 kHz component has about 4.4 samples per period, so a
+		 * stride of 8 aliases against it and can systematically miss the real
+		 * peak; a tone near fs/8 is the extreme case. An underestimated peak
+		 * means a boost that is too large, so the custom sound plays hot and
+		 * can clip on its loudest transient.
+		 *
+		 * The cost is not on a playback path: this runs once per uploaded file,
+		 * right after `decodeAudioData` (which costs far more), and the result
+		 * is cached alongside the buffer in `customSoundCache`.
 		 */
 		function normalizedGain(buffer) {
 			try {
 				let peak = 0;
-				// Sample every 8th frame: a peak that would clip is still
-				// caught by any reasonably strided scan (audio waveforms are
-				// smooth enough that adjacent samples carry the same
-				// magnitude), and this keeps a 30-second upload off the main
-				// thread's critical path.
-				const stride = 8;
 				for (let channel = 0; channel < buffer.numberOfChannels; channel++) {
 					const data = buffer.getChannelData(channel);
-					for (let i = 0; i < data.length; i += stride) {
+					for (let i = 0; i < data.length; i++) {
 						const magnitude = Math.abs(data[i]);
 						if (magnitude > peak) peak = magnitude;
 					}
@@ -574,11 +620,25 @@ window.__ModuleLoader__.load({
 				// Release the master gain once the tail has faded. Without
 				// this, every play leaves a gain node permanently wired to
 				// the destination — a slow audio-node leak on long sessions.
-				setTimeout(() => {
+				const remaining = () => (t0 + tail + 0.1 - engine.currentTime) * 1000;
+				const release = (rechecked) => {
 					try {
+						// The delay was computed when this was scheduled, and a
+						// suspended context freezes `currentTime`: without this
+						// second look, a timer that comes due during a freeze
+						// disconnects a tail that is still playing. Re-check
+						// once — not in a loop, so a clock that never advances
+						// (a test's frozen mock, a context suspended for good)
+						// still ends with the node released.
+						if (!rechecked && remaining() > 5) {
+							setTimeout(() => release(true), remaining() + 50);
+							return;
+						}
 						master.disconnect();
 					} catch {}
-				}, Math.max(0, (t0 + tail + 0.1 - engine.currentTime) * 1000 + 50));
+				};
+				const timer = setTimeout(() => release(false), Math.max(0, remaining() + 50));
+				timer.unref?.();
 			});
 		}
 
@@ -814,8 +874,183 @@ window.__ModuleLoader__.load({
 		/** Route the Host half answers the update check on; must match the Host half's UPDATE_CHECK_PATH. */
 		const UPDATE_CHECK_PATH = "/notify-sounds/update/check";
 
-		/** Route the Host half applies an update through; must match the Host half's UPDATE_APPLY_PATH. */
-		const UPDATE_APPLY_PATH = "/notify-sounds/update/apply";
+
+		/**
+		 * Where a user goes when the one-click update cannot finish.
+		 *
+		 * Shown as plain selectable text rather than a link: the Desktop shell
+		 * is a `dsh-app://` page and the Settings primitives expose no external
+		 * link component, so a URL the user can copy is the honest form — a
+		 * button that silently did nothing here would be worse than no button.
+		 */
+		const REPOSITORY_URL = "https://github.com/BillCx330/dsh-plugin-notify-sounds";
+
+		/**
+		 * Every stage the Host can report, and whether a fresh install is the remedy.
+		 *
+		 * Keyed off the stage rather than off the message: telling someone whose
+		 * download timed out to uninstall the plugin would be actively bad
+		 * advice, and telling someone whose archive was rejected to "try again
+		 * later" leaves them with no way forward at all. `true` means the
+		 * payload itself could not be applied, which retrying will not change.
+		 */
+		const UPDATE_STAGES = { check: false, download: false, verify: false, unpack: true, manifest: true, replace: true };
+
+		/** The localized word for a Host-side update stage. */
+		const stageWord = (t, stage) => t(`update.stage.${typeof stage === "string" && Object.hasOwn(UPDATE_STAGES, stage) ? stage : "unknown"}`);
+
+		/** `v1.2.3` for display, `?` when the Host reported no version. */
+		const formatVersion = (text) => (typeof text === "string" && text !== "" ? `v${text}` : "?");
+
+		/**
+		 * The line reporting an installation that landed.
+		 *
+		 * Composed here rather than in JSX so the notice above the section and
+		 * the row inside it say exactly the same thing, and so the whole
+		 * sentence — punctuation included — lives in the dictionaries instead
+		 * of being assembled from fragments at the call site (which is how the
+		 * English UI ended up with full-width stops).
+		 */
+		const updateAppliedText = (t, applied) => t("update.doneDetail", { from: formatVersion(applied?.from), to: formatVersion(applied?.to) });
+
+		/**
+		 * The two lines a failed update shows: what happened, and what to do.
+		 *
+		 * The remedy is chosen from the stage the Host reported, never from the
+		 * message: a download that timed out must not be answered with "uninstall
+		 * and reinstall", and an archive that was refused must not be answered
+		 * with "try again later".
+		 */
+		const updateFailureText = (t, failed, current) => {
+			// Name both versions whenever the target is known: "the update
+			// failed" on its own cannot be acted on afterwards, and this is the
+			// line a user copies into a bug report.
+			const named = typeof failed?.to === "string" ? `${formatVersion(current)} → ${formatVersion(failed.to)} · ` : "";
+			return {
+				detail: `${named}${t("update.applyFailed", { stage: stageWord(t, failed?.stage) })}`,
+				advice: UPDATE_STAGES[failed?.stage] === true
+					? t("update.reinstall", { url: REPOSITORY_URL })
+					: t("update.retry", { url: REPOSITORY_URL }),
+			};
+		};
+
+		/** Channel name and claim key shared by every page of this origin. */
+		const ALERT_CHANNEL = "dsh-notify-sounds:alerts";
+		const ALERT_LEADER_KEY = "dsh-notify-sounds:leader";
+		/** How often the leader re-asserts, and when a quiet claim is considered abandoned. */
+		const ALERT_HEARTBEAT_MS = 5000;
+		const ALERT_STALE_MS = 15000;
+
+		/**
+		 * `localStorage`, when this page has one that answers.
+		 *
+		 * Even reading it can throw where storage is blocked (private mode, a
+		 * sandboxed frame), and a page without it simply leads itself.
+		 *
+		 * @returns the storage, or undefined.
+		 */
+		const safeAlertStorage = () => {
+			try {
+				if (typeof localStorage === "undefined") return undefined;
+				localStorage.getItem(ALERT_LEADER_KEY);
+				return localStorage;
+			} catch {
+				return undefined;
+			}
+		};
+
+		/**
+		 * Elect one page among the tabs — and windows — of this GUI to be the one
+		 * that speaks.
+		 *
+		 * Two pages are two independent subscribers to the same session facts:
+		 * left alone, one decision rings the sound twice, raises two system
+		 * notifications and runs two repeat reminders (the settings even say
+		 * "at most one quiet check a day" while both of them check). The election
+		 * is a claim in `localStorage`, which every page of this origin shares,
+		 * refreshed by a heartbeat; a claim that stops being refreshed is taken
+		 * over, so a closed, crashed or frozen tab hands the role on within a few
+		 * seconds. `BroadcastChannel` only makes a claim heard sooner — the
+		 * correctness rests on the stored claim, because whoever wrote it last
+		 * owns the role and every page re-reads it rather than trusting a message.
+		 *
+		 * The title mark is deliberately NOT gated by this: each window and each
+		 * tab has its own title, so marking them all is right, while a sound and
+		 * a toast belong to the machine.
+		 *
+		 * Pages that can use neither mechanism — the smoke harness, a hardened
+		 * browser context — lead themselves, which is the behaviour before this
+		 * existed.
+		 *
+		 * @returns `{ isLeader, refresh, dispose }`, where `refresh` re-runs the
+		 *   election (the tests drive it instead of waiting for a heartbeat).
+		 */
+		function createAlertLeader() {
+			const storage = safeAlertStorage();
+			const Channel = typeof BroadcastChannel === "function" ? BroadcastChannel : undefined;
+			if (storage === undefined || Channel === undefined) {
+				return { isLeader: () => true, refresh: () => {}, dispose: () => {} };
+			}
+			const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+			let channel;
+			try {
+				channel = new Channel(ALERT_CHANNEL);
+			} catch {
+				return { isLeader: () => true, refresh: () => {}, dispose: () => {} };
+			}
+			let leader = false;
+			const readClaim = () => {
+				try {
+					const parsed = JSON.parse(storage.getItem(ALERT_LEADER_KEY) ?? "null");
+					return parsed !== null && typeof parsed?.id === "string" && Number.isFinite(parsed?.at) ? parsed : undefined;
+				} catch {
+					return undefined;
+				}
+			};
+			const claim = () => {
+				leader = true;
+				try {
+					storage.setItem(ALERT_LEADER_KEY, JSON.stringify({ id, at: Date.now() }));
+				} catch {}
+				try {
+					channel.postMessage({ id });
+				} catch {}
+			};
+			const refresh = () => {
+				const current = readClaim();
+				if (current === undefined || current.id === id) {
+					claim();
+					return;
+				}
+				// Somebody else holds a claim. While it is fresh this page stays
+				// silent; once it goes stale its holder is gone and this page
+				// takes over.
+				if (Date.now() - current.at < ALERT_STALE_MS) {
+					leader = false;
+					return;
+				}
+				claim();
+			};
+			channel.onmessage = (event) => {
+				if (event?.data?.id !== id) refresh();
+			};
+			const timer = setInterval(refresh, ALERT_HEARTBEAT_MS);
+			timer.unref?.();
+			refresh();
+			return {
+				isLeader: () => leader,
+				refresh,
+				dispose: () => {
+					clearInterval(timer);
+					try {
+						if (leader && readClaim()?.id === id) storage.removeItem(ALERT_LEADER_KEY);
+					} catch {}
+					try {
+						channel.close();
+					} catch {}
+				},
+			};
+		}
 
 		/**
 		 * Show one OS notification; every failure mode is silent.
@@ -981,8 +1216,7 @@ window.__ModuleLoader__.load({
 					.catch(() => {});
 			}, [autoCheck]);
 			if (applied === undefined || typeof applied.to !== "string") return null;
-			const version = (text) => (typeof text === "string" && text !== "" ? `v${text}` : "?");
-			return h("div", { className: css.hint, key: "text" }, `${t("update.done")}：${version(applied.from)} → ${version(applied.to)}，${t("update.restart")}`);
+			return h("div", { className: css.hint, key: "text" }, updateAppliedText(t, applied));
 		}
 
 		function NotifySoundsSection({ useConfig, setField, preview, t }) {
@@ -1099,17 +1333,6 @@ window.__ModuleLoader__.load({
 						},
 						onPreview: (id) => preview(id, volume),
 					}),
-					h(SwitchRow, {
-						key: "subagent",
-						t,
-						title: t("subagent.title"),
-						description: t("subagent.description"),
-						label: t("subagent.title"),
-						checked: value?.subagentAlerts === true,
-						disabled,
-						failed: failedField === "subagentAlerts",
-						onChange: (next) => write("subagentAlerts", next),
-					}),
 					h(CustomSoundRow, {
 						key: "custom",
 						t,
@@ -1152,6 +1375,28 @@ window.__ModuleLoader__.load({
 						},
 						onPreview: () => preview("custom", volume),
 					}),
+					h(SwitchRow, {
+						key: "subagent",
+						t,
+						title: t("subagent.title"),
+						description: t("subagent.description"),
+						label: t("subagent.title"),
+						checked: value?.subagentAlerts === true,
+						disabled,
+						failed: failedField === "subagentAlerts",
+						onChange: (next) => write("subagentAlerts", next),
+					}),
+					h(SwitchRow, {
+						key: "goalFinalOnly",
+						t,
+						title: t("goalFinalOnly.title"),
+						description: t("goalFinalOnly.description"),
+						label: t("goalFinalOnly.title"),
+						checked: value?.goalFinalOnly === true,
+						disabled,
+						failed: failedField === "goalFinalOnly",
+						onChange: (next) => write("goalFinalOnly", next),
+					}),
 					h(SystemNotifyRow, {
 						key: "systemNotify",
 						t,
@@ -1170,10 +1415,10 @@ window.__ModuleLoader__.load({
 						// document title like any other, so this is not
 						// applied there. iOS Safari's UA also contains "like
 						// Mac OS X" — `isDesktopShell` keeps it out.
-						description: isMac() && isDesktopShell() ? t("titleFlash.macUnsupported") : t("titleFlash.description"),
+						description: titleFlashUnavailable() ? t("titleFlash.macUnsupported") : t("titleFlash.description"),
 						label: t("titleFlash.title"),
 						checked: value?.titleFlash === true,
-						disabled,
+						disabled: disabled || titleFlashUnavailable(),
 						failed: failedField === "titleFlash",
 						onChange: (next) => write("titleFlash", next),
 					}),
@@ -1709,67 +1954,51 @@ window.__ModuleLoader__.load({
 					setState({ phase: "failed" });
 				}
 			};
-			const apply = async () => {
-				setState({ phase: "updating" });
-				try {
-					const response = await fetch(UPDATE_APPLY_PATH, { method: "POST" });
-					const result = await response.json();
-					setState({ phase: result?.ok === true ? (result.upToDate === true ? "done" : "updated") : "applyFailed", result });
-				} catch {
-					setState({ phase: "applyFailed" });
-				}
-			};
 			// A cached answer makes this free; only a cold Host reaches out.
 			// Same guard as the notice: `=== true` (not `!== false`), because
 			// during the loading frame `undefined` must not be treated as
-			// permission to reach out. The button below works regardless.
+			// permission to reach out.
 			useEffect(() => {
 				if (autoCheck !== true) return;
 				check(false)();
 			}, [autoCheck]);
 			const payload = state.payload;
-			const version = (text) => (typeof text === "string" && text !== "" ? `v${text}` : "?");
-			// The Host remembers the last install and repeats it with every
-			// answer, and this row prefers that: an update swaps the client
-			// half's own file, so the page may reload and drop this row's
-			// state mid-message — the news has to survive that. The Host keeps
-			// it until DSH restarts, which is exactly as long as "restart to
-			// load it" is true.
-			const applied = payload?.applied ?? (state.phase === "updated" ? state.result : undefined);
-			const appliedDone = applied !== undefined && (applied.ok === true || typeof applied.to === "string");
+			const latest = payload?.latest === undefined ? undefined : formatVersion(payload.latest);
 			let status = payload === undefined
 				? t("update.idle")
 				: payload.updateAvailable === true
-					? `${t("update.available")} ${version(payload.latest)}`
+					? `${t("update.available")} ${latest}`
 					: t("update.uptodate");
 			if (state.phase === "checking") status = t("update.checking");
-			if (state.phase === "updating") status = t("update.updating");
-			let detail = payload === undefined ? status : `${t("update.current")} ${version(payload.current)} · ${status}`;
-			if (appliedDone) {
-				detail = `${t("update.done")}：${version(applied.from)} → ${version(applied.to)}，${t("update.restart")}`;
-			} else if (state.phase === "applyFailed") {
-				detail = t("update.applyFailed", { stage: String(state.result?.stage ?? "?") });
+			const detail = payload === undefined ? status : `${t("update.current")} ${formatVersion(payload.current)} · ${status}`;
+			// The install belongs to the package manager now: this plugin only
+			// checks, and every route below installs THROUGH pnpm so the
+			// profile's lockfile moves with the files. The two shells reach it
+			// differently, so the row spells out the one that applies here.
+			const lines = [];
+			if (payload?.unregistered === true) {
+				lines.push(h("div", { className: css.hint, key: "unregistered" }, t("update.unregistered", {
+					recorded: formatVersion(payload.recorded),
+				})));
+			}
+			if (payload?.updateAvailable === true && latest !== undefined) {
+				lines.push(h("div", { className: css.hint, key: "howto" }, isDesktopShell()
+					? t("update.desktopGuidance")
+					: t("update.webGuidance", { profile: payload.profile ?? "web", version: latest })));
 			}
-			const busy = state.phase === "checking" || state.phase === "updating";
 			return h("div", { className: css.row }, [
 				h("div", { key: "text" }, [
 					h("div", { className: css.rowTitle, key: "title" }, t("update.title")),
 					h("div", { className: css.rowDescription, key: "description" }, t("update.description")),
 					h("div", { className: css.hint, key: "status" }, detail),
+					...lines,
 				]),
 				h("div", { className: css.stackControl, key: "control" }, [
-					payload?.updateAvailable === true && !appliedDone ? h(Button, {
-						key: "apply",
-						variant: "outline",
-						size: "sm",
-						disabled: busy,
-						onClick: apply,
-					}, t("update.apply")) : null,
 					h(Button, {
 						key: "check",
 						variant: "outline",
 						size: "sm",
-						disabled: busy,
+						disabled: state.phase === "checking",
 						onClick: check(true),
 					}, t("update.check")),
 				]),
@@ -1893,6 +2122,12 @@ window.__ModuleLoader__.load({
 			let panelObserver = null;
 			let observedPanel = null;
 			const scan = (root) => {
+				// One panel-level probe before the walk. This observer fires on
+				// every change anywhere in the settings tree — a conversation
+				// streaming next to an open panel included — and once this
+				// section's cell carries the glyph there is nothing left to do;
+				// the per-cell checks below would only re-establish that.
+				if (root.querySelector(`[${NAV_ICON_MARKER}]`) !== null) return;
 				const label = t("nav");
 				for (const cell of root.querySelectorAll("button")) swapNavIcon(cell, label);
 			};
@@ -1961,6 +2196,11 @@ window.__ModuleLoader__.load({
 		 */
 		function apply(ctx) {
 			insertStyles();
+			// One page per browser profile speaks (see createAlertLeader): a
+			// sound and a toast belong to the machine, and a second tab of the
+			// same GUI must not raise them a second time.
+			const alertLeader = createAlertLeader();
+			ctx.effect(() => alertLeader.dispose, "notify-sounds: alert leader");
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "notify-sounds: dictionaries");
 			const t = ctx.locale.bind(NS);
 			// The platform's own resolver for package text, which may be a plain
@@ -1995,7 +2235,8 @@ window.__ModuleLoader__.load({
 			const cooldown = new Map();
 
 			/**
-			 * The session list rows, if this runtime exposes them.
+			 * One snapshot of the session list rows, or `undefined` when this
+			 * runtime exposes none.
 			 *
 			 * The status facts carry no classification at all — an entry is
 			 * only `{ running, pendingInteraction, completionUnread }` — so
@@ -2003,24 +2244,20 @@ window.__ModuleLoader__.load({
 			 * session list, whose rows carry the same `origin`/`parentId` the
 			 * sidebar uses to keep sub-agents out of the ordinary list.
 			 *
+			 * Callers read ONCE per pass and hand the result down: the previous
+			 * shape called this per session inside the loops below, so a status
+			 * update covering ten sessions took ten snapshots, and the pass
+			 * scope was implied by "the same millisecond" rather than stated.
+			 *
 			 * @returns the `byId` row map, or undefined when unavailable.
 			 */
-			// Cache one snapshot per synchronous block: `isNotifiable` is
-			// called per session in read()/trackPending loops, and each call
-			// would otherwise take a fresh snapshot (O8).
-			let cachedRows;
-			let cachedRowsAt = 0;
-			const sessionRows = () => {
-				const now = Date.now();
-				if (cachedRows !== undefined && now === cachedRowsAt) return cachedRows;
+			const readSessionRows = () => {
 				try {
-					cachedRows = ctx.sessions?.list?.getSnapshot?.()?.byId
+					return ctx.sessions?.list?.getSnapshot?.()?.byId
 						?? ctx.uiSession?.sessions?.list?.getSnapshot?.()?.byId;
 				} catch {
-					cachedRows = undefined;
+					return undefined;
 				}
-				cachedRowsAt = now;
-				return cachedRows;
 			};
 
 			/**
@@ -2028,10 +2265,11 @@ window.__ModuleLoader__.load({
 			 * sub-agent, a teammate — rather than one of the user's own.
 			 *
 			 * @param sessionId - the session to classify.
+			 * @param rows - the pass's session rows, when the runtime has them.
 			 * @returns whether it is a spawned child session.
 			 */
-			const isSubagentSession = (sessionId) => {
-				const row = sessionRows()?.[sessionId];
+			const isSubagentSession = (sessionId, rows) => {
+				const row = rows?.[sessionId];
 				// Deliberately ONLY `origin`, the same test the sidebar and the
 				// sub-agent UI use. `parentId` alone is not enough: a forked
 				// conversation carries one too and is still the user's own.
@@ -2048,12 +2286,13 @@ window.__ModuleLoader__.load({
 			 * not something they want a chime for.
 			 *
 			 * @param sessionId - the session to test.
+			 * @param rows - the pass's session rows, when the runtime has them.
 			 * @returns whether its events should alert.
 			 */
-			const isNotifiable = (sessionId) => {
+			const isNotifiable = (sessionId, rows) => {
 				const value = form.getSnapshot().value;
 				if (value?.subagentAlerts === true) return true;
-				return !isSubagentSession(sessionId);
+				return !isSubagentSession(sessionId, rows);
 			};
 
 			/**
@@ -2075,6 +2314,10 @@ window.__ModuleLoader__.load({
 			 *   reminder is not recorded as sent.
 			 */
 			const notify = (kind, interaction, sessionId, options = {}) => {
+				// The elected page is the only one that makes a noise or raises
+				// a notification; every page still keeps its own title mark,
+				// because a title belongs to its own window.
+				if (!alertLeader.isLeader()) return false;
 				const value = form.getSnapshot().value;
 				if (value?.enabled === false) return false;
 				if (value?.quietHours === true && inQuietHours(new Date(), value?.quietStart, value?.quietEnd)) return false;
@@ -2096,8 +2339,17 @@ window.__ModuleLoader__.load({
 					// Evict the oldest entry rather than clearing the whole
 					// table: one session hitting the cap must not silence
 					// every other session's cooldown.
-					if (cooldown.size >= 96) cooldown.delete(cooldown.keys().next().value);
-					cooldown.set(`${kind}:${sessionId}`, now);
+					//
+					// LRU, not FIFO: `Map.set` on a key that is already there
+					// updates the value and KEEPS the original position, so
+					// plain eviction would throw away whichever entry is
+					// touched most often — precisely the session whose
+					// two-second dedupe is doing work. Deleting first moves it
+					// to the back on re-insertion.
+					const key = `${kind}:${sessionId}`;
+					if (cooldown.has(key)) cooldown.delete(key);
+					else if (cooldown.size >= 96) cooldown.delete(cooldown.keys().next().value);
+					cooldown.set(key, now);
 				}
 				const fallback = kind === "completion" ? "ding" : kind === "question" ? "chime" : "bell";
 				let id = typeof value?.[kind + "Sound"] === "string" ? value[kind + "Sound"] : fallback;
@@ -2156,12 +2408,96 @@ window.__ModuleLoader__.load({
 					return value?.quietHours === true && inQuietHours(new Date(), value?.quietStart, value?.quietEnd);
 				};
 				/** Whether any session is currently running. */
-				const anyRunning = () => {
+				const anyRunning = (rows) => {
 					for (const [sessionId, status] of source.getSnapshot()) {
-						if (status.running === true && isNotifiable(sessionId)) return true;
+						if (status.running === true && isNotifiable(sessionId, rows)) return true;
 					}
 					return false;
 				};
+				/**
+				 * The goal projection's phase for one session, when this runtime
+				 * carries the goal packages.
+				 *
+				 * DSH's goal mode drives several rounds inside one session, and
+				 * every round ends with a running→idle edge — so an unguarded
+				 * completion chime fires once per round. The phase is the host's
+				 * own vocabulary: `active` keeps going on its own, `complete`
+				 * finished, and `paused`/`blocked` wait for the user.
+				 *
+				 * Every step is optional: a runtime without the goal projection
+				 * simply answers `undefined`, which reads as "no goal".
+				 */
+				const goalPhaseOf = (sessionId) => {
+					try {
+						const sessions = ctx.sessions ?? ctx.uiSession?.sessions;
+						const store = sessions?.get?.(sessionId)?.projections;
+						const snapshot = store?.get?.("goal") ?? store?.faceOf?.("goal")?.getSnapshot?.();
+						const phase = snapshot?.goal?.phase;
+						return typeof phase === "string" ? phase : undefined;
+					} catch {
+						return undefined;
+					}
+				};
+				/** Whether the completion edge for a session is worth an alert now. */
+				const completionIsFinal = (sessionId, value) => {
+					if (value?.goalFinalOnly !== true) return true;
+					// A session with no goal, or with one that will not continue on
+					// its own (finished, paused, blocked), ends this edge for the
+					// user; one that is still `active` drives another round.
+					return goalPhaseOf(sessionId) !== "active";
+				};
+				/** Longest a goal may stay `active` before its watcher gives up. */
+				const GOAL_SETTLE_TIMEOUT_MS = 30 * 60 * 1000;
+				/** Settings whose session already has a watcher waiting for its goal. */
+				const goalWatchers = new Map();
+				/**
+				 * Serve the single completion chime a goal earns when it ends.
+				 *
+				 * The edge that armed this watcher was an intermediate round (the
+				 * phase was still `active`). The next round starts at quiescence,
+				 * so the projection is re-read on every change: running again means
+				 * the edge was intermediate and stays silent, while any non-active
+				 * phase means the goal ended and earns the one chime.
+				 */
+				const watchGoalCompletion = (sessionId) => {
+					if (goalWatchers.has(sessionId)) return;
+					let settled = false;
+					let subscriptionOff = () => {};
+					let timer;
+					const settle = (chime) => {
+						if (settled) return;
+						settled = true;
+						goalWatchers.delete(sessionId);
+						try {
+							subscriptionOff();
+						} catch {}
+						clearTimeout(timer);
+						if (!chime) return;
+						if (!pageIsWatched() && !quietNow()) unreadCompletion = true;
+						notify("completion", undefined, sessionId);
+						refreshFlash();
+					};
+					try {
+						const sessions = ctx.sessions ?? ctx.uiSession?.sessions;
+						const face = sessions?.get?.(sessionId)?.projections?.faceOf?.("goal");
+						if (typeof face?.subscribe === "function") {
+							const subscription = face.subscribe(() => {
+								if (source.getSnapshot().get(sessionId)?.running === true) {
+									settle(false);
+									return;
+								}
+								const phase = goalPhaseOf(sessionId);
+								if (phase === undefined || phase !== "active") settle(true);
+							});
+							if (typeof subscription === "function") subscriptionOff = subscription;
+						}
+					} catch {}
+					// A goal that never resolves must not pin this entry forever;
+					// dropping it silently beats a stray chime minutes later.
+					timer = setTimeout(() => settle(false), GOAL_SETTLE_TIMEOUT_MS);
+					timer?.unref?.();
+					goalWatchers.set(sessionId, () => settle(false));
+				};
 				/**
 				 * Which alert the title should carry, if any.
 				 *
@@ -2180,7 +2516,7 @@ window.__ModuleLoader__.load({
 						// the quiet window ends.
 						if (record.quiet !== true) return "pending";
 					}
-					if (anyRunning()) return undefined;
+					if (anyRunning(readSessionRows())) return undefined;
 					return unreadCompletion ? "done" : undefined;
 				};
 				/** Refresh the title alert from the current facts. */
@@ -2190,12 +2526,12 @@ window.__ModuleLoader__.load({
 					applyTitleFlash(wantedTitleState(), titleAlerts(t));
 				};
 				/** Rebuild the tracker from one snapshot, then refresh the flash. */
-				const trackPending = (snapshot) => {
+				const trackPending = (snapshot, rows) => {
 					const next = new Map();
 					for (const [sessionId, status] of snapshot) {
 						// A filtered session is invisible to the whole package:
 						// it gets no reminder and no title mark either.
-						if (!isNotifiable(sessionId)) continue;
+						if (!isNotifiable(sessionId, rows)) continue;
 						const interaction = status.pendingInteraction;
 						if (interaction === undefined) continue;
 						const record = pending.get(sessionId);
@@ -2222,11 +2558,14 @@ window.__ModuleLoader__.load({
 				};
 				const read = () => {
 					const snapshot = source.getSnapshot();
+					// One row snapshot for this whole pass, handed to every
+					// check below instead of being taken per session.
+					const rows = readSessionRows();
 					if (previous !== undefined) {
 						for (const [sessionId, status] of snapshot) {
 							// Sub-agent sessions stay out of it unless asked for:
 							// the user wants the main conversation's alerts.
-							if (!isNotifiable(sessionId)) continue;
+							if (!isNotifiable(sessionId, rows)) continue;
 							const before = previous.get(sessionId);
 							const beforePending = before === undefined ? undefined : before.pendingInteraction;
 							if (status.pendingInteraction !== undefined && status.pendingInteraction !== beforePending) {
@@ -2241,18 +2580,25 @@ window.__ModuleLoader__.load({
 								notify(status.pendingInteraction.kind === "question" ? "question" : "decision", status.pendingInteraction, sessionId);
 							}
 							if (before !== undefined && before.running === true && status.running === false) {
-								// A finish that happens while the user is away is
-								// news; one they watch happen is not — and one
-								// that happens during quiet hours is forgotten
-								// rather than kept for later, so nothing about it
-								// shows up when the quiet window ends.
-								if (!pageIsWatched() && !quietNow()) unreadCompletion = true;
-								notify("completion", undefined, sessionId);
+								const value = form.getSnapshot().value;
+								if (!completionIsFinal(sessionId, value)) {
+									// An intermediate goal round: stay silent and let
+									// the goal's own end deliver the single chime.
+									watchGoalCompletion(sessionId);
+								} else {
+									// A finish that happens while the user is away is
+									// news; one they watch happen is not — and one
+									// that happens during quiet hours is forgotten
+									// rather than kept for later, so nothing about it
+									// shows up when the quiet window ends.
+									if (!pageIsWatched() && !quietNow()) unreadCompletion = true;
+									notify("completion", undefined, sessionId);
+								}
 							}
 						}
 					}
 					previous = snapshot;
-					trackPending(snapshot);
+					trackPending(snapshot, rows);
 				};
 				// Returning to the page clears the alert even while the
 				// decision stays pending — and marks every pending decision
@@ -2332,6 +2678,7 @@ window.__ModuleLoader__.load({
 					unsubscribeForm();
 					unsubscribeLocale();
 					clearInterval(renotifyTimer);
+					for (const stop of [...goalWatchers.values()]) stop();
 					if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibility);
 					applyTitleFlash(undefined, titleAlerts(t));
 				};
@@ -2372,9 +2719,17 @@ window.__ModuleLoader__.load({
 				let timer;
 				const tick = () => {
 					try {
-						if (form.getSnapshot().value?.updateAutoCheck === false) return;
-						fetch(UPDATE_CHECK_PATH, { method: "GET" }).catch(() => {});
+						if (form.getSnapshot().value?.updateAutoCheck !== false) {
+							fetch(UPDATE_CHECK_PATH, { method: "GET" }).catch(() => {});
+						}
 					} catch {}
+					// Rescheduled unconditionally, and that is the fix rather
+					// than a detail: returning early here — which is what the
+					// chain used to do when the preference was off — ended the
+					// self-scheduling for good. Turning the switch off once, or
+					// simply loading the page with it off, meant no check ever
+					// ran again until a full reload, while the row went on
+					// promising "at most one check a day".
 					timer = setTimeout(tick, 24 * 60 * 60 * 1000);
 					timer.unref?.();
 				};
@@ -2424,7 +2779,21 @@ window.__ModuleLoader__.load({
 		exports.SOUND_IDS = SOUND_IDS;
 		exports.FOCUS_PATH = FOCUS_PATH;
 		exports.UPDATE_CHECK_PATH = UPDATE_CHECK_PATH;
-		exports.UPDATE_APPLY_PATH = UPDATE_APPLY_PATH;
+		// Which update stages a retry can fix and which need a fresh install:
+		// the Host names a stage in every failure it reports, so this map is the
+		// one place the advice comes from, and the tests cross-check it against
+		// the stage words the dictionaries carry.
+		exports.UPDATE_STAGES = UPDATE_STAGES;
+		// The two composed messages, so the tests can assert the sentences a
+		// user actually reads rather than only the dictionary keys behind them.
+		exports.updateAppliedText = updateAppliedText;
+		exports.updateFailureText = updateFailureText;
+		// The alert election, so the tests can drive two pages against a stubbed
+		// storage and channel instead of hoping two real tabs cooperate.
+		exports.createAlertLeader = createAlertLeader;
+		// The peak scan, so a test can build the one buffer that tells a full
+		// scan apart from a strided one.
+		exports.normalizedGain = normalizedGain;
 		exports.timeOfDayToMinutes = timeOfDayToMinutes;
 		return module.exports;
 	},