dsh-plugin-notify-sounds 1.6.5 → 1.6.9

package/README.md

@@ -105,6 +105,7 @@ The command line writes `dsh.profile.bundles` and installs the dependency for yo
 - **The window is found by its title** — deliberately without inspecting other processes (that trips security software). If DSH ever changes its title format, click-to-return silently stops working; sounds and notifications are unaffected.
 - **The nav glyph** depends on the settings panel's DOM structure and silently falls back to the official gear after a DSH redesign — cosmetic only.
 - **Notification permission** is granted on the Desktop; under restrictive policies the row shows how to allow it manually, everything else keeps working.
+- **macOS system notifications**: the desktop shell grants every permission request, so settings always say "granted" — whether a banner actually appears is up to macOS (System Settings → Notifications → DeepSeek Harness), and unsigned development builds may fail silently. "It says granted but nothing shows" is usually not this plugin.
 - **Upgrading from v1.0.0**: since v1.1.0 approvals and questions are separate tracks, so questions default to "Chime" instead of "Bell" — change it back in settings if you prefer.
 
 ## 🧩 Design notes
@@ -123,6 +124,10 @@ For anyone hacking on the code (exact details live in the source comments):
 
 ## 📜 Changelog
 
+- **v1.6.9** (2026-10-12) Fixes a README filename compatibility issue in v1.6.8: reverted to `README.md` (English) + `README.zh.md` (Chinese) so the update whitelist in every prior version can recognise them. A new filename would be refused by old users' updates — the whitelist is one-directional because the update runs old code.
+- **v1.6.8** (2026-10-12) Review fixes and optimizations: the auto-check first-frame timing gap is closed (`undefined` is no longer treated as permission to reach out); an orphaned JSDoc is removed; the teardown assertion now actually verifies listener removal; `normalizedGain` samples every 8th frame (2.6M → 330K iterations for a 30-second upload); the master gain disconnects after playback ends (no more audio-node leak); `swapNavIcon` is wrapped in try/catch and preserves the original node for restore on dispose (React re-renders can no longer crash it); the cooldown table evicts the oldest entry instead of clearing all; and `sessionRows` caches one snapshot per synchronous block.
+- **v1.6.7** (2026-10-12) Three fixes from the review: a macOS browser tab is no longer mislabeled "not supported" for the title alert (`isDesktopShell` is the right criterion, not `isMac` alone); the first-frame timing gap in the auto-check guard is closed (`undefined` is no longer treated as permission); and three comments that no longer matched the code are corrected. Plus BUG-1 regression tests covering the suspended AudioContext path.
+- **v1.6.6** (2026-10-12) Nine fixes from an audit: sounds are no longer lost under the browser autoplay policy, and no longer "banked" to fire together at some later click (first-gesture unlock, and nothing is scheduled while the context cannot play); the macOS window raise now activates by bundle id with the deep link as fallback and logs its failures; update rollback is complete — files the update added are removed again, no temp file survives, and the backup is cleaned up once the swap succeeds; checks and updates are single-flight, so two pages clicking at once neither collide nor double-request; turning automatic checks off now really keeps the plugin quiet; a mobile browser that refuses to build a notification is reported as unsupported instead of showing a switch that can never work; and the nav glyph is back on the artwork's own 17×17 coordinate system. Platform notes are now labelled where they apply: the title alert says macOS does not support it, and repeat reminders note that background browser tabs throttle timers.
 - **v1.6.5** (2026-10-11) Quiet hours now mean forgotten, not queued: decisions and finishes that arrive during the quiet range get no reminder and no title mark, and nothing that was missed overnight is delivered when the window ends; reminders that come due inside it are dropped rather than deferred. The update outcome now appears at the top of the section (visible the moment the page reloads, no scrolling), and the update row's copy is simpler.
 - **v1.6.4** (2026-10-11) No more scrolling to find the news: an update swaps the plugin's own client file and the page reloads at the top, so the row now scrolls itself back into view when the outcome appears.
 - **v1.6.3** (2026-10-11) The update-success message no longer flashes and vanishes: the Host remembers the install and repeats it with every check, so "Updated, restart DSH to load it" survives the page reload the update itself triggers (it swaps the client half's own file) and stays until the restart. The cached check is invalidated after an install too, so the row can no longer claim a newer version than the one it just wrote.

package/README.zh.md

@@ -105,6 +105,7 @@ dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds
 - **唤窗按窗口标题定位主窗口**：刻意不读取其他进程信息（那会触发杀软主动防御）。若将来 DSH 改变标题格式，唤窗会静默失效——提示音与通知本身不受影响。
 - **导航小图标**：依赖设置面板的 DOM 结构，若DSH 改版后自动回落为官方齿轮，仅影响外观。
 - **通知权限**：桌面端放行；受限环境（某些浏览器策略）下被拒时，行内会引导手动允许，其余功能不受影响。
+- **macOS 的系统通知**：桌面外壳对权限请求一律放行，所以设置里恒显示「已授权」；**实际是否弹横幅由 macOS 决定**（系统设置 → 通知 → DeepSeek Harness），未签名的开发版可能静默失败——「显示已授权却没通知」多半不是插件的问题。
 
 ## 🧩 设计与实现
 
@@ -122,6 +123,10 @@ dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds
 
 ## 📜 更新记录
 
+- **v1.6.9**（2026-10-12）修正 v1.6.8 的 README 文件名兼容性：改回 `README.md`（英文默认）+ `README.zh.md`（中文），确保旧版本更新白名单能识别。新文件名会让旧用户的更新被拒——白名单是单向兼容的，更新时跑的是旧代码。
+- **v1.6.8**（2026-10-12）修复复核细节 + 优化：`autoCheck` 首帧时序补上（`undefined` 不再被当成允许联网）；删孤立 JSDoc；teardown 断言改为真正验证监听器移除；`normalizedGain` 抽样（每 8 帧，260 万→33 万次）；`master` gain 播完自动断连（不再泄漏音频节点）；`swapNavIcon` try/catch + 保留原节点、dispose 时还原（React 重排不再炸）；冷却表 LRU 淘汰（不再全清）；`sessionRows` 同步块级快照缓存。
+- **v1.6.7**（2026-10-12）修复复核发现的 3 处细节：macOS 浏览器标签页不再被误标「暂不支持标题提醒」（`isDesktopShell` 才是判据）；「自动检查=关」的首帧时序缺口补上（`undefined` 不再被当成允许）；三处注释与实现不符已更正。补 BUG-1 回归测试（挂起 AudioContext 三断言）。
+- **v1.6.6**（2026-10-12）按审计报告修复 9 处：浏览器自动播放策略下不再丢失提示音、也不再「攒到某次点击时一起补放」（首次手势解锁 + 只在真正可播时排程）；macOS 唤窗改为按 bundle id 激活、深链兜底，失败会写进日志；更新回滚补全——新增文件一并撤回、不留临时文件、成功后清理备份；检查与更新加单飞，两个页面同时点不再互踩或重复请求；「自动检查更新=关」真正生效；移动端通知构造失败会如实显示不支持；导航图标回到官方 17×17 坐标系。跨平台标注：macOS 的「窗口标题提醒」标为暂不支持，浏览器下的重复提醒标注后台可能节流。
 - **v1.6.5**（2026-10-11）免打扰改为**真的忘记**：静音时段里发生的决策与完成不再记账——不响、不通知、不打标题标记，时段结束后也不会把夜里漏掉的一起发回来；本该在时段内发出的重复提醒直接作废而非顺延。更新提示移到分区顶部（页面回顶也能第一眼看到，不再需要滚动）；更新行文案简化。
 - **v1.6.4**（2026-10-11）更新完成后不用再手动往下翻：更新会替换插件自身的客户端文件、触发页面重载并回到顶部，现在「更新完成」提示出现时，「更新」行会**平滑滚动回视野**。
 - **v1.6.3**（2026-10-11）更新成功的提示不再一闪而过：更新结果改由**宿主**记住、随每次检查下发——即便更新替换掉了客户端自身文件、页面热重载丢掉本地状态，「更新完成：vX → vY，重启 DSH 后生效」也会一直显示到你重启；同时更新后**作废检查缓存**，不会再出现「明明刚升完却仍显示有新版」。

package/lib/client.js

@@ -70,6 +70,33 @@ window.__ModuleLoader__.load({
 			".dsh-notify-sounds-quietDash{color:var(--dsw-alias-label-tertiary)}",
 			".dsh-notify-sounds-hint{color:var(--dsw-alias-label-tertiary);margin-top:4px;font-size:12px;line-height:18px}",
 		].join("");
+
+		/**
+		 * Whether this page is running inside the Desktop shell rather than a
+		 * real browser.
+		 *
+		 * Derived from what the page can see: the shell serves the same bundle
+		 * over its own `dsh-app:` protocol and ships an Electron user agent,
+		 * while a browser serves it over http(s) with no Electron token. Either
+		 * signal alone would do; using both keeps one of them changing its mind
+		 * from flipping the answer.
+		 */
+		const isDesktopShell = () => {
+			if (typeof location !== "undefined" && location.protocol === "dsh-app:") return true;
+			return typeof navigator !== "undefined" && /Electron/i.test(navigator.userAgent ?? "");
+		};
+
+		/**
+		 * Whether the page is on macOS.
+		 *
+		 * Note this is a pure OS check: it matches macOS browsers too. The
+		 * places that need "macOS DESKTOP SHELL" combine this with
+		 * `isDesktopShell()`, because the window chrome that breaks the title
+		 * alert (`titleBarStyle: "hiddenInset"`) is the shell's own choice —
+		 * a macOS browser tab shows the document title like any other.
+		 */
+		const isMac = () => typeof navigator !== "undefined" && /Mac/i.test(`${navigator.platform ?? ""} ${navigator.userAgent ?? ""}`);
+
 		/** Stylesheet class names, one projection the components read. */
 		const css = {
 			section: "dsh-notify-sounds-section",
@@ -151,10 +178,12 @@ window.__ModuleLoader__.load({
 			"systemNotify.unsupported": "当前环境不支持系统通知",
 			"titleFlash.title": "窗口标题提醒",
 			"titleFlash.description": "页面处于后台时，在窗口标题前加文字标记（待处理 / 已完成），便于在任务栏察觉；回到页面后自动清除",
+			"titleFlash.macUnsupported": "macOS 暂不支持：标题栏隐藏、Dock 也没有窗口标题，标记无处显示（只在「窗口」菜单 / Mission Control 里可见）",
 			"titleFlash.pending": "待处理",
 			"titleFlash.done": "已完成",
 			"renotify.title": "未处理决策重复提醒",
 			"renotify.description": "有决策一直未处理时，每隔设定时间重新提醒；只要你已经看过它一眼（它出现时你正在窗口，或之后回到过窗口），就不再重复提醒，即使再切走也一样",
+			"renotify.browserHint": "浏览器的后台标签页会节流计时器，重复间隔可能被拉长（1 分钟档尤其明显）",
 			"renotify.interval": "重复间隔",
 			"renotify.minutes": "{n} 分钟",
 			"quiet.title": "静音时段",
@@ -228,10 +257,12 @@ 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.pending": "Waiting for you",
 			"titleFlash.done": "Finished",
 			"renotify.title": "Repeat unanswered decisions",
 			"renotify.description": "Re-ping decisions that stay unanswered at a fixed interval; once you have seen one — it appeared while you were at the window, or you came back to it — it never repeats, even if you leave again",
+			"renotify.browserHint": "Background browser tabs throttle timers, so the interval can stretch (most visible at the 1-minute setting)",
 			"renotify.interval": "Interval",
 			"renotify.minutes": "{n} min",
 			"quiet.title": "Quiet hours",
@@ -416,9 +447,15 @@ window.__ModuleLoader__.load({
 		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++) {
+					for (let i = 0; i < data.length; i += stride) {
 						const magnitude = Math.abs(data[i]);
 						if (magnitude > peak) peak = magnitude;
 					}
@@ -456,12 +493,38 @@ window.__ModuleLoader__.load({
 		}
 
 		/**
-		 * Play one preset at a loudness in percent.
+		 * Run `play` on an AudioContext that is actually running.
 		 *
-		 * The context is resumed when the browser suspended it; a page that has
-		 * not yet seen a user gesture stays silent (the browser's autoplay
-		 * policy, not an error). Peaks stay far below clipping even with every
-		 * preset voice summed.
+		 * A suspended context has a FROZEN `currentTime`: scheduling sources on
+		 * it parks them on the timeline and they all fire together whenever the
+		 * context later resumes — the opposite of an alert. So nothing is ever
+		 * scheduled while suspended. Where resuming needs a user gesture (every
+		 * browser; the Electron shell needs none) this attempt is simply
+		 * dropped, and the unlock effect has the context running for the next
+		 * one rather than banking a stale sound for later.
+		 *
+		 * @param engine - the page's AudioContext.
+		 * @param play - schedules the sound.
+		 */
+		function whenRunning(engine, play) {
+			if (engine.state === "running") {
+				play();
+				return;
+			}
+			Promise.resolve(engine.resume())
+				.then(() => {
+					if (engine.state === "running") play();
+				})
+				.catch(() => {});
+		}
+
+		/**
+		 * Play one preset (or the uploaded sound) at a loudness in percent.
+		 *
+		 * Nothing is scheduled while the AudioContext cannot play — see
+		 * `whenRunning`, which defers to the first real user gesture on
+		 * browsers. Peaks stay far below clipping even with every preset voice
+		 * summed.
 		 *
 		 * @param id - preset id; `none`, unknown ids, and `custom` without an
 		 *   upload are silent no-ops (the caller falls back first).
@@ -472,43 +535,51 @@ window.__ModuleLoader__.load({
 		 */
 		function playSound(id, volumePercent, customBase64) {
 			if (id === "none" || id === undefined) return;
+			const engine = audioEngine();
+			if (engine === undefined) return;
 			if (id === "custom") {
-				const engine = audioEngine();
-				if (engine === undefined) return;
-				if (engine.state === "suspended") engine.resume().catch(() => {});
-				playCustomSound(engine, customBase64, volumePercent);
+				whenRunning(engine, () => playCustomSound(engine, customBase64, volumePercent));
 				return;
 			}
 			const preset = SOUND_PRESETS[id];
 			if (preset === undefined) return;
-			const engine = audioEngine();
-			if (engine === undefined) return;
-			if (engine.state === "suspended") engine.resume().catch(() => {});
 			const percent = Number.isFinite(volumePercent) ? volumePercent : DEFAULT_VOLUME;
 			const loudness = Math.max(0, Math.min(100, percent)) / 100;
 			if (loudness === 0) return;
-			const master = engine.createGain();
-			master.gain.value = loudness * 0.6;
-			master.connect(engine.destination);
-			const t0 = engine.currentTime + 0.02;
-			for (const note of preset.notes) {
-				const osc = engine.createOscillator();
-				const gain = engine.createGain();
-				osc.type = note.type ?? "sine";
-				const start = t0 + note.at;
-				osc.frequency.setValueAtTime(note.freq, start);
-				if (note.glideTo !== undefined) {
-					osc.frequency.exponentialRampToValueAtTime(note.glideTo, start + note.dur * 0.85);
+			whenRunning(engine, () => {
+				const master = engine.createGain();
+				master.gain.value = loudness * 0.6;
+				master.connect(engine.destination);
+				const t0 = engine.currentTime + 0.02;
+				let tail = 0;
+				for (const note of preset.notes) {
+					const osc = engine.createOscillator();
+					const gain = engine.createGain();
+					osc.type = note.type ?? "sine";
+					const start = t0 + note.at;
+					osc.frequency.setValueAtTime(note.freq, start);
+					if (note.glideTo !== undefined) {
+						osc.frequency.exponentialRampToValueAtTime(note.glideTo, start + note.dur * 0.85);
+					}
+					const peak = Math.max(0.0002, note.gain * 0.25);
+					gain.gain.setValueAtTime(0.0001, start);
+					gain.gain.exponentialRampToValueAtTime(peak, start + 0.012);
+					gain.gain.exponentialRampToValueAtTime(0.0001, start + note.dur);
+					osc.connect(gain);
+					gain.connect(master);
+					osc.start(start);
+					osc.stop(start + note.dur + 0.05);
+					tail = Math.max(tail, note.at + note.dur);
 				}
-				const peak = Math.max(0.0002, note.gain * 0.25);
-				gain.gain.setValueAtTime(0.0001, start);
-				gain.gain.exponentialRampToValueAtTime(peak, start + 0.012);
-				gain.gain.exponentialRampToValueAtTime(0.0001, start + note.dur);
-				osc.connect(gain);
-				gain.connect(master);
-				osc.start(start);
-				osc.stop(start + note.dur + 0.05);
-			}
+				// 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(() => {
+					try {
+						master.disconnect();
+					} catch {}
+				}, Math.max(0, (t0 + tail + 0.1 - engine.currentTime) * 1000 + 50));
+			});
 		}
 
 		/**
@@ -747,13 +818,17 @@ window.__ModuleLoader__.load({
 		const UPDATE_APPLY_PATH = "/notify-sounds/update/apply";
 
 		/**
-		 * Show one OS notification; every failure mode is silent. The tag
-		 * collapses repeats per trigger kind, and `silent` keeps the OS from
-		 * layering its own sound on top of ours.
+		 * Show one OS notification; every failure mode is silent.
+		 *
+		 * `tag` is our OWN collapse key — we close the previous notification
+		 * ourselves rather than handing the tag to the platform, because a
+		 * superseded toast can swallow clicks aimed at it. `silent` keeps the
+		 * OS from layering its own sound on top of ours.
 		 *
 		 * @param title - notification title.
 		 * @param body - notification body.
-		 * @param tag - collapse tag.
+		 * @param tag - our internal key for closing the previous generation;
+		 *   deliberately NOT passed to the platform (see the comment inside).
 		 */
 		function showSystemNotification(title, body, tag) {
 			try {
@@ -806,9 +881,13 @@ window.__ModuleLoader__.load({
 				};
 			} catch (error) {
 				// `new Notification` is what can throw here, when the
-				// environment refuses to construct one. Worth one line: the
-				// Settings row reads `Notification.permission`, which still
-				// says "granted", so nothing else would explain the silence.
+				// environment refuses to construct one — nearly every mobile
+				// browser does exactly that, while still reporting a
+				// "granted" permission. So this is not just a log line: it is
+				// recorded and shown, because the Settings row otherwise reads
+				// `Notification.permission` and proudly says "granted" for a
+				// switch that can never do anything.
+				notificationConstructionFailed = true;
 				if (!warnedNotificationFailure) {
 					warnedNotificationFailure = true;
 					console.warn("notify-sounds: could not show a system notification", error);
@@ -819,6 +898,15 @@ window.__ModuleLoader__.load({
 		/** Whether the one-time notification-construction warning has been logged. */
 		let warnedNotificationFailure = false;
 
+		/**
+		 * Whether this environment refused to construct a Notification.
+		 *
+		 * Set by the first real attempt, read by the settings row: permission
+		 * being "granted" proves nothing about whether a toast can actually be
+		 * built (MDN: the constructor throws in nearly all mobile browsers).
+		 */
+		let notificationConstructionFailed = false;
+
 		/**
 		 * Human-readable summary of one pending interaction, for notification
 		 * bodies: the approval's localized reason first, then its raw reason,
@@ -876,14 +964,22 @@ window.__ModuleLoader__.load({
 		 * @param props - copy.
 		 * @returns the notice element, or null when there is nothing to say.
 		 */
-		function UpdateNotice({ t }) {
+		function UpdateNotice({ t, autoCheck }) {
 			const [applied, setApplied] = useState(undefined);
+			// Explicit `=== true`, not `!== false`: during the first frame
+			// `useConfig` may still be loading, and `undefined` must NOT be
+			// treated as "allowed" — that is the one case where a request
+			// could slip past a user who has the switch off. The dep array is
+			// `[autoCheck]` rather than `[]` so the effect picks up the real
+			// value when it arrives, instead of only ever reading the first
+			// render's prop.
 			useEffect(() => {
+				if (autoCheck !== true) return;
 				fetch(UPDATE_CHECK_PATH, { method: "GET" })
 					.then((response) => response.json())
 					.then((payload) => setApplied(payload?.applied))
 					.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")}`);
@@ -937,7 +1033,7 @@ window.__ModuleLoader__.load({
 			return h("div", { className: css.section }, [
 				h("h2", { className: css.title, key: "title" }, t("title")),
 				h("p", { className: css.intro, key: "intro" }, t("intro")),
-				h(UpdateNotice, { key: "update-notice", t }),
+				h(UpdateNotice, { key: "update-notice", t, autoCheck: value === undefined ? undefined : value.updateAutoCheck !== false }),
 				h("div", { className: css.rows, key: "rows" }, [
 					h(SwitchRow, {
 						key: "enabled",
@@ -1068,7 +1164,13 @@ window.__ModuleLoader__.load({
 						key: "titleFlash",
 						t,
 						title: t("titleFlash.title"),
-						description: t("titleFlash.description"),
+						// macOS DESKTOP shell only: its title bar is hiddenInset
+						// and the Dock shows no per-window title, so the mark
+						// has nowhere to appear. A macOS BROWSER tab shows the
+						// 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"),
 						label: t("titleFlash.title"),
 						checked: value?.titleFlash === true,
 						disabled,
@@ -1122,6 +1224,7 @@ window.__ModuleLoader__.load({
 					h(UpdateRow, {
 						key: "update",
 						t,
+						autoCheck: value === undefined ? undefined : value.updateAutoCheck !== false,
 					}),
 				]),
 			]);
@@ -1433,7 +1536,11 @@ window.__ModuleLoader__.load({
 		 */
 		function SystemNotifyRow({ t, checked, disabled, failed, onChange }) {
 			const [busy, setBusy] = useState(false);
-			const supported = typeof Notification !== "undefined";
+			// `typeof Notification` alone is not enough: nearly every mobile
+			// browser exposes the API and happily reports "granted", yet the
+			// constructor throws every time. Once a real attempt has failed,
+			// this environment is treated as unsupported and the row says so.
+			const supported = typeof Notification !== "undefined" && !notificationConstructionFailed;
 			const permission = supported ? Notification.permission : "unsupported";
 			const hintKey = !supported ? "systemNotify.unsupported"
 				: permission === "denied" ? "systemNotify.denied"
@@ -1486,6 +1593,10 @@ window.__ModuleLoader__.load({
 				h("div", { key: "text" }, [
 					h("div", { className: css.rowTitle, key: "title" }, t("renotify.title")),
 					h("div", { className: css.rowDescription, key: "description" }, t("renotify.description")),
+					// Only where it is true: the Desktop shell runs this timer
+					// in a real window that is never throttled, so the caveat
+					// would only confuse its users.
+					isDesktopShell() ? null : h("div", { className: css.hint, key: "hint" }, t("renotify.browserHint")),
 					failed ? h("div", { className: css.error, role: "alert", key: "error" }, t("saveFailed")) : null,
 				]),
 				h("div", { className: css.stackControl, key: "control" }, [
@@ -1586,7 +1697,7 @@ window.__ModuleLoader__.load({
 		 * @param props - copy.
 		 * @returns the row element tree.
 		 */
-		function UpdateRow({ t }) {
+		function UpdateRow({ t, autoCheck }) {
 			const [state, setState] = useState({ phase: "idle" });
 			const check = (force) => async () => {
 				setState({ phase: "checking" });
@@ -1609,9 +1720,13 @@ window.__ModuleLoader__.load({
 				}
 			};
 			// 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.
 			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
@@ -1707,7 +1822,11 @@ window.__ModuleLoader__.load({
 			const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
 			svg.setAttribute("width", "16");
 			svg.setAttribute("height", "16");
-			svg.setAttribute("viewBox", "0 0 16 16");
+			// 17×17, matching the artwork's own coordinate system
+			// (`IconAlarmClockOutlineArtwork`); the gear it replaces is 16×16,
+			// and reusing ITS viewport here would scale the alarm paths up by
+			// 17/16 and make the glyph visibly larger than its neighbours.
+			svg.setAttribute("viewBox", "0 0 17 17");
 			svg.setAttribute("fill", "none");
 			svg.setAttribute("stroke-width", "1.3");
 			svg.setAttribute("aria-hidden", "true");
@@ -1742,7 +1861,18 @@ window.__ModuleLoader__.load({
 			const shippedClass = icon.getAttribute("class");
 			if (shippedClass !== null && shippedClass !== "") replacement.setAttribute("class", shippedClass);
 			replacement.setAttribute(NAV_ICON_MARKER, "");
-			cell.replaceChild(replacement, icon);
+			// Keep the original so the disposer can restore it. `replaceChild`
+			// detaches a node React still holds in its fiber tree; if React
+			// ever re-renders that slot it throws NotFoundError trying to
+			// remove the detached node. Restoring on dispose prevents that.
+			replacement._originalIcon = icon;
+			try {
+				cell.replaceChild(replacement, icon);
+			} catch {
+				// A React re-render raced the swap; the next observer pass
+				// will try again on the fresh node.
+				return false;
+			}
 			return true;
 		}
 
@@ -1791,6 +1921,18 @@ window.__ModuleLoader__.load({
 			return () => {
 				detachPanel();
 				bodyObserver.disconnect();
+				// Restore every swapped glyph so React never finds a detached
+				// node in its fiber tree (see swapNavIcon).
+				if (typeof document !== "undefined") {
+					for (const el of document.querySelectorAll(`[${NAV_ICON_MARKER}]`)) {
+						const original = el._originalIcon;
+						if (original !== undefined && el.parentNode !== null) {
+							try {
+								el.parentNode.replaceChild(original, el);
+							} catch {}
+						}
+					}
+				}
 			};
 		}
 		//#endregion
@@ -1863,13 +2005,22 @@ window.__ModuleLoader__.load({
 			 *
 			 * @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;
 				try {
-					return ctx.sessions?.list?.getSnapshot?.()?.byId
+					cachedRows = ctx.sessions?.list?.getSnapshot?.()?.byId
 						?? ctx.uiSession?.sessions?.list?.getSnapshot?.()?.byId;
 				} catch {
-					return undefined;
+					cachedRows = undefined;
 				}
+				cachedRowsAt = now;
+				return cachedRows;
 			};
 
 			/**
@@ -1942,7 +2093,10 @@ window.__ModuleLoader__.load({
 				// triggers are edge-fired that alert is lost rather than
 				// delayed.
 				if (!reminder) {
-					if (cooldown.size >= 96) cooldown.clear();
+					// 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);
 				}
 				const fallback = kind === "completion" ? "ding" : kind === "question" ? "chime" : "bell";
@@ -2183,6 +2337,28 @@ window.__ModuleLoader__.load({
 				};
 			}, "notify-sounds: session status watcher");
 
+			// Browsers gate Web Audio behind a user gesture: until one happens
+			// the context starts suspended and `resume()` simply stays pending,
+			// so a trigger firing in the meantime would be lost — and worse,
+			// anything scheduled on the frozen timeline would all fire at once
+			// whenever some later gesture unlocked it. So the FIRST real
+			// gesture starts the context and keeps it running, and nothing is
+			// scheduled while suspended (see `whenRunning`). The Desktop shell
+			// needs none of this — Electron starts audio without a gesture,
+			// which is exactly why the problem is invisible on the Desktop.
+			ctx.effect(() => {
+				if (typeof document === "undefined") return () => {};
+				const unlock = () => {
+					const engine = audioEngine();
+					if (engine?.state === "suspended") engine.resume().catch(() => {});
+				};
+				const events = ["pointerdown", "keydown", "touchstart"];
+				for (const type of events) document.addEventListener(type, unlock, { capture: true, passive: true });
+				return () => {
+					for (const type of events) document.removeEventListener(type, unlock, { capture: true });
+				};
+			}, "notify-sounds: audio unlock");
+
 			// Quiet update check: shortly after the page settles, then at most
 			// once a day, and never while the user has it turned off. It asks
 			// the Host's own route — one small query, nothing downloaded — and

package/lib/index.js

@@ -15,8 +15,11 @@
  *     OS window, but this process can: on Windows it calls `user32.dll`
  *     through the Desktop's own FFI binding and finds the window by title.
  *
- * `apply` also suppresses the auto-generated inventory page for this entry,
- * because the Client contributes a dedicated Settings section of its own.
+ * `apply` also asks the settings namespace to hold off any auto-generated
+ * inventory page for this entry, because the Client contributes a dedicated
+ * Settings section of its own. (Note: `autoGenerate` is not yet consumed by
+ * any shipped client — the flag is correct and future-proof, but today the
+ * effect is a no-op. Runtime README: "no shipped client does so yet".)
  *
  * @module dsh-plugin-notify-sounds
  */
@@ -42,6 +45,15 @@ export const TIME_OF_DAY = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
 /** Deep link the packaged Desktop registers (`setAsDefaultProtocolClient`); the last-resort focus path. */
 const FOCUS_DEEP_LINK = "dsh://open";
 
+/**
+ * The desktop app's bundle id, for raising it by identity on macOS.
+ *
+ * Taken from the packaged shell's own manifest (`dshDesktopAppId`), not
+ * guessed: `open -b <id>` is the only raise that needs no URL scheme to have
+ * been registered.
+ */
+const MACOS_BUNDLE_ID = "com.deepseek.dsh";
+
 /** Route the browser half posts to when a system notification is clicked. Exported so the tests can cross-check the Client half's spelling. */
 export const FOCUS_PATH = "/notify-sounds/focus";
 
@@ -330,16 +342,32 @@ function raiseDesktopWindowDeepLink() {
 /**
  * Start a short-lived launcher without blocking, reporting failures once.
  *
+ * The exit code matters as much as the spawn: `open` exits non-zero when no
+ * application handles the request (macOS: "Unable to find application for
+ * URL"), and a launch that never happened must not look exactly like one
+ * that did.
+ *
  * @param command - the executable to run.
  * @param args - its arguments.
+ * @param done - called with whether the launcher exited cleanly; optional,
+ *   so a caller can chain a fallback.
  */
-function launcher(command, args) {
+function launcher(command, args, done) {
 	try {
 		const child = spawn(command, args, { windowsHide: true, stdio: "ignore" });
-		child.on("error", (error) => warn(`could not launch ${command}: ${error?.message ?? error}`));
+		child.on("error", (error) => {
+			warn(`could not launch ${command}: ${error?.message ?? error}`);
+			done?.(false);
+		});
+		child.on("exit", (code) => {
+			const ok = code === 0;
+			if (!ok) warn(`${command} exited ${code}: ${args.join(" ")}`);
+			done?.(ok);
+		});
 		child.unref();
 	} catch (error) {
 		warn(`could not launch ${command}: ${error?.message ?? error}`);
+		done?.(false);
 	}
 }
 
@@ -414,9 +442,24 @@ function focusDesktopWindow() {
 				raiseDesktopWindowDeepLink();
 			}
 		} else if (process.platform === "darwin") {
-			log("raising via open + deep link");
-			launcher("open", [FOCUS_DEEP_LINK]);
+			// Activate the app by bundle id first: it needs no URL scheme to
+			// have been registered, which a packaged .app only gets if its
+			// Info.plist declares CFBundleURLTypes — something this project
+			// cannot verify from source. The deep link stays as the fallback,
+			// and a launch that failed is now named in the log instead of
+			// looking exactly like one that succeeded.
+			log("raising via open -b");
+			launcher("open", ["-b", MACOS_BUNDLE_ID], (ok) => {
+				if (ok) return;
+				log("bundle-id activation did not take; falling back to the deep link");
+				launcher("open", [FOCUS_DEEP_LINK]);
+			});
 		} else {
+			// No desktop shell ships for other platforms today — the shell
+			// itself refuses anything but win32/darwin, and a browser click
+			// never reaches this function. `xdg-open` is the correct opener
+			// should a Linux shell ever appear; until then this line is
+			// unreachable rather than misleading.
 			log("raising via xdg-open + deep link");
 			launcher("xdg-open", [FOCUS_DEEP_LINK]);
 		}
@@ -471,6 +514,12 @@ const UPDATE_MAX_RESPONSE_BYTES = 256 * 1024;
 /** Result of the last check, when the last real request went out, and the last successful install. */
 const updateCheck = { checkedAt: 0, requestedAt: 0, result: undefined, applied: undefined };
 
+/** The check currently in flight, if any — callers join it instead of starting a second one. */
+let checkInFlight;
+
+/** The update currently in flight, if any — one download and one swap at a time. */
+let applyInFlight;
+
 /**
  * Parse `major.minor.patch` with an optional prerelease tag.
  *
@@ -599,27 +648,40 @@ export async function checkForUpdate(options = {}) {
 	if (now - updateCheck.requestedAt < UPDATE_CHECK_SPACING_MS && updateCheck.result !== undefined) {
 		return updateCheck.result;
 	}
+	// Two callers arriving together — the settings row and the notice above
+	// it, or an automatic check landing on a user's click — must not become
+	// two requests. The spacing rule above cannot cover that: it only sees a
+	// finished result, and while the first request is still in the air there
+	// is none. So a second caller joins the first instead.
+	if (checkInFlight !== undefined) return checkInFlight;
 	updateCheck.requestedAt = now;
-	const current = readOwnVersion(options.root);
-	const answer = await fetchRegistryAnswer();
-	if (answer === undefined) {
-		const result = { ok: false, current, error: "no registry answered", applied: updateCheck.applied };
+	checkInFlight = (async () => {
+		const current = readOwnVersion(options.root);
+		const answer = await fetchRegistryAnswer();
+		if (answer === undefined) {
+			const result = { ok: false, current, error: "no registry answered", applied: updateCheck.applied };
+			updateCheck.checkedAt = now;
+			updateCheck.result = result;
+			return result;
+		}
+		const ordering = current === undefined ? NaN : compareVersions(current, answer.version);
+		const result = {
+			ok: true,
+			current,
+			latest: answer.version,
+			updateAvailable: Number.isFinite(ordering) && ordering < 0,
+			checkedAt: now,
+			applied: updateCheck.applied,
+		};
 		updateCheck.checkedAt = now;
 		updateCheck.result = result;
 		return result;
+	})();
+	try {
+		return await checkInFlight;
+	} finally {
+		checkInFlight = undefined;
 	}
-	const ordering = current === undefined ? NaN : compareVersions(current, answer.version);
-	const result = {
-		ok: true,
-		current,
-		latest: answer.version,
-		updateAvailable: Number.isFinite(ordering) && ordering < 0,
-		checkedAt: now,
-		applied: updateCheck.applied,
-	};
-	updateCheck.checkedAt = now;
-	updateCheck.result = result;
-	return result;
 }
 
 /**
@@ -822,6 +884,7 @@ async function downloadTarball(url) {
 export function installUpdate(root, files) {
 	const rootPrefix = resolve(root);
 	const backup = join(root, ".update-backup");
+	const tempName = (relative) => `${resolve(root, relative)}.update-tmp`;
 	rmSync(backup, { recursive: true, force: true });
 	const written = [];
 	try {
@@ -835,18 +898,29 @@ export function installUpdate(root, files) {
 				mkdirSync(dirname(aside), { recursive: true });
 				writeFileSync(aside, readFileSync(target));
 			}
-			const temp = `${target}.update-tmp`;
+			const temp = tempName(relative);
 			writeFileSync(temp, source);
 			renameSync(temp, target);
 			written.push(relative);
 		}
 	} catch (error) {
+		// Put everything back — including files the update ADDED, which have
+		// no backup to restore from and must simply go away again. A failed
+		// update has to leave nothing behind: no half-replaced file, no
+		// leftover temp, and no file that was not there before.
 		for (const relative of written) {
 			const aside = join(backup, relative);
-			if (existsSync(aside)) writeFileSync(resolve(root, relative), readFileSync(aside));
+			const target = resolve(root, relative);
+			if (existsSync(aside)) writeFileSync(target, readFileSync(aside));
+			else rmSync(target, { force: true });
 		}
+		for (const relative of UPDATE_FILES) rmSync(tempName(relative), { force: true });
 		throw error;
 	}
+	// The swap succeeded, so the backup has done its job. Leaving it would
+	// park the previous version's files — a hundred-odd KB including the
+	// client half — inside the profile until some later update clears it.
+	rmSync(backup, { recursive: true, force: true });
 }
 
 /**
@@ -867,6 +941,21 @@ export function installUpdate(root, files) {
  *   upToDate: true, current }`, or `{ ok: false, stage, error }`.
  */
 export async function applyUpdate(options = {}) {
+	// One download and one swap at a time. Two callers — a second tab, or a
+	// user clicking again because the first attempt looks stuck — would share
+	// the fixed temp names and the single backup directory, and the slower
+	// one's cleanup would pull the floor out from under the other.
+	if (applyInFlight !== undefined) return applyInFlight;
+	applyInFlight = runUpdate(options);
+	try {
+		return await applyInFlight;
+	} finally {
+		applyInFlight = undefined;
+	}
+}
+
+/** `applyUpdate` without the single-flight guard. */
+async function runUpdate(options = {}) {
 	const root = options.root ?? packageRoot();
 	const current = readOwnVersion(root);
 	let stage = "check";
@@ -952,9 +1041,12 @@ export const Config = z.object({
  * @param ctx - the Host plugin context.
  */
 export function apply(ctx) {
-	// The Client half registers a dedicated `settings.section` page; keep the
-	// plugin inventory from contributing an auto-generated form for the same
-	// namespace, so the preference is editable from exactly one place.
+	// The Client half registers a dedicated `settings.section` page; this asks
+	// the plugin inventory to hold off an auto-generated form for the same
+	// namespace so the preference is editable from exactly one place. Note:
+	// `autoGenerate` is not yet consumed by any shipped client (runtime README
+	// confirms), so this is a forward-compatible declaration rather than an
+	// effect that is already in force.
 	ctx.inject(["settings"], (child) => {
 		child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
 	});
@@ -982,16 +1074,23 @@ export function apply(ctx) {
 					return;
 				}
 				// Which client asked? The Desktop's renderer fetches from its
-				// own `dsh-app://app/` origin, and the shell STRIPS Origin
-				// before forwarding to this server, so a Desktop click arrives
-				// with no Origin header while a real browser always sends one.
+				// own `dsh-app://app/` origin, and the shell STRIPS Origin and
+				// Sec-Fetch-Site before forwarding to this server (the shell's
+				// `forwardWebRequest` in `lib/main.js`), so a Desktop click
+				// arrives with neither header while a real browser always sends
+				// at least one. Checking BOTH keeps this working if the shell
+				// ever stops stripping only one of them: the day it strips
+				// neither, a Desktop click would silently start looking like a
+				// browser one and clicks would stop raising the window — with no
+				// other symptom to explain it.
 				//
 				// The two need opposite things, so the choice is derived here
 				// rather than configured: a browser click needs no help, since
 				// activating the notification raises the browser window itself
 				// and raising the Desktop window instead would be the wrong
 				// window entirely.
-				const fromBrowser = req.headers?.origin !== undefined;
+				const headers = req.headers ?? {};
+				const fromBrowser = headers.origin !== undefined || headers["sec-fetch-site"] !== undefined;
 				res.statusCode = 204;
 				res.end();
 				log(`focus click (fromBrowser=${fromBrowser})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-notify-sounds",
-  "version": "1.6.5",
+  "version": "1.6.9",
   "description": "Notification sounds for DeepSeek Harness — a soft chime when the agent needs your decision or finishes a task, with a Settings section styled like DSH's own · 需要决策或任务完成时播放提示音，点击系统通知可回到窗口，设置面板可调音量与音效",
   "type": "module",
   "main": "lib/index.js",