dsh-plugin-notify-sounds 1.6.9 → 1.7.0

package/README.md

@@ -34,7 +34,7 @@ Every visual detail of the settings section comes from DSH's own design system:
 | **Only what you care about** | Sub-agents (background tasks) are completely silent by default — only your own conversation is announced |
 | **Quiet when it should be** | Quiet hours (e.g. 22:00–08:00, wrapping past midnight), notify-only-when-hidden, and a master switch |
 | **Your sound, your way** | Nine built-in sounds, custom ringtone upload, volume — each feature with its own toggle |
-| **Update checks** | Check npm for a new version and install it in one click: verified against the published digest before anything is replaced, restored on failure; restart DSH to load it |
+| **Update checks** | Check npm for a new version and install it in one click: verified against the published digest before anything is replaced, restored on failure with advice you can act on; restart DSH to load it |
 
 ## 💡 Why
 
@@ -84,7 +84,13 @@ DSH does not update plugins on its own, but this plugin **updates itself**: Sett
 dsh plugin --profile <your profile> add github:BillCx330/dsh-plugin-notify-sounds
 ```
 
-**Release archive** — download the `.tgz` from [Releases](https://github.com/BillCx330/dsh-plugin-notify-sounds/releases) and hand it to `dsh plugin add`.
+**Release archive** — download the `.tgz` from [Releases](https://github.com/BillCx330/dsh-plugin-notify-sounds/releases) and install it by its **path on disk**:
+
+```sh
+dsh plugin --profile <your profile> add ./dsh-plugin-notify-sounds-1.7.0.tgz
+```
+
+(`dsh plugin add` hands its argument straight to the package manager, so it takes a local file path — a download URL will not work.)
 
 **Local directory** — for development or trying unreleased changes:
 
@@ -99,7 +105,8 @@ The command line writes `dsh.profile.bundles` and installs the dependency for yo
 ## ⚠️ Known limitations
 
 - **Hand-edited config**: preferences live in the profile's `cordis.patch.yml`; values must match the schema (volume 0–100, a preset id, `HH:MM` times) or the plugin declines to load — just fix the value. The settings UI only ever writes valid values.
-- **One-click update only swaps files**: it replaces the seven files this package ships and **never touches the profile's configuration**. Downloaded code is never executed — the new code loads on a **DSH restart**. Let the row report a result before closing the window (an interrupted update restores itself, but there is no reason to gamble); if a future release adds a dependency, that needs installing separately (this one has none).
+- **One-click update only writes files**: it writes the files the new release carries — added ones included — into this package's own directory and **never touches the profile's configuration**. It never *deletes*: a file a later release drops stays behind on machines that updated into it (harmless, but only a reinstall removes it). Downloaded code is never executed — the new code loads on a **DSH restart**. Let the row report a result before closing the window (a failed update restores itself, and says what to do next); if a future release adds a dependency, that needs installing separately (this one has none).
+- **Versions up to 1.6.9 cannot update into a release that adds a file**: those builds carry a fixed list of seven filenames and refuse an archive containing anything else — **without damaging the installed version**, which keeps working as it did. Reinstalling once from npm or the repository's Releases fixes it permanently: 1.7.0 removed that limit, and from then on any release may add files.
 - **Multiple windows** fire independently: the same event may chime once per window; turn on notify-only-when-hidden to avoid it.
 - **Click-to-return** is fully implemented and tested on Windows; macOS / Linux fall back to the system deep link and are unverified.
 - **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.
@@ -124,6 +131,7 @@ For anyone hacking on the code (exact details live in the source comments):
 
 ## 📜 Changelog
 
+- **v1.7.0** (2026-10-16) **The update mechanism turns a corner**: one-click update is no longer limited by a fixed list of seven filenames. It now accepts any regular file inside the package directory, governed by rules instead of an inventory — path traversal, absolute paths, symlinks, non-file entries, reserved names (its own backup/temp names and its record file, `.git`, `node_modules`, `.npmrc`), paths containing `:`, names colliding only by case, and a file that differs from the entry point `package.json` declares only by case are all still refused, with the file count and the decompressed size capped (enforced while inflating). **1.7.0 and later update cleanly into a release that adds or drops any number of files**: a file a later release drops is now actually deleted, based on the `.update-manifest.json` record this updater leaves behind — **only files an update installed are ever deleted**, anything you put in that directory yourself is left alone, and installations older than the first record are never guessed at. **1.6.9 and earlier will fail** (safely — nothing is written, the installed version keeps working) if a newer release adds a file, and the README says to reinstall once. Fixed: turning auto-check off ended the daily check chain for good, even after turning it back on; clicking a notification did nothing when the window title changed between the two Win32 reads; prerelease versions compared as strings (`rc.10` looked older than `rc.9`); **two tabs — or two windows — of the same GUI each rang the sound, raised their own system notification and ran their own repeat reminder** (one page is now elected to speak, via BroadcastChannel plus a shared claim, and the others stay silent until it disappears; per-window title marks are unaffected); and custom-sound normalization now visits **every sample** (taking every 8th frame aliased against content near fs/8 and systematically underestimated the peak). A failed update now gives **stage-appropriate advice** — retry for network failures, and the repository plus the uninstall/reinstall steps when the payload itself could not be applied, naming both versions — `package.json` is written **last** (a crash mid-swap leaves the old version number over the new code, so the next check still offers the update instead of declaring success), and the archive's manifest is verified to be this package at the version the registry named. The custom-sound row moved to sit **directly under the three trigger sounds** it is used by, and the smaller fixes on top: the cooldown table is a real LRU rather than FIFO (the session that fired most often was evicted first), one session-list snapshot per pass instead of per session, the macOS Desktop's window-title switch is now disabled rather than merely re-described, the full-width punctuation that leaked into the English update message is gone, and the README's release-archive instructions now give a command that actually works.
 - **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.

package/README.zh.md

@@ -34,7 +34,7 @@ dsh-plugin-notify-sounds
 | **只提醒你关心的** | 子智能体（后台任务）默认完全静默，只提醒主对话，可开关 |
 | **该安静时安静** | 静音时段（如 22:00–08:00，可跨午夜）、仅页面不可见时提示、总开关一键全静音 |
 | **声音随你** | 九种内置音效、自定义铃声上传、音量调节，每项独立开关 |
-| **检测更新** | 设置里检查 npm 新版本并一键更新：下载后校验完整性才替换，失败自动还原；更新后重启 DSH 生效 |
+| **检测更新** | 设置里检查 npm 新版本并一键更新：下载后校验完整性才替换，失败自动还原并给出可照做的处理建议；更新后重启 DSH 生效 |
 
 ## 💡 为什么需要它
 
@@ -84,7 +84,13 @@ DSH 不会自动更新插件，但本插件**自带更新功能**：设置 →
 dsh plugin --profile <你的 profile> add github:BillCx330/dsh-plugin-notify-sounds
 ```
 
-**Release 压缩包** —— 从 [Releases](https://github.com/BillCx330/dsh-plugin-notify-sounds/releases) 下载 `.tgz`，交给 `dsh plugin add`。
+**Release 压缩包** —— 从 [Releases](https://github.com/BillCx330/dsh-plugin-notify-sounds/releases) 下载 `.tgz`，用它**在磁盘上的路径**安装：
+
+```sh
+dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds-1.7.0.tgz
+```
+
+（`dsh plugin add` 把参数原样交给包管理器，所以要给本地文件路径，不能填下载地址。）
 
 **本地目录** —— 开发或试用未发布的改动：
 
@@ -99,7 +105,8 @@ dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds
 ## ⚠️ 已知边界
 
 - **手改配置**：偏好写在 profile 的 `cordis.patch.yml`，值必须符合 schema（音量 0–100、音效为预设之一、时间 `HH:MM`）；写错会让插件不加载，改回即可。设置界面只会写入合法值。
-- **一键更新只换文件**：只替换本包内的七个文件，**不碰 profile 配置**；下载内容从不执行，新代码要等**重启 DSH** 才生效。更新过程请等状态行给出结果再关窗口（中断会自动还原）；若未来的新版引入了新依赖，需另行安装（当前零依赖）。
+- **一键更新只写文件**：把新版本带的文件写进本包目录（**新版新增的文件也会装上**），**不碰 profile 配置**；它只写不删——某个版本去掉的文件会留在更新过它的机器上（无害，但要重装才会彻底消失）。下载内容从不执行，新代码要等**重启 DSH** 才生效。更新过程请等状态行给出结果再关窗口（失败会自动还原，并告诉你下一步怎么做）；若未来的新版引入了新依赖，需另行安装（当前零依赖）。
+- **1.6.9 及更早版本无法更新到「新增了文件」的新版**：那些版本内置的是固定文件清单，遇到清单外的文件会整包拒绝——**不会损坏已装版本**，插件照常工作。从 npm 或仓库 Releases 手动重装一次即可永久解决：1.7.0 已取消该限制，之后任何版本都可以自由增减文件。
 - **多窗口**：各窗口独立触发，同一事件可能各响一次；打开「仅在页面不可见时提示」即可避免。
 - **点击通知回到窗口**：Windows 完整实现并实测；macOS / Linux 走系统深链，未验证。
 - **唤窗按窗口标题定位主窗口**：刻意不读取其他进程信息（那会触发杀软主动防御）。若将来 DSH 改变标题格式，唤窗会静默失效——提示音与通知本身不受影响。
@@ -123,6 +130,7 @@ dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds
 
 ## 📜 更新记录
 
+- **v1.7.0**（2026-10-16）**更新机制的转折点**：一键更新不再受「固定七个文件名」的白名单约束，改为按规则接受包目录下的任何普通文件——路径穿越、绝对路径、符号链接、非普通文件、保留名字（更新器自己的备份/临时名与记录文件、`.git`、`node_modules`、`.npmrc`）、含 `:` 的路径段，以及只有大小写不同的重名或**与 `package.json` 声明的入口只差大小写**的文件，依然一律拒绝，文件数与解压体积也都有上限（解压时即受 `gunzip` 上限约束）。**1.7.0 及以后可以正常更新到任意增减文件的新版**：某个版本去掉的文件现在会真的被删掉（依据更新器自己留下的 `.update-manifest.json` 记录，**只删它自己装过的文件**，用户放进目录里的东西一律不动；第一条记录之前的安装不做任何猜测）。**1.6.9 及更早**遇到「新增了文件」的新版会更新失败（安全失败：一个字节都不写，已装版本继续正常工作），README 里说明了重装一次的办法。修复：关掉「自动检查更新」会让每日轮询永久停摆（重新打开也不恢复）；窗口标题在两次 Win32 读取之间变短时，点通知唤窗会静默失效；预发布版本号按字符串比较（`rc.10` 被误判为比 `rc.9` 旧）；**同一个 GUI 开多个标签页或多个窗口时提示音、系统通知、重复提醒全部翻倍**（现在由 BroadcastChannel + 本地记录选出一个「发声页」，其余页保持安静，只在发声页消失后接管；窗口标题标记各窗口独立，不受影响）；自定义音效的峰值归一化改为**逐样本**扫描（原先每 8 帧抽样会与接近 fs/8 的高频混叠、系统性低估峰值）。更新失败时给出**按阶段区分的建议**（网络类提示重试；解包/替换类给出手动重装步骤与仓库地址，并列出失败的两个版本号），写入顺序改为**最后写 `package.json`**（中途崩溃时检查仍会提示更新，用户再点一次即可自愈），并会校验归档里的清单确实是本包、确实是 registry 报的那个版本。设置里「自定义音效」移到**三种提示音之后**（它们才是会用到它的三处）；`settings` 相关的小修：冷却表改为真正的 LRU（原先是 FIFO，最常触发的会话反而最先被淘汰）、会话列表每轮只取一次快照、macOS 桌面版的「窗口标题提醒」开关改为**禁用**（原先能打开但标记无处显示）、英文界面更新提示里残留的全角标点修掉、README 的 Release 安装说明改为可照做的本地路径写法。
 - **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 三断言）。

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",
@@ -178,7 +190,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": "未处理决策重复提醒",
@@ -220,9 +232,17 @@ window.__ModuleLoader__.load({
 			"update.failed": "检查失败（网络不可用）",
 			"update.apply": "立即更新",
 			"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 +277,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",
@@ -299,9 +319,17 @@ window.__ModuleLoader__.load({
 			"update.failed": "Check failed (no network)",
 			"update.apply": "Update now",
 			"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 +471,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 +610,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?.();
 			});
 		}
 
@@ -817,6 +867,183 @@ window.__ModuleLoader__.load({
 		/** 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 +1208,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 +1325,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 +1367,17 @@ 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(SystemNotifyRow, {
 						key: "systemNotify",
 						t,
@@ -1170,10 +1396,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),
 					}),
@@ -1728,7 +1954,6 @@ window.__ModuleLoader__.load({
 				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
@@ -1740,15 +1965,21 @@ window.__ModuleLoader__.load({
 			let status = payload === undefined
 				? t("update.idle")
 				: payload.updateAvailable === true
-					? `${t("update.available")} ${version(payload.latest)}`
+					? `${t("update.available")} ${formatVersion(payload.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}`;
+			let detail = payload === undefined ? status : `${t("update.current")} ${formatVersion(payload.current)} · ${status}`;
+			// Advice is a second line rather than more words in the first one:
+			// the failure line is the part a user scans, and the remedy only
+			// applies to some stages. `undefined` renders nothing at all.
+			let advice;
 			if (appliedDone) {
-				detail = `${t("update.done")}：${version(applied.from)} → ${version(applied.to)}，${t("update.restart")}`;
+				detail = updateAppliedText(t, applied);
 			} else if (state.phase === "applyFailed") {
-				detail = t("update.applyFailed", { stage: String(state.result?.stage ?? "?") });
+				const failure = updateFailureText(t, state.result, payload?.current);
+				detail = failure.detail;
+				advice = failure.advice;
 			}
 			const busy = state.phase === "checking" || state.phase === "updating";
 			return h("div", { className: css.row }, [
@@ -1756,6 +1987,7 @@ window.__ModuleLoader__.load({
 					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),
+					advice === undefined ? null : h("div", { className: css.hint, key: "advice" }, advice),
 				]),
 				h("div", { className: css.stackControl, key: "control" }, [
 					payload?.updateAvailable === true && !appliedDone ? h(Button, {
@@ -1893,6 +2125,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 +2199,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 +2238,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 +2247,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 +2268,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 +2289,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 +2317,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 +2342,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,9 +2411,9 @@ 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;
 				};
@@ -2180,7 +2435,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 +2445,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 +2477,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) {
@@ -2252,7 +2510,7 @@ window.__ModuleLoader__.load({
 						}
 					}
 					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
@@ -2372,9 +2630,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?.();
 				};
@@ -2425,6 +2691,21 @@ window.__ModuleLoader__.load({
 		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;
 	},

package/lib/index.js

@@ -28,7 +28,7 @@ import z from "@deepseek-ai/schemastery";
 import { spawn } from "node:child_process";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gunzipSync } from "node:zlib";
@@ -188,13 +188,22 @@ let nativeRaise;
  * @param handle - the window to read.
  * @returns the title text.
  */
-function windowTitle(native, handle) {
+export function windowTitle(native, handle) {
 	try {
 		const length = native.GetWindowTextLengthW(handle);
 		if (length <= 0) return "";
 		const buffer = new Uint16Array(length + 2);
-		native.GetWindowTextW(handle, buffer, buffer.length);
-		return Buffer.from(buffer.buffer, 0, length * 2).toString("utf16le");
+		const copied = native.GetWindowTextW(handle, buffer, buffer.length);
+		// The two calls are not atomic: between them the page can rewrite its
+		// title (switching sessions is exactly when it does), and this call
+		// then copies fewer characters than the first one counted. Slicing by
+		// the OLD count would hand back a string with NULs on the end — which
+		// no real title ever contains, and which silently stops `endsWith`
+		// matching, i.e. one click that does nothing at all. Slice by what was
+		// actually copied, and treat a nonsense return as "read the old count"
+		// rather than trusting it.
+		const written = Number.isFinite(copied) && copied >= 0 ? Math.min(copied, length) : length;
+		return Buffer.from(buffer.buffer, 0, written * 2).toString("utf16le");
 	} catch {
 		return "";
 	}
@@ -545,11 +554,47 @@ export function compareVersions(a, b) {
 	for (let i = 0; i < 3; i++) {
 		if (left[i] !== right[i]) return left[i] - right[i];
 	}
-	// Same core: a prerelease sorts before its own release (1.5.0-rc.1 < 1.5.0).
-	if (left[3] !== right[3]) {
-		if (left[3] === "") return 1;
-		if (right[3] === "") return -1;
-		return left[3] < right[3] ? -1 : 1;
+	return comparePrerelease(left[3], right[3]);
+}
+
+/**
+ * Compare two prerelease fields the way semver defines it, not as strings.
+ *
+ * Plain string order gets the common case wrong: `rc.10` sorts BEFORE `rc.9`
+ * ("1" < "9"), so a registry whose `latest` points at a later release candidate
+ * would look older than the one already installed and the update would never be
+ * offered. The rules are: identifiers are compared field by field; a numeric
+ * field compares numerically and ranks below an alphanumeric one; an
+ * alphanumeric field compares in ASCII order; and when every shared field is
+ * equal, the one with MORE fields wins (`1.0.0-rc.1` < `1.0.0-rc.1.1`).
+ *
+ * @param left - the prerelease field of the first version, "" for a release.
+ * @param right - the prerelease field of the second version.
+ * @returns negative, 0, or positive.
+ */
+function comparePrerelease(left, right) {
+	if (left === right) return 0;
+	// A release outranks any of its own prereleases (1.5.0 > 1.5.0-rc.1).
+	if (left === "") return 1;
+	if (right === "") return -1;
+	const a = left.split(".");
+	const b = right.split(".");
+	for (let i = 0; i < Math.max(a.length, b.length); i++) {
+		const x = a[i];
+		const y = b[i];
+		if (x === undefined) return -1;
+		if (y === undefined) return 1;
+		const numericX = /^\d+$/.test(x);
+		const numericY = /^\d+$/.test(y);
+		if (numericX && numericY) {
+			const dx = Number(x);
+			const dy = Number(y);
+			if (dx !== dy) return dx < dy ? -1 : 1;
+			continue;
+		}
+		// A numeric identifier always ranks below an alphanumeric one.
+		if (numericX !== numericY) return numericX ? -1 : 1;
+		if (x !== y) return x < y ? -1 : 1;
 	}
 	return 0;
 }
@@ -734,14 +779,41 @@ export const UPDATE_APPLY_PATH = "/notify-sounds/update/apply";
 const UPDATE_MAX_TARBALL_BYTES = 8 * 1024 * 1024;
 
 /**
- * The only files an update may replace, as package-relative paths.
+ * Largest expansion accepted after gunzip.
+ *
+ * The download cap alone does not bound memory: a few-hundred-KB gzip stream
+ * can expand to gigabytes, and that allocation happens inside this process.
+ * `gunzipSync` is given this as `maxOutputLength` so the limit is enforced
+ * while inflating rather than after.
+ */
+const UPDATE_MAX_UNPACKED_BYTES = UPDATE_MAX_TARBALL_BYTES * 8;
+
+/** Most files one release of this package may carry. It is a handful of text files. */
+const UPDATE_MAX_FILES = 256;
+
+/**
+ * Path segments an update may never contain, however an archive spells them.
+ *
+ * `.update-backup` is this updater's own working directory: an archive that
+ * carried a file with that name could leave the previous version's bytes
+ * exactly where a rollback looks for them. `node_modules` and `.git` are never
+ * published in a tarball, so an archive containing them describes a different
+ * tree than the one this installation came from.
+ */
+const UPDATE_RESERVED_SEGMENTS = new Set(["node_modules", ".git", ".update-backup"]);
+
+/**
+ * Records which files this updater installed, so the next update can prune.
  *
- * An update is a file swap, not an install: it replaces exactly what the
- * package publishes and touches nothing else. The profile's own configuration
- * lives outside this directory and is not on this list — no update can reach
- * it, whatever an archive contains.
+ * It lives in the installed package directory and is written by the updater at
+ * runtime — it is NEVER part of the published tarball, which is why adding it
+ * cannot break an older installation's update (those check the archive's file
+ * names, not what the directory happens to contain).
  */
-const UPDATE_FILES = ["package.json", "cordis.patch.yml", "README.md", "README.zh.md", "LICENSE", "lib/client.js", "lib/index.js"];
+const UPDATE_MANIFEST = ".update-manifest.json";
+
+/** Package-root names a package manager reads as configuration, and the updater's own bookkeeping; never delivered by an update. */
+const UPDATE_RESERVED_ROOT_FILES = new Set([".npmrc", ".pnpmfile.cjs", UPDATE_MANIFEST]);
 
 /** Where this package is installed: the only tree an update may write to. */
 function packageRoot() {
@@ -765,24 +837,43 @@ function readTarOctal(header, offset, length) {
 }
 
 /**
- * Map an archive path to the package-relative file it may replace.
+ * Map an archive path to the package-relative file it may write.
  *
  * Everything about a tar path is hostile until shown otherwise: only the
- * `package/` prefix the registry publishes under, only the whitelisted names,
- * and never a path that climbs, escapes, or arrives by another separator.
+ * `package/` prefix the registry publishes under, never a path that climbs,
+ * escapes, or arrives by another separator, never a reserved name, and never
+ * one that an NTFS alternate data stream could hide behind.
+ *
+ * What is deliberately NOT checked is the file's NAME. An exact list of seven
+ * names was the previous design and it was a trap: the updater that runs during
+ * an update is the one already installed, so its list decides what the NEXT
+ * release may contain. A release that added a file became uninstallable by
+ * every older installation — permanently, and with no way to fix it after the
+ * fact, because the old code is already on those machines. The rules below are
+ * the ones that never need to change (path safety, not a file inventory), so
+ * they can remain the whole gate while the file set moves forward.
  */
 export function archivePathToRelative(path) {
 	const normalized = path.replaceAll("\\", "/");
-	if (normalized.startsWith("/") || normalized.split("/").includes("..")) throw new Error(`refusing tar path: ${path}`);
+	const segments = normalized.split("/");
+	if (normalized.startsWith("/") || segments.includes("..")) throw new Error(`refusing tar path: ${path}`);
 	const prefix = "package/";
 	if (!normalized.startsWith(prefix)) throw new Error(`refusing tar path: ${path}`);
 	const relative = normalized.slice(prefix.length);
-	if (relative === "" || !UPDATE_FILES.includes(relative)) throw new Error(`refusing tar path: ${path}`);
+	if (relative === "" || relative.endsWith("/")) throw new Error(`refusing tar path: ${path}`);
+	for (const segment of relative.split("/")) {
+		// A `.` segment would let one file be named twice in one archive, and it
+		// slips past the case check below, which compares names rather than
+		// resolved paths.
+		if (segment === "" || segment === "." || segment.includes(":")) throw new Error(`refusing tar path: ${path}`);
+		if (UPDATE_RESERVED_SEGMENTS.has(segment) || segment.endsWith(".update-tmp")) throw new Error(`refusing tar path: ${path}`);
+	}
+	if (UPDATE_RESERVED_ROOT_FILES.has(relative)) throw new Error(`refusing tar path: ${path}`);
 	return relative;
 }
 
 /**
- * Read a tar archive into the few files an update may touch.
+ * Read a tar archive into the files an update may write.
  *
  * The archive arrived from the network and is treated accordingly:
  *
@@ -790,13 +881,19 @@ export function archivePathToRelative(path) {
  *     anywhere, so any other entry type is refused outright;
  *   - pax/gnu extension headers are skipped, not interpreted;
  *   - every name must survive `archivePathToRelative`, so nothing outside
- *     this package is ever named;
- *   - a header claiming more than the archive holds is an error, not a read.
+ *     this package is ever named and nothing reserved is ever written;
+ *   - two entries may not differ only in case: on Windows and macOS the second
+ *     would silently overwrite the first;
+ *   - a header claiming more than the archive holds is an error, not a read;
+ *   - the total size and the file count are capped, so an archive cannot turn
+ *     a bounded download into unbounded disk usage.
  *
  * @returns a Map of package-relative path → contents.
  */
 export function unpackTar(bytes) {
 	const files = new Map();
+	const seen = new Map();
+	let total = 0;
 	let offset = 0;
 	while (offset + 512 <= bytes.length) {
 		const header = bytes.subarray(offset, offset + 512);
@@ -812,12 +909,79 @@ export function unpackTar(bytes) {
 		offset = contentStart + Math.ceil(size / 512) * 512;
 		if (typeflag === "x" || typeflag === "g" || typeflag === "L") continue;
 		if (typeflag !== "0" && typeflag !== "") throw new Error(`refusing non-file tar entry (${typeflag})`);
-		files.set(archivePathToRelative(prefix === "" ? name : `${prefix}/${name}`), content);
+		const relative = archivePathToRelative(prefix === "" ? name : `${prefix}/${name}`);
+		const folded = relative.toLowerCase();
+		const collidesWith = seen.get(folded);
+		if (collidesWith !== undefined && collidesWith !== relative) {
+			throw new Error(`refusing two entries that differ only in case: ${collidesWith} / ${relative}`);
+		}
+		seen.set(folded, relative);
+		total += content.length;
+		if (total > UPDATE_MAX_UNPACKED_BYTES) throw new Error("the archive expands beyond its limit");
+		if (files.size >= UPDATE_MAX_FILES) throw new Error("the archive carries more files than this package can have");
+		files.set(relative, content);
 	}
 	if (files.size === 0) throw new Error("the archive carried no usable files");
 	return files;
 }
 
+/**
+ * Check that the archive really is this package, at the version the registry named.
+ *
+ * With the file inventory gone, this is what still ties the bytes to an
+ * identity. The registry answer was validated before anything was downloaded,
+ * and the digest binds the bytes to that answer's `dist` — but the archive's
+ * own manifest is the only thing that says WHICH package and version those
+ * bytes are, and the next check trusts the manifest this update leaves on
+ * disk. A manifest that is missing, unreadable, or about something else would
+ * otherwise be installed silently and make "an update landed" a lie the check
+ * cannot see through.
+ *
+ * @param files - the unpacked archive, package-relative path → contents.
+ * @param version - the version the registry announced.
+ * @returns the parsed manifest.
+ */
+export function verifyManifest(files, version) {
+	const manifest = files.get("package.json");
+	if (manifest === undefined) throw new Error("the archive carries no package.json");
+	let parsed;
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(manifest));
+	} catch {
+		throw new Error("the archive's package.json is not readable JSON");
+	}
+	if (parsed?.name !== UPDATE_PACKAGE) throw new Error(`the archive is not ${UPDATE_PACKAGE}`);
+	if (parsed?.version !== version) {
+		throw new Error(`the archive says version ${String(parsed?.version)} where the registry said ${version}`);
+	}
+	// A file whose name differs from a path this manifest declares only by case
+	// would replace that file on Windows and macOS and be a dead file on Linux:
+	// one archive, two different installations. The set is derived from the
+	// archive's OWN manifest (`package.json` itself, `main`, and every `exports`
+	// target) — never from a list held here — so a release stays free to move
+	// or rename its own files, which is the whole point of this design.
+	const declared = new Map([["package.json", "package.json"]]);
+	const declare = (value) => {
+		if (typeof value !== "string" || value === "") return;
+		const relative = value.startsWith("./") ? value.slice(2) : value;
+		declared.set(relative.toLowerCase(), relative);
+	};
+	const declareAll = (value) => {
+		if (typeof value === "string") declare(value);
+		else if (Array.isArray(value)) value.forEach(declareAll);
+		else if (value !== null && typeof value === "object") Object.values(value).forEach(declareAll);
+	};
+	declare(parsed.main);
+	declareAll(parsed.exports);
+	for (const relative of files.keys()) {
+		const target = declared.get(relative.toLowerCase());
+		if (target !== undefined && target !== relative) {
+			throw new Error(`refusing a file that differs only in case from ${target}: ${relative}`);
+		}
+	}
+	return parsed;
+}
+
 /**
  * Check downloaded bytes against the digest the registry published.
  *
@@ -873,6 +1037,48 @@ async function downloadTarball(url) {
 	throw new Error(`download refused: more than ${UPDATE_MAX_REDIRECTS} redirects`);
 }
 
+/**
+ * The file list a previous update recorded, as a Set.
+ *
+ * A missing, unreadable, or malformed manifest reads as "nothing recorded",
+ * which prunes nothing: the failure mode of a damaged manifest has to be
+ * "leaves a file behind", never "deletes something".
+ *
+ * @param root - the package directory.
+ * @returns the recorded package-relative paths.
+ */
+function readUpdateManifest(root) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(root, UPDATE_MANIFEST), "utf8"));
+		if (!Array.isArray(parsed?.files)) return new Set();
+		return new Set(parsed.files.filter((name) => typeof name === "string"));
+	} catch {
+		return new Set();
+	}
+}
+
+/**
+ * Which recorded files this release no longer carries.
+ *
+ * Only paths the PREVIOUS update wrote are candidates, so a file the user put
+ * in the package directory themselves is never named here and never removed.
+ * This is what makes an update add and remove files while the file-list rule
+ * stays out of the way — the alternative, shipping deletions inside the
+ * archive, is not something a tar can express.
+ *
+ * @param previous - paths recorded by the last update.
+ * @param files - the incoming archive's package-relative paths.
+ * @returns the paths to delete, sorted.
+ */
+export function filesToPrune(previous, files) {
+	const gone = [];
+	for (const relative of previous) {
+		if (relative === UPDATE_MANIFEST) continue;
+		if (!files.has(relative)) gone.push(relative);
+	}
+	return gone.sort();
+}
+
 /**
  * Swap the package's files for the update's, keeping the previous ones.
  *
@@ -880,41 +1086,127 @@ async function downloadTarball(url) {
  * failure cannot leave a half-written file under a real name. Everything the
  * update is about to replace is copied aside first, and any failure puts it
  * all back: a failed update is not a half-updated plugin.
+ *
+ * The files are whatever the archive carried, not a list held here. An earlier
+ * design iterated a fixed set of seven names, which meant a release could only
+ * ever touch those seven; that list is gone on purpose (see
+ * `archivePathToRelative`), and this function is the second half of the same
+ * decision — unpacking a new file and then never writing it would look exactly
+ * like a successful update that quietly did nothing.
  */
 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 });
+	// The manifest goes last, and that order is load-bearing. If this process
+	// dies mid-swap — a power cut or a kill, not a thrown error, which rolls
+	// back — the installation is left with the OLD version number over part of
+	// the new code, so the next check still reports an update and the user can
+	// retry. The opposite order would leave a NEW version number over the old
+	// code: the check would call that "up to date" and there would be nothing
+	// left to prompt anyone with.
+	const relatives = [...files.keys()].sort((a, b) => (a === "package.json" ? 1 : 0) - (b === "package.json" ? 1 : 0));
+	/** Directories this update creates, outermost first, so a rollback can take them back. */
+	const created = [];
 	const written = [];
+	/** Files this update deletes, kept aside first so a rollback can bring them back. */
+	const pruned = [];
+	/** The previous update's record, read before anything is written over it. */
+	const previous = readUpdateManifest(root);
+	const manifestPath = join(root, UPDATE_MANIFEST);
+	/** Copy the current bytes aside before they are replaced or removed. */
+	const backUp = (relative, target) => {
+		const aside = join(backup, relative);
+		mkdirSync(dirname(aside), { recursive: true });
+		writeFileSync(aside, readFileSync(target));
+	};
 	try {
-		for (const relative of UPDATE_FILES) {
+		for (const relative of relatives) {
 			const source = files.get(relative);
 			if (source === undefined) continue;
 			const target = resolve(root, relative);
 			if (target !== rootPrefix && !target.startsWith(rootPrefix)) throw new Error(`refusing to write outside the package: ${relative}`);
-			if (existsSync(target)) {
-				const aside = join(backup, relative);
-				mkdirSync(dirname(aside), { recursive: true });
-				writeFileSync(aside, readFileSync(target));
+			let parent = rootPrefix;
+			for (const segment of relative.split("/").slice(0, -1)) {
+				parent = join(parent, segment);
+				if (!existsSync(parent)) created.push(parent);
 			}
+			mkdirSync(dirname(target), { recursive: true });
+			if (existsSync(target)) backUp(relative, target);
 			const temp = tempName(relative);
 			writeFileSync(temp, source);
 			renameSync(temp, target);
 			written.push(relative);
 		}
+		// A release can also DROP a file, and an archive cannot say so: it is a
+		// list of what exists, not of what should be deleted. The previous
+		// update's record is what makes the difference computable, and it is
+		// deliberately limited to files an update wrote — anything else in this
+		// directory (a user's own notes, a tool's leftovers) is never named in
+		// the record and therefore never deleted.
+		for (const relative of filesToPrune(previous, files)) {
+			const target = resolve(root, relative);
+			if (target !== rootPrefix && !target.startsWith(rootPrefix)) continue;
+			// Files only. A path that is now a directory is left alone rather
+			// than failing the whole update, and never removed recursively.
+			try {
+				if (!statSync(target).isFile()) continue;
+			} catch {
+				continue;
+			}
+			backUp(relative, target);
+			rmSync(target, { force: true });
+			pruned.push(relative);
+		}
+		// The record is written LAST, through the same temporary-name swap as
+		// everything else, and it describes the state this update leaves behind:
+		// the incoming files plus itself, minus nothing.
+		if (existsSync(manifestPath)) backUp(UPDATE_MANIFEST, manifestPath);
+		const record = new TextEncoder().encode(JSON.stringify({ version: 1, files: [...files.keys(), UPDATE_MANIFEST].sort() }));
+		writeFileSync(`${manifestPath}.update-tmp`, record);
+		renameSync(`${manifestPath}.update-tmp`, manifestPath);
+		written.push(UPDATE_MANIFEST);
 	} 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.
+		// no backup to restore from and must simply go away again, the files it
+		// DELETED, which come back from their copies, and the directories it
+		// created. A failed update has to leave nothing behind: no half-replaced
+		// file, no leftover temp, no file that was not there before, and no
+		// empty directory either.
 		for (const relative of written) {
 			const aside = join(backup, relative);
 			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 });
+		for (const relative of pruned) {
+			const aside = join(backup, relative);
+			if (existsSync(aside)) writeFileSync(resolve(root, relative), readFileSync(aside));
+		}
+		for (const relative of relatives) rmSync(tempName(relative), { force: true });
+		// Guarded: a cleanup step must never replace the failure it is cleaning
+		// up after (this path can hold a directory, and `rmSync` refuses one
+		// without `recursive`).
+		try {
+			rmSync(`${manifestPath}.update-tmp`, { force: true });
+		} catch {}
+		// Deepest first, so a chain collapses one level at a time. `rmdirSync`
+		// refuses a directory that still holds something, which is the point:
+		// a failure here must never delete real content. (Not `rmSync` — that
+		// one needs `recursive` even for an empty directory on Windows and
+		// throws EISDIR, which would have left every created directory behind.)
+		for (const directory of created.reverse()) {
+			try {
+				rmdirSync(directory);
+			} catch {}
+		}
+		// The restore above is done, so the copies have no further use. If a
+		// restore threw, this is never reached and the backup stays on disk —
+		// which is the one case where keeping it is the safer outcome.
+		try {
+			rmSync(backup, { recursive: true, force: true });
+		} catch {}
 		throw error;
 	}
 	// The swap succeeded, so the backup has done its job. Leaving it would
@@ -930,8 +1222,10 @@ export function installUpdate(root, files) {
  * registry (the answer is validated as strictly as for a check); download the
  * tarball from the URL that answer named and nowhere else; verify its sha512
  * against the digest the registry published — a mismatch stops here, before a
- * byte is written; unpack it in memory, accepting only whitelisted regular
- * files; then back up what is there and swap the files, restoring on failure.
+ * byte is written; unpack it in memory, accepting only regular files that stay
+ * inside the package, and confirm its manifest is this package at the version
+ * the registry announced; then back up what is there and swap the files,
+ * restoring on failure.
  *
  * Nothing downloaded is ever executed here. The new code runs when DSH
  * restarts, which is the same trust model as the user updating by hand.
@@ -959,17 +1253,25 @@ async function runUpdate(options = {}) {
 	const root = options.root ?? packageRoot();
 	const current = readOwnVersion(root);
 	let stage = "check";
+	/** The version the registry announced, once there is one, for the failure report. */
+	let announced;
 	try {
 		const answer = await fetchRegistryAnswer();
 		if (answer === undefined) return { ok: false, stage, error: "no registry answered" };
 		const ordering = current === undefined ? NaN : compareVersions(current, answer.version);
 		if (Number.isFinite(ordering) && ordering >= 0) return { ok: true, upToDate: true, current };
+		announced = answer.version;
 		stage = "download";
 		const bytes = await downloadTarball(answer.tarball);
 		stage = "verify";
 		verifyIntegrity(bytes, answer.integrity);
 		stage = "unpack";
-		const files = unpackTar(gunzipSync(bytes));
+		// A gzip stream can expand far beyond the bytes it arrived in, so the
+		// decompressor is told where to stop instead of being trusted to be
+		// reasonable; the tarball cap above bounds the input, not the output.
+		const files = unpackTar(gunzipSync(bytes, { maxOutputLength: UPDATE_MAX_UNPACKED_BYTES }));
+		stage = "manifest";
+		verifyManifest(files, answer.version);
 		stage = "replace";
 		installUpdate(root, files);
 		// The answer that said "update available" is now a lie about this
@@ -986,7 +1288,7 @@ async function runUpdate(options = {}) {
 		return { ok: true, from: current, to: answer.version, requiresRestart: true };
 	} catch (error) {
 		warn(`update failed at ${stage}: ${error?.message ?? error}`);
-		return { ok: false, stage, error: error?.message ?? String(error) };
+		return { ok: false, stage, to: announced, error: error?.message ?? String(error) };
 	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-notify-sounds",
-  "version": "1.6.9",
+  "version": "1.7.0",
   "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",
@@ -18,8 +18,7 @@
     "lib/index.js",
     "lib/client.js",
     "cordis.patch.yml",
-    "README.zh.md",
-    "assets"
+    "README.zh.md"
   ],
   "license": "MIT",
   "repository": {