dsh-notify-me 1.17.0 → 1.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,74 @@
2
2
 
3
3
  All notable changes to **dsh-notify-me** are documented here.
4
4
 
5
+ ## [1.19.0] — 2026-11-09
6
+
7
+ 「回到页面也保留提醒」把 1.17.0 的收起动作交还给你;Windows 桌面端的审批通知终于带上真的「同意 / 拒绝」按钮,macOS 桌面端的系统通知改由宿主助手发出。同时收编 [#27](https://github.com/chromoany/dsh-notify-me/issues/27) / [#28](https://github.com/chromoany/dsh-notify-me/pull/28) / [#29](https://github.com/chromoany/dsh-notify-me/issues/29) / [#30](https://github.com/chromoany/dsh-notify-me/pull/30) / [#31](https://github.com/chromoany/dsh-notify-me/issues/31) / [#32](https://github.com/chromoany/dsh-notify-me/pull/32) / [#33](https://github.com/chromoany/dsh-notify-me/issues/33):把「转发外部通知」总开关接到宿主兜底上,并修掉 macOS 原生通道的几个边界。
8
+
9
+ ### 新增
10
+
11
+ - **回到页面也保留提醒**(配置键 `keepOnReturn`,默认关;[#27](https://github.com/chromoany/dsh-notify-me/issues/27) / [#28](https://github.com/chromoany/dsh-notify-me/pull/28)):1.17.0 起只要回到 DSH 页面,残留通知一律收起。系统通知样式设成「持续」时,这正好把你要留着的提醒收走——现在打开这个开关,离开时收到的通知在你回到页面后不再被收起,留到你点掉或点「关闭」。它只管「回到页面收起残留通知」这一条;三种「自动消失」仍只管定时关闭。
12
+ - **一键「前台也提醒」**([#27](https://github.com/chromoany/dsh-notify-me/issues/27) 第 2 点):设置页「什么时候提醒」卡片顶部新增这一行,一次把「窗口在前台时也提醒『需要你』」打开、「当前对话不弹通知」关掉、「回复完成」设为「总是提醒」——等价于下面三项都调成前台可见。关掉它恢复默认的「只在后台提醒」。它不新增存储键,只是那三项的派生视图,三者任一被单独改动,这一行会跟着变。
13
+ - **Windows 桌面端审批通知带「同意 / 拒绝」按钮**([#33](https://github.com/chromoany/dsh-notify-me/issues/33)):Electron 的渲染进程把 `Notification` 的 `actions` 数组整个丢掉(`platform_notification_service.cc` 只抄 title/body/tag/icon/silent/has_reply/timeout_type),桌面端 `dsh-app://` 又注册不了 Service Worker——按钮因此从来没在 Windows 桌面出现过。现在审批提醒改由宿主发原生 Toast:`lib/index.js` 起 `lib/win-toast.ps1`(WinRT `ToastNotificationManager`,AUMID `electron.app.DeepSeek Harness`),按钮用 `activationType="protocol"` 指向 `dsh-notify-me://approve?token=…` / reject,点击后宿主把动作交回页面,仍走页面里同一个 `decidePending()`——「同意」就是「允许一次」,不多放行任何东西。首次使用时在 `HKCU\Software\Classes\dsh-notify-me` 注册协议处理器(一个把动作写入文件再打开 `dsh://open` 的 VBS);token 单次、3 分钟有效,动作文件取走即删。不需要编译、不需要管理员权限;关掉它:profile patch 层 `winToast: { enabled: false }`。
14
+ - **macOS 桌面端系统通知**([#31](https://github.com/chromoany/dsh-notify-me/issues/31) / [#32](https://github.com/chromoany/dsh-notify-me/pull/32),原提案 xty13114150041):页面里的 `new Notification()` 在 `dsh-app://app` 上进不了通知中心。新增 `lib/mac-notify.js` + `macos/DSHNotify.swift`(`macos/build.sh` 编译),宿主用 `UNUserNotificationCenter` 发通知;点通知把会话 id 写回临时文件并打开 `dsh://open`,页面重新获得焦点时取走并切到对应对话,`autoFocus` 关掉时只抬窗。`macNotify: { enabled, appPath }`,路由与助手都就绪时才生效;提示音仍由页面合成,「系统通知音」模式交给 macOS。
15
+
16
+ ### 修复
17
+
18
+ - **总开关现在也管页面关闭后的宿主兜底**:宿主侧兜底(`hostFallback`)推送时只问了「有没有页面持有租约」,从不知道页面里那个总开关,心跳也刻意没带它。于是把「转发外部通知」关掉、再关掉标签页,宿主照样把「回复完成 / 审批请求」推到你的网关——正是刚被关掉的那条外部通知。现在心跳与 pagehide 释放都会带上 `external: {enabled, attention, done}`,宿主侧兜底照它决定推不推:总开关关了就两条都不推,「转发「需要你」」关了只留回复完成,「转发「回复完成」」关了只留审批。被开关压下的审批不占去重 id,开关再打开时同一审批仍会补上;被压下的 `turn/end` 也不吃掉那 15 秒节流窗口。
19
+ - **开关一改就立刻告诉宿主**:与静音列表同一条路径——改完马上补一次心跳,而不是等下一次间隔(最长 20 秒)。关掉开关、紧接着关标签页,不会再有那一段「宿主还按旧答案推送」的窗口。
20
+ - **半截的开关汇报按「没说过」处理**:`external` 只有三个字段全是布尔才被采纳;缺字段、写错类型都保留上一次的答案,绝不会因为读到 `enabled` 缺失就当成关闭,把运维明确打开的兜底悄悄静音。页面从没报过开关时(宿主刚起来、页面还没打开)兜底照旧按 `hostFallback.enabled` 推,不会被静音。
21
+ - **macOS 原生通道不再漏掉启动时的等待**:探测是异步的,而宿主起来时积压的等待可能在探测回包前就被绑定并计为「已提醒」——那一条用页面通知发不出去(macOS 桌面端本来就收不到),此后再也不会补发。现在探测完成前到达的提醒先排队,探测回包后统一重放;期间已被答掉的审批直接丢弃,不再补一条幽灵通知。探测同时加了「页面必须真的在桌面壳里」这一道门(`isDesktopShell()`),浏览器经隧道连到 macOS 宿主时不会再把提醒送进宿主机器。
22
+ - **原生通知也参与收起与自动消失**:macOS 通知中心里的那条原来不归 `trackToast()` 记账,回到页面收不掉,「总是关闭 / 从不关闭」也管不到它。助手新增 `--id` / `--remove` 两个参数(按请求 identifier 撤回),页面侧把原生通知按 tag 记账并交给同一套定时器与 `withdrawToasts()`——回到页面(或打开 `keepOnReturn` 时保留)、到点关闭,与构造器通知一致。Windows 原生 Toast 走同一条记账路径,`remove` 用 `ToastNotificationManager.History.Remove(tag, group, aumid)`。
23
+ - **助手可以按 id 撤回**:`lib/mac-notify.js` 的 `POST /__dsh-notify-me/mac-notify` 新增 `{remove: id}` 分支;`macos/DSHNotify.swift` 收到 `--remove <id>` 时调用 `removeDeliveredNotifications(withIdentifiers:)` 后退出。`--id` 为空时仍回落 UUID,旧助手没有这两个参数也不会被打坏(撤回失败只是留在通知中心,不影响提醒)。
24
+ - **macOS 路由测试不再依赖 POSIX shell**:原测试用 `#!/bin/sh` 桩当助手可执行文件,Windows CI 上 `spawn` 不认 shebang,恰是 Codex 在 #32 上标出的 P1。`mountMacNotify` 现在接受可注入的 `deps`(`spawn` / `execFile` / `clickFile`),测试用假 `spawn` + 普通空文件当助手,任何平台都跑;`smoke/win-toast-test.mjs` 同样用假 `spawn` 驱动 `reg.exe` / `powershell.exe`。
25
+
26
+ ### 变更
27
+
28
+ - **设置页总开关的说明补上兜底**:中文「关闭后不向任何外部端点发送,页面关闭后的宿主兜底也一样。」、英文同样加一句,原先那句只描述页面自己。
29
+ - **健康探针新增 `pageExternal`**:报出页面最近一次汇报的开关(没报过是 `null`)。「兜底怎么不推了」这类问题,答案就在这里。
30
+ - **macOS 桌面端不再依赖页面通知权限**:路由可用时提示音仍由页面合成,只有「系统通知音」模式交给 macOS。
31
+ - **未注册原生路由的平台行为不变**:Linux、Web、助手未编译、`winToast` 关掉时都退回原来的页面通知;macOS 审批通知仍不带快捷裁决按钮,Windows 桌面端改由宿主 Toast 提供按钮。
32
+ - **设置页文案按通道分流**:「审批通知上直接裁决」的说明、「试一试」的反馈、「回到页面就收起」的边界都写明 Web 有按钮、Windows 桌面端有按钮、macOS 桌面端没有;`bridgeOffDesktop` 同样按通道说清。
33
+ - **原生通知与页面通知共用同一套开关**:`keepOnReturn` / 三种「自动消失」对宿主发出的通知同样生效;`debug()` 新增 `winNative` / `winNativeLast`。
34
+
35
+ ### 测试
36
+
37
+ - `smoke/host-fallback-test.mjs` 新增两节:总开关关闭后两种提醒都不推出、打开后恢复、「需要你 / 回复完成」各自只静音自己那一类、被压下的审批不烧 id、页面从没报过开关时仍然推送。
38
+ - `smoke/page-bridge-test.mjs` 新增:`createPresence` 的 `externalAllowed()` 语义(未报告 → 放行、总开关 → 全静音、分项 → 只静音自己、半截报告 → 保留上一次、释放后仍记得),以及心跳里 `external` 字段的容错。
39
+ - `smoke/smoke-test.cjs`:心跳体改为 `{alive, external, language, muted}`,释放体为 `{alive, external, language}`;新增「改开关立即补一次心跳」;webhook 计数视图改为屏蔽整条 host-bridge 路由(探测、心跳、释放都算宿主协调,不算投递);`keepOnReturn` 打开后回到页面不再收起残留通知。
40
+ - `smoke/mac-notify-test.mjs` 重写:`mountMacNotify` 注入假 `spawn` / `execFile` 与临时 `clickFile`,助手只是普通文件、无需可执行位;覆盖未在 macOS 桌面宿主时不注册、缺助手时 `enabled:false` 与 `501`、探针、`405` / `403` / `400`、传入参数含 `--id` / `--sound`、`{remove:id}` 走撤回、点击回传只被取走一次。
41
+ - 新增 `smoke/win-toast-test.mjs`:Windows 桌面门控、探针与 `enabled`、`405` / `403` / `501` / `400`、审批 payload(AUMID / tag / 标题 / 按钮 token / 文案)与 base64 传递、`HKCU\Software\Classes\dsh-notify-me` 的三条注册命令、协议动作单次绑定审批 key、`open` 动作带会话、token 过期、`{remove}` 走 `-RemoveTag`。用假 `spawn` 驱动 `reg.exe` / `powershell.exe`,不需要真宿主。
42
+ - `npm test` 现在跑八套:上面这些加上原有的 host-route / page-bridge / host-fallback / relay / cordis-host,`smoke/smoke-test.cjs` 末尾断言 `api.version` 与 `package.json` 一致(1.19.0)。
43
+
44
+ ### 文档
45
+
46
+ - README 中英的心跳契约更新为 `{alive, language, muted, external}`,并重写「心跳不带页面的推送开关」那段立场:可见性 / 闲置那类启发式仍然不带(宿主看不见,只照做一半会得到谁也说不清的规则),但用户亲手写进配置的开关与静音列表一样,宿主照它执行就是页面自己的意思。
47
+ - README 中英新增「Windows 桌面端怎么发带按钮的通知」一节;「macOS 桌面端怎么发系统通知」补上原生通知参与收起 / 自动消失、启动时排队的等待会重放、助手 `--id` / `--remove`;顶部导读、提醒渠道表、已知限制与开发自检的测试清单同步。
48
+ - `docs/console-config.md` / `.en.md` 补 `winToast`(profile patch 层配置,`{enabled:false}` 关掉宿主原生审批 Toast)与 `debug().winNative` / `winNativeLast`。
49
+ - `cordis.patch.yml` 补 `winToast` 配置行与注释;`docs/listing.md` 的 `latest` 更新到 1.19.0。
50
+ - 设置页截图未重拍:两张都还是 1.18.0 的界面,1.19.0 在「什么时候提醒」里多了一行「前台也提醒(一键)」,`docs/README.md` 的尺寸表已按这个口径标注。
51
+
52
+ ## [1.18.0] — 2026-11-08
53
+
54
+ 回应 [#26](https://github.com/chromoany/dsh-notify-me/issues/26):会话行悬停时那两个图标已经挤到标题了——铃铛可以关掉,右键菜单里也放一个同样能用的。
55
+
56
+ ### 新增
57
+
58
+ - **会话右键菜单也能静音**:右键点侧边栏的会话,菜单里多一行「静音此会话的提醒」/「取消静音,恢复此会话的提醒」,图标与按下状态跟悬停铃铛一致,点完菜单自动收起。它注在宿主旧的 `sidebar.workspaces.session.menu.item` 槽位(渲染在「归档」一行之前),优先用宿主自带的 `MenuItemButton`,看起来跟内置菜单行一样;宿主没有这个平台模块时回落成插件自己的 `role="menuitem"` 按钮。触摸设备本来就不显示悬停条,这一行是它们唯一的静音入口。
59
+ - **悬停铃铛可以关掉**:设置页「会话静音」卡片顶部新增开关「悬停时显示静音按钮」(配置键 `muteRowButton`,默认开)。关掉后未静音的会话悬停时不再出铃铛,改用右键菜单;已静音的会话仍然保留这枚铃铛——它在那里既是状态提示,也是一键取消静音的入口;标题前那个划掉的铃铛不受影响。手改的配置值不是布尔时回落默认,而不是悄悄变成关闭。
60
+
61
+ ### 修复
62
+
63
+ - **刷新后静音列表不再被清空**:`cleanMutedSessions` 的两个上限(`MUTED_MAX` / `MUTED_ID_MAX`)原本声明在 `readConfig()` 之后,而 `readConfig()` 在工厂初始化时就执行——那时两个上限还是 `undefined`,`out.length < undefined` 恒假,存过的静音 id 在启动时被整列表剪空。于是刷新页面后静音看上去还在(设置页读存储能数出来),实际提醒照发,直到下一次改设置重新读一遍存储才「想起来」。现在两个上限移到 `readConfig()` 之前,静音真正跨刷新保留;这是 1.16.0 起就存在的缺陷,与 [#26](https://github.com/chromoany/dsh-notify-me/issues/26) 同一片代码,一并修掉。
64
+
65
+ ### 测试
66
+
67
+ - `smoke/smoke-test.cjs` 的 `mutedSessionsUi` 扩写:两种语言的新文案、菜单槽位注入与注册、回退按钮的 `role="menuitem"` 与点击后经 `useMenuOpenState` 收起菜单、静音/取消静音往返、开关默认开、关掉后未静音行不渲染而静音行保留铃铛、标题前标记仍在、开关点击写回、非布尔值回落默认;卡片计数与一键恢复照旧。启动时从存储读静音列表这条路径也由这个用例覆盖(关掉悬停铃铛的页面直接按存储里的静音 id 渲染行尾铃铛)。
68
+
69
+ ### 文档
70
+
71
+ - README 中英「静音某些对话」补上右键菜单入口与「悬停时显示静音按钮」开关,边界条件说明菜单行依赖宿主旧菜单槽位、悬停铃铛关掉后的表现;`docs/listing.md` 的 `latest` 更新到 1.18.0。
72
+
5
73
  ## [1.17.0] — 2026-10-29
6
74
 
7
75
  回到页面,还挂着的通知立刻收起;三种「自动消失」设置从此只约束定时关闭。
@@ -26,7 +94,7 @@ All notable changes to **dsh-notify-me** are documented here.
26
94
 
27
95
  ### 文档
28
96
 
29
- - README 中英同步:顶部特性里的「人走开但窗口没走」补一句回到页面就收起残留通知;「通知自动消失」与「离开时保留」两处改写边界(三种设置只约束定时关闭、回到页面一律收起、不看通知中心也不会被遗留通知挡着);提醒渠道一节补同样的边界;开发自检的测试清单补上这一节。
97
+ - README 中英同步:顶部特性里的「人走开但窗口没走」补一句回到页面就收起残留通知;「通知自动消失」与「离开时保留」两处改写边界(三种设置只约束定时关闭、回到页面一律收起、不看通知中心也不会被遗留通知挡着);提醒渠道一节补同样的边界;开发自检的测试清单补上这一节;控制台 `debug()` 一行补上新增的三个字段(`README.md:85` / `README.en.md:85`)。
30
98
  - `docs/console-config.md` / `docs/console-config.en.md` 的 `autoDismiss` 注释补一句「只管定时关闭」。
31
99
 
32
100
  ## [1.16.1] — 2026-10-28
package/README.en.md CHANGED
@@ -1,8 +1,6 @@
1
1
  <div align="center">
2
2
 
3
- <img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/brand/icon-app-128.png" width="76" height="76" alt="dsh-notify-me">
4
-
5
- # dsh-notify-me
3
+ <img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/brand/header.jpg" width="100%" alt="Banner: a lit bell mark over a dark desk scene, titled dsh-notify-me, subtitled Step away. Stay informed.">
6
4
 
7
5
  **Step away from DSH and know when to come back.**
8
6
 
@@ -15,7 +13,7 @@
15
13
  [![test](https://github.com/chromoany/dsh-notify-me/actions/workflows/test.yml/badge.svg)](https://github.com/chromoany/dsh-notify-me/actions/workflows/test.yml)
16
14
  [![DSH Web and Desktop](https://img.shields.io/badge/DSH-Web%20%7C%20Desktop-blue?style=flat-square)](#installation)
17
15
  [![Package size](https://img.shields.io/npm/unpacked-size/dsh-notify-me?style=flat-square&label=package%20size)](https://www.npmjs.com/package/dsh-notify-me)
18
- [![DSH Compatibility](https://img.shields.io/badge/DSH-tested%200.2.2--alpha.2-6366f1.svg?style=flat-square)](#compatibility)
16
+ [![DSH Compatibility](https://img.shields.io/badge/DSH-tested%200.2.2--rc.1%20%2F%200.2.1--rc.5-6366f1.svg?style=flat-square)](#compatibility)
19
17
  [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
20
18
 
21
19
  </div>
@@ -26,11 +24,13 @@ A notification plugin for DSH Web / Desktop, so you can afford to keep full acce
26
24
 
27
25
  - **When input is needed:** approval, plan review, and questions get a notification, a sound, and a title marker.
28
26
  - **When a background reply finishes:** come back for the result; clicking the notification returns to that conversation. Pick "background only", "quiet for the open one", or "always".
29
- - **When you walk off but the window stays in front:** over 3 minutes without input counts as away, and the alert still fires as usual; the toast that arrived does not clear itself before you come back, and is withdrawn the moment you are back at the page (taskbar, Alt-Tab or the toast itself).
27
+ - **When you walk off but the window stays in front:** over 3 minutes without input counts as away, and the alert still fires as usual; the toast that arrived does not clear itself before you come back, and is withdrawn the moment you are back at the page (taskbar, Alt-Tab or the toast itself) — turn on "keep alerts when you come back" to let it wait there instead.
30
28
  - **When you leave your computer:** optionally forward alerts to Discord, Bark, Gotify, Feishu group bots, ServerChan, WxPusher, or your own webhook.
31
29
  - **When you close the page entirely:** optional host-side fallback — with no page open the host process keeps pushing "needs you" / "reply finished" to your gateway; or turn on just the same-origin relay so the page can reach an authenticated gateway. Both are off by default and configured in the profile's patch layer (see "After the page closes" under [Advanced](#advanced)).
32
30
 
33
- > The page or desktop app has to stay running (background / minimized is fine); system notifications need notification permission. Approval buttons rely on a Service Worker, so only Web has them — Desktop notifications carry no buttons, and clicking one takes you back to the conversation to decide. With host-side fallback enabled you still get external push once the page is closed — local toasts and the approval buttons still need the page.
31
+ > **macOS Desktop (DSH Desktop)** raises its system notifications through a small host-spawned helper, `DSH Notify.app`: build it once with `bash macos/build.sh` and allow it in System Settings (see [How macOS Desktop raises system notifications](#how-macos-desktop-raises-system-notifications)).
32
+
33
+ > The page or desktop app has to stay running (background / minimized is fine); system notifications need notification permission. Approval buttons rely on a Service Worker, so Web gets them through the page's own notification; Windows Desktop gets them through a native toast posted by the host, while macOS Desktop notifications still carry no buttons — clicking one takes you back to the conversation to decide. With host-side fallback enabled you still get external push once the page is closed — local toasts and the approval buttons still need the page.
34
34
 
35
35
  ## UI Preview
36
36
 
@@ -74,15 +74,15 @@ The Electron application manages the `desktop` profile. Do not change the Web co
74
74
  2. Open **Settings → Notify me**. Confirm that the section and the plugin version at its foot appear, and leave "Enable reminders" and "Sound" on.
75
75
  3. Click **Test "reply finished"** on the settings page. A test notification should appear and play a sound according to your current sound settings. This local test is not forwarded to any external endpoint, and the "also alert while the window is in front" switch does not apply to it.
76
76
 
77
- Web users can also test the approval buttons, which then appear on the notification. Desktop cannot get a Service Worker, so this test sends a plain notification; real approval alerts work the same way — the toast fires, and clicking it takes you back to the conversation to decide.
77
+ Web users can also test the approval buttons, which then appear on the notification. Windows Desktop posts a native toast through the host and also carries the buttons (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)); macOS Desktop has no Service Worker and its native helper carries no buttons, so this test sends a plain notification — real approval alerts work the same way, and clicking one takes you back to the conversation to decide.
78
78
 
79
79
  **Optional console check** — in environments with DevTools, you can also run:
80
80
 
81
81
  ```js
82
82
  window.__dshNotifyMe.test("done") // "reply finished" sample
83
83
  window.__dshNotifyMe.test("attention") // "needs you" sample
84
- window.__dshNotifyMe.test("approval") // Approve / Reject when the bridge is available; a plain notification otherwise (which is what Desktop gets)
85
- window.__dshNotifyMe.debug() // bridge ("active" = buttons work), raiseChannel, the last raise attempt in raiseLast, a refused toast's platform message in lastToastReject, configStored for whether the settings really persisted, and hostBridge for host coordination
84
+ window.__dshNotifyMe.test("approval") // Approve / Reject when the bridge is available (Web) or through the Windows desktop host's native toast; a plain notification otherwise (macOS Desktop, or no Service Worker)
85
+ window.__dshNotifyMe.debug() // bridge ("active" = buttons work), raiseChannel, the last raise attempt in raiseLast, a refused toast's platform message in lastToastReject, configStored for whether the settings really persisted, hostBridge for host coordination, and the native channels in macNative / macNativeLast and winNative / winNativeLast; after coming back to the page, toastsLive / toastsWithdrawn / lastToastWithdrawAt show what is still tracked, how many were withdrawn, and when that last happened
86
86
  ```
87
87
 
88
88
  If no test notification appears, check in this order: whether the notification permission was declined (click once on the page and choose **Allow**; or address-bar lock → Site settings → Notifications → Allow → reload), whether DSH was restarted after installing, and whether the browser's notifications are switched off in the OS settings.
@@ -101,7 +101,7 @@ dsh-notify-me decouples **supervision** from **sitting in front of the screen**:
101
101
  | 🔔 Input needed | Alerts even in the foreground; the conversation on screen keeps only a title marker |
102
102
  | ✅ Reply finished | Alerts while the page is hidden / backgrounded (or "quiet for the open one" / "always") |
103
103
 
104
- **Input needed** covers approval requests, plan review, and questions (`ask_user_question`). The approve / reject quick decision only works on Web, where the toast carries the buttons; on Desktop, click the notification to decide in the conversation (see [Known limitations](#known-limitations)).
104
+ **Input needed** covers approval requests, plan review, and questions (`ask_user_question`). The approve / reject quick decision works where a notification can carry buttons: Web through the Service Worker bridge, Windows Desktop through the host-posted native toast. macOS Desktop and pages without a Service Worker get a plain notification — click it and decide in the conversation (see [Known limitations](#known-limitations)).
105
105
 
106
106
  **Reply finished** also covers background sessions. A finished but unread session keeps the `✅ Reply finished ·` title marker until opened. Title markers are independent of the alert policy.
107
107
 
@@ -117,16 +117,18 @@ Open **Settings → Notify me**. The page lays out three blocks — how you get
117
117
 
118
118
  - **Enable reminders** — master switch: off means no toasts, no sound, and the tab title is left alone;
119
119
  - **Sound / Volume** — the switch toggles directly; the volume slider is folded into that row and revealed by clicking the title (▸ becomes ▾). What it actually plays is decided by Advanced → Alert sound source;
120
- - **Decide approvals from the toast** (on by default) — approvals carry Approve / Reject, one click settles the request without switching back. Web gets a system notification with buttons; Desktop `dsh-app://` cannot register a Service Worker, so the notification has no buttons and you click it to decide in the conversation. The line under "Try it" states truthfully whether the current environment can provide buttons.
120
+ - **Decide approvals from the toast** (on by default) — approvals carry Approve / Reject, one click settles the request without switching back. Web gets a system notification with buttons; Windows Desktop gets a native toast posted by the host, with the same two buttons; macOS Desktop `dsh-app://` cannot register a Service Worker and its native helper carries no buttons, so there you click the notification and decide in the conversation. The line under "Try it" states truthfully whether the current environment can provide buttons.
121
121
 
122
122
  ### When to alert
123
123
 
124
124
  - **Also alert "needs you" while the window is in front** (on by default): off means you only hear it once the window goes to the background;
125
+ - **Alert in the foreground too (one switch)** (off by default): turns on "also alert 'needs you' in the foreground", turns off "stay quiet for the conversation on screen", and sets "reply finished" to "always" in one click — it is not its own stored key, just a derived view of those three, and the row follows if you change one of them individually; turn it off to restore the default background-only behaviour;
125
126
  - **Stay quiet for the conversation on screen** (on by default): a wait in the conversation you are looking at keeps only the tab marker, and is delivered once you leave;
126
127
  - **When "reply finished" alerts** (default "background only"): background only / quiet for the open one / always — pick one;
127
128
  - **Dismiss the toast automatically** (default "keep while away"): keep while away / always close / never close — pick one; the choice only covers the closing on the timer, and leftover toasts are withdrawn once you are back at the page;
129
+ - **Keep alerts when you come back** (off by default): when on, alerts that arrived while you were away are not withdrawn after you return to the DSH page — they stay until you dismiss them or click Close. Meant for an OS notification style that keeps alerts on screen, when the reminder itself should wait there;
128
130
  - **Ignore subagent sessions** (on by default): skips background subagent sessions, while the one you have open still alerts;
129
- - **Click a toast to open that conversation** (on by default): switches to that conversation and brings the window forward — on Windows through the host route, on macOS / Linux through the `dsh://open` deep link — and with several tabs only one is raised.
131
+ - **Click a toast to open that conversation** (on by default): switches to that conversation and brings the window forward — on Windows through the host route, on macOS / Linux through the `dsh://open` deep link — and with several tabs only one is raised. Host-posted native notifications (Windows native toast, macOS Notification Centre) use the same click handling.
130
132
 
131
133
  <details>
132
134
  <summary>Edge cases behind the switches</summary>
@@ -134,7 +136,7 @@ Open **Settings → Notify me**. The page lays out three blocks — how you get
134
136
  - **What counts as background**: switching to another app, being covered by another window, or minimizing all count; a window left in front with 3 minutes of no keyboard or mouse input counts too, and `idleMinutes: 0` falls back to looking only at the window.
135
137
  - **When "stay quiet for the conversation on screen" is replayed**: as usual once the window goes to the background or the idle timer fires; if you already handled it, it is dropped.
136
138
  - **The three "reply finished" choices**: "background only" = alert when you are not watching the page; "quiet for the open one" = the one on screen stays silent while other conversations still alert, useful with several open; "always" = never suppress. An old profile's "also alert 'reply finished' while in front" switch migrates to this setting automatically.
137
- - **"Keep while away"**: while you are at the page a plain toast closes itself after a few seconds; one that arrived while you were away stays in the notification centre until you come back. It is withdrawn the moment you are back (taskbar, Alt-Tab, the toast itself, or restoring a minimized window), and none of the three options affect that — so a toast you never opened in the notification centre is not left in your way. A toast with Approve / Reject carries no auto-dismiss timer — it stays until you click a button, answer the request in the page, or a newer request replaces it; a desktop approval toast, which cannot render buttons, closes after 12 s and is likewise not withdrawn while you are away. Both are withdrawn when you come back to the page.
139
+ - **"Keep while away"**: while you are at the page a plain toast closes itself after a few seconds; one that arrived while you were away stays in the notification centre until you come back. It is withdrawn the moment you are back (taskbar, Alt-Tab, the toast itself, or restoring a minimized window), and none of the three options affect that — so a toast you never opened in the notification centre is not left in your way. **With "keep alerts when you come back" on, the return no longer withdraws them either** — they wait until you dismiss them or click Close, and stay on screen under a persistent OS notification style. A Web toast with Approve / Reject carries no auto-dismiss timer — it stays until you click a button, answer the request in the page, or a newer request replaces it; a macOS desktop approval toast, which cannot render buttons, and a Windows desktop native approval toast both close after 12 s and are likewise not withdrawn while you are away. Host-posted native notifications (the Windows native toast, macOS Notification Centre) are tracked by the same ledger: not withdrawn while you are away, withdrawn when you return unless that switch is on, and covered by the auto-dismiss choice as well. All of them are withdrawn when you come back to the page (and kept when that switch is on).
138
140
  - **Fallback for a toast click**: on Desktop a window that will not raise leaves only the conversation switch, with the reason in `debug().raiseLast`; turn this switch off and a click does nothing.
139
141
 
140
142
  </details>
@@ -143,18 +145,21 @@ Open **Settings → Notify me**. The page lays out three blocks — how you get
143
145
 
144
146
  For the "this one runs automated work in the background — I do not need to hear about it tonight" case: silence one row and nothing else.
145
147
 
146
- - **Mute**: hover a session in the sidebar, a bell appears on the right; click it to mute that conversation (the button reads "mute alerts for this session"), click again to resume.
148
+ - **Mute**: hover a session in the sidebar, a bell appears on the right; click it to mute that conversation (the button reads "mute alerts for this session"), click again to resume. You can also right-click the session and pick "Mute alerts for this session" — touch devices have no hover strip, so that menu row is their entry point.
147
149
  - **Mark**: a muted conversation shows a crossed bell before its title (announced as "alerts muted for this session").
150
+ - **The hover bell can be switched off**: the "Show the mute bell on hover" switch at the top of the "Muted sessions" card on the settings page defaults to on; off hides the bell from the hover strip, and unmuted conversations are muted from the right-click menu instead. A muted conversation keeps its bell — it shows the state and unmutes in one click; the crossed bell before the title is unaffected.
148
151
  - **Scope**: "needs you", "reply finished", sound, the tab-title mark and external forwarding are all silenced for that conversation; every other conversation is untouched. The test buttons under "Try it" still fire — they exist to check the channel on the spot.
149
152
  - **Persistence**: the list lives in local storage, so it survives reloads and restarts; a hand-edited list is pruned instead of breaking the page.
150
153
  - **After the tab closes**: the list travels with the heartbeat, so the host-side fallback honours it too — otherwise closing the page would start the very alerts you turned off.
151
154
 
152
- The settings page has a "Muted sessions" card under "When to alert" with the current count and an "Unmute all" button.
155
+ The settings page has a "Muted sessions" card under "When to alert" with the current count, the hover-bell switch at the top of the card, and an "Unmute all" button.
153
156
 
154
157
  <details>
155
158
  <summary>Edge cases</summary>
156
159
 
157
160
  - The mark lives in the host's `sidebar.session.row.leading` slot, and the host puts its status dots there while a session is running, so the mark is not rendered then — a running background job shows no crossed bell until it stops. The mute itself is unaffected.
161
+ - The right-click menu row lives in the host's legacy `sidebar.workspaces.session.menu.item` slot; a host that does not declare that slot only loses that one row — the hover bell, the settings page and the mute itself keep working.
162
+ - With the hover bell off, an unmuted conversation has no mute control in the row at all, so checking or clearing the mute goes through the right-click menu; a muted conversation keeps its pressed-state bell at the end of the row.
158
163
  - Muting keys on the session id: renaming or moving the directory changes nothing, and a deleted session is harmless in the list (capped at 200 ids; "Unmute all" clears it).
159
164
  - Muting does not change the "reply finished" policy or "current conversation stays quiet"; when both apply, the mute wins.
160
165
 
@@ -181,7 +186,7 @@ Off by default. Supports Discord Webhook / Bark / Gotify / Feishu group bots / S
181
186
  <details>
182
187
  <summary>Target URLs, forwarding switches, test messages, and the failure log</summary>
183
188
 
184
- - **External notifications** (default off): forward each alert to your own push endpoints as well, so it reaches you away from the machine; any number of targets, each of which can be enabled or disabled on its own. "Forward 'needs you'" and "Forward 'reply finished'" switch independently; **Send test notification** sends one test message to every target (not limited by those two switches, and never pretending to be a real alert). Forwarding follows exactly the same trigger rules as local alerts ("stay quiet for the conversation on screen" and friends apply to it too); the alert text is sent as-is to the addresses you fill in, so **only use endpoints you trust**;
189
+ - **External notifications** (default off): forward each alert to your own push endpoints as well, so it reaches you away from the machine; any number of targets, each of which can be enabled or disabled on its own. "Forward 'needs you'" and "Forward 'reply finished'" switch independently; **Send test notification** sends one test message to every target (not limited by those two switches, and never pretending to be a real alert). Forwarding follows exactly the same trigger rules as local alerts ("stay quiet for the conversation on screen" and friends apply to it too); with the master switch off the **host-side fallback after a closed page stops too** (the switches ride the heartbeat — see "after the page closes"), so there is no "the page is gone but it still pushes"; the alert text is sent as-is to the addresses you fill in, so **only use endpoints you trust**;
185
190
  - **What each target takes**: Discord — the webhook URL; Bark — `https://api.day.app/<device key>`; Gotify — `https://<server>/message?token=<app token>`; Feishu — the group-bot webhook plus an optional verification secret; ServerChan — the full `…/send/<SendKey>.send` URL; WxPusher — the appToken and the receiver UID; a custom endpoint receives one POST of JSON: `{source, event, title, body, text, sessionId, time}`;
186
191
  - **Reliable delivery**: failures that look transient (network error, 5xx, 429) are retried after 2 s and 6 s; anything else stops at once. Switching forwarding off or deleting a target cancels a retry that is already on a timer — it is not counted as a failure and never reaches the failure log. A delivery that still fails is recorded in the failure log (10 entries at most — title and body snippet plus host only, never the full endpoint), which the settings page shows and can clear;
187
192
  - **Service codes and "unverified"**: a 2xx from Feishu / ServerChan / WxPusher also carries a service code (`0` for Feishu and ServerChan, `1000` for WxPusher); a wrong code is recorded as a failure with the service's own message, and a 2xx whose body is not that service's JSON (empty, or a proxy/WAF HTML page) is "sent but unverified" rather than a success;
@@ -199,7 +204,7 @@ Both live in the host process (`lib/host-fallback.js`, `lib/relay.js`, optional
199
204
  <details>
200
205
  <summary>Host-side fallback: the host keeps pushing after the page closes</summary>
201
206
 
202
- With no page open the browser half does not run, and that is where alerts stop. The host-side fallback subscribes to the host's session event feed (`session/event`) and pushes the same two alerts to your gateway on its own once the page is closed.
207
+ With no page open the browser half does not run, and that is where alerts stop. The host-side fallback subscribes to the host's session event feed (`session/event`) and pushes the same two alerts to your gateway on its own once the page is closed. It shares the page's switches: the heartbeat reports `external: {enabled, attention, done}`, so turning off the 「Forward to external targets」 master switch (or just 「needs you」 / 「reply finished」) silences the fallback the same way — otherwise switching the master switch off and closing the tab would still deliver that last external alert.
203
208
 
204
209
  An override example for the profile (`~/.dsh/profiles/<profile>/cordis.patch.yml`). **`config` is replaced wholesale, not deep-merged**: a patch row naming the same `id` assigns the whole `config`, which is why the example spells out all three blocks — an omitted key falls back to the plugin's own defaults (the same values as the bundled YAML), but a `gateway.target` wiped along with it does not come back on its own.
205
210
 
@@ -244,7 +249,7 @@ Key by key (defaults in parentheses):
244
249
 
245
250
  **The credentials file** is a mode-0600 JSON file readable by the host user, holding `{"user": "...", "password": "..."}` (sent as HTTP Basic) or `{"authorization": "Bearer ..."}` (sent verbatim; a bare token gets `Bearer ` prepended). It must not go into the patch layer — that layer is world-readable and lands in the profile directory. Leaving the key empty sends the request without an authentication header: plenty of webhook endpoints never ask for one, and treating a missing credentials file as an error would make every alert fail; only a path that is configured and unreadable counts as credentials-unavailable. When the gateway answers 401 / 403 the host drops the cached credential, re-reads the file and retries exactly once, so a rotated password needs no host restart.
246
251
 
247
- **Deduplication rides on one page online lease**: on load the page probes `GET /__dsh-notify-me/host-bridge` once (and again every 60 s; no probe while the page is hidden, one catch-up probe when it becomes visible), and it only starts heartbeating when the reply says `hostFallback.enabled === true` — the body is `{alive, language, muted}` (`muted` being the ids of the sessions the user silenced), the interval is `leaseMs/3` clamped to 5–20 s, and `pagehide` releases immediately with one `{alive:false}` (sent with `keepalive`). A fresh host-side lease means no fallback push (the page is delivering), while an expired lease or an `alive:false` hands over, waiting at most `pageLeaseMs`. The heartbeat carries the language and the mute list, not the page's push switches: the rule is simply that the host takes over while no page holds the lease, and the page's own visibility and idle heuristics are invisible to the host — honouring half of them would produce a rule nobody can predict. The mute list is the exception: it is a settled state the user picked row by row and the page wrote to its config, so the host following it is the page speaking. The language it brings is what keeps an English page from getting Chinese host alerts, and it applies whenever `language: 'auto'`. The list is trimmed by bytes on the wire (an 8 KiB budget, at most 200 ids): a session past the cut is still silenced locally, it is just no longer covered by the fallback. `pageLeaseMs: 0` turns coordination off so the host always pushes — the page then gets everything twice while it is open, so use it for debugging only.
252
+ **Deduplication rides on one page online lease**: on load the page probes `GET /__dsh-notify-me/host-bridge` once (and again every 60 s; no probe while the page is hidden, one catch-up probe when it becomes visible), and it only starts heartbeating when the reply says `hostFallback.enabled === true` — the body is `{alive, language, muted, external}` (`muted` being the ids of the sessions the user silenced, `external` the `{enabled, attention, done}` forward switches), the interval is `leaseMs/3` clamped to 5–20 s, a change to the mute list or to any forward switch beats immediately instead of waiting for that interval, and `pagehide` releases immediately with one `{alive:false, language, external}` (sent with `keepalive`). A fresh host-side lease means no fallback push (the page is delivering), while an expired lease or an `alive:false` hands over, waiting at most `pageLeaseMs`. The heartbeat carries the language, the mute list and the forward switches, because all three are settled state the user wrote into the config, so the host following them is the page speaking: the mute list keeps silenced sessions silent, and `external.enabled: false` (the 「Forward to external targets」 master switch off) stops the host fallback as well — otherwise turning the switch off and closing the tab would still deliver the external alert that was just switched off; `attention` / `done` gate 「needs you」 and 「reply finished」 respectively. What still stays out is the page's visibility and idle heuristics: the host cannot see them, and honouring half of them would produce a rule nobody can predict. The language it brings is what keeps an English page from getting Chinese host alerts, and it applies whenever `language: 'auto'`. `external` is only honoured when all three fields are booleans; an incomplete report keeps the previous answer, and a page that has never reported at all leaves the host on `hostFallback.enabled`. The list is trimmed by bytes on the wire (an 8 KiB budget, at most 200 ids): a session past the cut is still silenced locally, it is just no longer covered by the fallback. `pageLeaseMs: 0` turns coordination off so the host always pushes — the page then gets everything twice while it is open, so use it for debugging only.
248
253
 
249
254
  **The two route contracts**: the probe the page calls, `GET /__dsh-notify-me/host-bridge`, answers `{ok, version, features, hostFallback:{enabled, leaseMs}, relay:{enabled, path, upstreamHost, upstreamPath}, language, page:{alive, ageMs}}` (`upstreamHost` / `upstreamPath` name the gateway the host forwards to, present only while the relay is enabled; the credential is never published); it is only registered while `hostFallback.enabled` or `relay.enabled` is true, so on a stock install it is a 404 and the page reads that as "off" rather than as a fault. The heartbeat `POST` requires the intent header `x-dsh-notify-me-page: bridge` (missing header → `403`), answers `400` to bad JSON and `413` to a body over 16 KiB, and `200 {ok, leaseUntil}` on success.
250
255
 
@@ -286,7 +291,7 @@ Credentials stay in the host: the page cannot read them, and they are never echo
286
291
 
287
292
  #### Runtime & diagnostics
288
293
 
289
- The last block inside Advanced. The page protocol is detected automatically to tell Web from Desktop (DSH Desktop, `dsh-app://`); override it by hand if detection is wrong — on Windows a toast click goes through the host route for native raising, on macOS / Linux through the `dsh://open` deep link (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)), and it carries no quick-decision buttons, while Web uses `window.focus()` plus the Service Worker bridge. When the manual override disagrees with detection the page says so.
294
+ The last block inside Advanced. The page protocol is detected automatically to tell Web from Desktop (DSH Desktop, `dsh-app://`); override it by hand if detection is wrong — on Windows a toast click goes through the host route for native raising, on macOS / Linux through the `dsh://open` deep link (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)), and the raise path itself carries no quick-decision buttons — those come from the Service Worker bridge on Web and from the host-posted native toast on Windows Desktop. When the manual override disagrees with detection the page says so.
290
295
 
291
296
  <details>
292
297
  <summary>Alert language, Desktop window raising, and reset</summary>
@@ -301,7 +306,7 @@ The last block inside Advanced. The page protocol is detected automatically to t
301
306
 
302
307
  | Channel | What it does |
303
308
  | --- | --- |
304
- | System notification | Through the browser into the Windows / macOS / Linux notification centre; clicking it returns to the conversation it came from. Web can carry Approve / Reject |
309
+ | System notification | Through the browser into the Windows / macOS / Linux notification centre; clicking it returns to the conversation it came from. On macOS Desktop the host spawns `DSH Notify.app` to post it (see [How macOS Desktop raises system notifications](#how-macos-desktop-raises-system-notifications)); on Windows Desktop the host posts a native approval toast that carries Approve / Reject (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)). Web can carry Approve / Reject too |
305
310
  | Sound | WebAudio cue by default, with different patterns for "needs you" and "done"; swap in a custom audio file, or hand the sound over to the system notification sound |
306
311
  | Tab title | `🔔 Action needed · …` / `✅ Reply finished · …`, following the alert language; gone once you open that session, and both markers can be up at the same time |
307
312
  | External push (optional, default off) | Forwards the same alert to Discord / Bark / Gotify / Feishu / ServerChan / WxPusher / a custom webhook |
@@ -312,7 +317,7 @@ This is primarily a **browser-layer** plugin: local toasts, sound and the title
312
317
 
313
318
  ## Compatibility
314
319
 
315
- Every release from `0.1.1-rc.2` through `0.2.2-alpha.2` was tested to actually activate (the criteria: the plugin entry lands in the boot page's `__DSH_BOOT__`, its inject dependencies resolve, `/plugins/??dsh-notify-me/client.js` serves a build containing the new code, and the "Notify me" section appears in Settings). Per-release records, the host-generation shape differences and the two traps that fail silently are in **[docs/compatibility.en.md](docs/compatibility.en.md)**.
320
+ Every release from `0.1.1-rc.2` through `0.2.2-rc.1` was tested to actually activate, including the recent desktop build `0.2.2-rc.1` (the criteria: the plugin entry lands in the boot page's `__DSH_BOOT__`, its inject dependencies resolve, `/plugins/??dsh-notify-me/client.js` serves a build containing the new code, and the "Notify me" section appears in Settings). Per-release records, the host-generation shape differences and the two traps that fail silently are in **[docs/compatibility.en.md](docs/compatibility.en.md)**.
316
321
 
317
322
  ## Advanced console configuration
318
323
 
@@ -338,12 +343,12 @@ The reminder core still has zero third-party runtime dependencies and is fully s
338
343
 
339
344
  ### Quick decisions, and how they reach the agent
340
345
 
341
- Notifications with Approve / Reject buttons can only be raised by a Service Worker (passing `actions` to `new Notification()` throws a `TypeError` outright), so the same bundle file is registered a second time as a worker whose only job is relaying which button was clicked back to the page. **The decision still happens in the page**, through the same `PendingApproval.answer('allowed-once' | 'rejected')` the approval panel uses for Allow once / Reject — so "Approve" is exactly "Allow once" and releases nothing extra.
346
+ On Web, notifications with Approve / Reject buttons can only be raised by a Service Worker (passing `actions` to `new Notification()` throws a `TypeError` outright), so the same bundle file is registered a second time as a worker whose only job is relaying which button was clicked back to the page; on Windows Desktop the host posts a native toast with the same two buttons instead. **The decision still happens in the page** either way, through the same `PendingApproval.answer('allowed-once' | 'rejected')` the approval panel uses for Allow once / Reject — so "Approve" is exactly "Allow once" and releases nothing extra.
342
347
 
343
348
  <details>
344
349
  <summary>Button-toast bookkeeping and window raising</summary>
345
350
 
346
- Each button toast is booked against its interaction key, and one toast claims only one wait; once the request has been answered in the page, or replaced by a newer request, clicking the leftover buttons decides nothing and just closes it quietly. Button toasts carry no auto-dismiss timer — they stay until you click or answer; plain toasts close after 5 s, and a desktop approval toast without buttons after 12 s. With "never close" selected neither kind closes on the timer; all three options cover that timer only, so anything still up is withdrawn once you are back at the page. If you miss the click, the approval in the conversation is still waiting for you.
351
+ Each button toast is booked against its interaction key, and one toast claims only one wait; once the request has been answered in the page, or replaced by a newer request, clicking the leftover buttons decides nothing and just closes it quietly. Button toasts carry no auto-dismiss timer — they stay until you click or answer; plain toasts close after 5 s, and a desktop approval toast without buttons after 12 s. With "never close" selected neither kind closes on the timer; all three options cover that timer only, so anything still up is withdrawn once you are back at the page (not when "keep alerts when you come back" is on). If you miss the click, the approval in the conversation is still waiting for you.
347
352
 
348
353
  The "raise a window and switch its conversation" part of a body click is scheduled on the worker half as well: `client.focus()` raises exactly one window (a visible one first) and routes the conversation switch to that window alone, so several DSH tabs never fight over focus or all switch at once.
349
354
 
@@ -369,6 +374,33 @@ That header is only a "this came from the page" marker, not the defence — a DN
369
374
  The cases where it will not raise are the same ones listed under [Known limitations](#known-limitations) (elevated window, another virtual desktop, a foreground repeatedly stolen, a window hidden to the tray with `SW_HIDE`); they all answer `202` truthfully and the conversation switch still happens.
370
375
 
371
376
  </details>
377
+ ### How macOS Desktop raises system notifications
378
+
379
+ On macOS Desktop (`dsh-app://app`) the page's own `new Notification()` never reaches the Notification Centre — nothing is shown and nothing throws (`Notification.permission` still reads `granted`). The plugin takes the host path there instead: the page POSTs `/__dsh-notify-me/mac-notify`, the host (`lib/mac-notify.js`) spawns the helper app in `macos/`, and that helper posts a real `UNUserNotificationCenter` notification.
380
+
381
+ - **One-time setup**: `bash macos/build.sh` builds `macos/DSH Notify.app` (needs Xcode Command Line Tools, a few seconds). The bundle is `.gitignore`d, so it is in neither the repository nor the npm package. Allow it under System Settings → Notifications → DSH Notify the first time one arrives.
382
+ - **Which path is used is automatic**: the host registers the route only when all three hold — macOS, the desktop shell (the Electron binary), and a built helper. Otherwise the `GET` probe reports `enabled: false` and the page keeps its own notification, exactly as before this change. `dsh web` in a browser never reaches the route.
383
+ - **Clicking returns to that conversation**: the helper writes the session id to `dsh-notify-me-click.json` in the temp directory and opens `dsh://open` to raise the window; the next time the page regains focus it `GET`s that id once, switches to the conversation and clears it, so nothing jumps twice. With `autoFocus` off the window is raised but the conversation is left alone.
384
+ - **Sound**: the "system notification sound" mode hands the sound to macOS; the synthesized modes stay in the page, so the two never stack.
385
+ - **Still no Approve / Reject buttons**: notification actions require registered categories, and the helper never touches approval state — decisions stay in the conversation.
386
+ - **Turning it off**: add `macNotify: { enabled: false }` to the `notify-me` entry in the profile's patch layer, or delete `macos/DSH Notify.app` and the probe falls back to `enabled: false`.
387
+
388
+ Like the window-raise route, this one registers exactly one exact path and refuses everything else: anything but GET / POST is `405` (including the preflight `OPTIONS`, which never gets a CORS header), a non-loopback peer or an unlisted `Host` / `Origin` is `403`, a POST without the `x-dsh-notify-me-mac: notify` header is `403`, a missing helper is `501`, and a body that is not a notification is `400`. The reply carries no system information, only the helper's exit status.
389
+
390
+ ### How Windows Desktop raises buttoned notifications
391
+
392
+ The page's own `new Notification()` is not refused on Windows Desktop, but it cannot carry buttons: Electron's renderer hands the platform only title / body / tag / icon / silent and drops the `actions` array entirely (`DisplayNotification()` in `shell/browser/notifications/platform_notification_service.cc`); and a `dsh-app://` page cannot register a Service Worker, while only a Service Worker can draw button notifications. The plugin therefore posts approval alerts through the host as native toasts.
393
+
394
+ - **Who posts it**: the host half (`lib/index.js`) registers `POST /__dsh-notify-me/win-toast` and runs one `powershell.exe` with `lib/win-toast.ps1`, which sends the toast through the WinRT `ToastNotificationManager` under the "DeepSeek Harness" AUMID — the same notification stack DSH's own notifications use, so it follows the same system notification settings.
395
+ - **How the buttons decide**: the toast's two buttons use `activationType="protocol"` and point at `dsh-notify-me://approve?token=…` / reject. Clicking one invokes the handler registered for that protocol (a VBS that writes the action to a file and opens `dsh://open`); the host hands the action back on the page's next probe, and the page still goes through the same `decidePending()` the approval panel uses — "Approve" is "Allow once" and releases nothing extra.
396
+ - **Registration**: the first buttoned toast registers that handler under `HKCU\Software\Classes\dsh-notify-me` (current-user, no admin rights needed) and books the toast into `ToastNotificationManager.History` by tag. Tokens are single-use and valid for 3 minutes; an action file is deleted once taken.
397
+ - **When it does not post**: outside the Windows desktop host, with `winToast.enabled: false`, or without `powershell.exe`, the route reports `enabled: false` (`501`) and the page keeps its own buttonless notification — the same behaviour as before this change.
398
+ - **Turning it off**: add `winToast: { enabled: false }` to the `notify-me` entry in the profile's patch layer; approval alerts go back to the page's own notification, without buttons.
399
+ - **Auto-dismiss and withdrawal**: native toasts are tracked by `trackToast()`: a plain toast closes after 5 s, a buttoned approval after 12 s ("always close" / "never close" still apply), and they are withdrawn when you come back to the page unless "keep alerts when you come back" is on.
400
+
401
+ Like the other routes, this one registers exactly one exact path and refuses everything else: anything but GET / POST is `405`, a non-loopback peer or an unlisted `Host` / `Origin` is `403`, a POST without the `x-dsh-notify-me-win: toast` header is `403`, and a body that is not a valid notification is `400`. The reply reports the delivery status only, never system information.
402
+
403
+
372
404
 
373
405
  ## Known limitations
374
406
 
@@ -381,11 +413,11 @@ The cases where it will not raise are the same ones listed under [Known limitati
381
413
 
382
414
  **Platform differences**
383
415
 
384
- - Quick-decision buttons need a Service Worker: `http://127.0.0.1` and `https` work, `http://192.168.x.x`-style LAN addresses do not; **the Desktop (`dsh-app://`) is tested and cannot register a Service Worker** (the host does not grant the `allowServiceWorkers` privilege), so approval toasts fall back to their buttonless form. When the host renders no notification buttons, the `bridge` field of `debug()` explains why, and nothing else is affected.
416
+ - Quick-decision buttons need a Service Worker: `http://127.0.0.1` and `https` work, `http://192.168.x.x`-style LAN addresses do not; **the Desktop (`dsh-app://`) is tested and cannot register a Service Worker** (the host does not grant the `allowServiceWorkers` privilege): on Windows Desktop approval alerts are posted by the host as native toasts with real buttons (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)), while macOS Desktop falls back to a buttonless notification. When the host renders no notification buttons, the `bridge` field of `debug()` explains why, and nothing else is affected.
385
417
  - Windows caps a toast tag at 64 characters, and Chromium hands the platform the whole `n#<origin>#<tag>` string — the desktop page's `dsh-app://app` alone takes 16. The plugin sizes each tag against the current `location.origin` and, when it does not fit, keeps a readable prefix and swaps the tail for a short hash, so a tag seen through `debug()` may be shortened; if the platform still refuses one, its message lands in `debug().lastToastReject` and the settings test button reports it instead of claiming the toast was sent.
386
418
  - On Desktop (Windows) a toast click can still fail to raise the window: when the target window is owned by a higher integrity level (elevated / UAC), sits on another virtual desktop, has its foreground repeatedly stolen by another process, or is hidden to the tray with `SW_HIDE`, the host script answers `FOCUSED=0` and the route answers `202`, with the conversation switch intact (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)).
387
419
  - Desktop (macOS / Linux) toast clicks rely on the `dsh://open` deep link: when the system has no `x-scheme-handler/dsh` registration, or the shell has no `second-instance` / `open-url` handling, the window will not raise. Measured to work on Linux; macOS is untested.
388
- - macOS: alerts, sound, the title marker and toast-click navigation carry no platform assumptions and work as usual; but DSH Desktop (Electron) system notifications require the app to be signed — an unsigned build simply emits no notification — and whether the official macOS build meets that precondition is untested; notification button rendering on the macOS desktop host is likewise untested (the Windows desktop host is tested and renders none).
420
+ - macOS: alerts, sound, the title marker and toast-click navigation carry no platform assumptions and work as usual; but DSH Desktop (Electron) system notifications require the app to be signed — an unsigned build simply emits no notification — and whether the official macOS build meets that precondition is untested; notification button rendering on the macOS desktop host is likewise untested (the Windows desktop host now posts its approval toasts as native toasts, which do render buttons).
389
421
 
390
422
  **Alert content and timing**
391
423
 
@@ -408,7 +440,7 @@ The cases where it will not raise are the same ones listed under [Known limitati
408
440
  ```sh
409
441
  node --check lib/client.js
410
442
  node --check lib/index.js
411
- npm test # smoke-test (state machine) + host-route-test (host half) + page-bridge-test + host-fallback-test + relay-route-test + cordis-host-test
443
+ npm test # smoke-test (state machine) + host-route-test (host half) + page-bridge-test + host-fallback-test + relay-route-test + cordis-host-test + mac-notify-test + win-toast-test
412
444
  npm pack --dry-run # preview the published tarball
413
445
  ```
414
446
 
@@ -416,6 +448,10 @@ npm pack --dry-run # preview the published tarball
416
448
 
417
449
  The three new suites also ship their own fake `ctx`, need no local DSH and touch no network: `smoke/page-bridge-test.mjs` runs the page-bridge route — status shape, heartbeat and release, missing intent header `403`, cross-origin `403`, bad JSON `400`, oversized `413`, the `allowedOrigins`-derived `Host` (a simulated tunnel) being let through, and path collisions; `smoke/host-fallback-test.mjs` runs the host fallback — approval dedupe, `turn/end` throttling, subagent skip, no push on a fresh lease, a push after the lease expires, an immediate push after `alive:false`, language following the heartbeat, credentials re-read after a 401, and the health probe; `smoke/relay-route-test.mjs` runs the relay — the `GET` probe, `405`, cross-origin `403`, `413`, `400`, `503`, the `200` / `502` mapping and "retry exactly once on a 401".
418
450
 
451
+ `smoke/mac-notify-test.mjs` runs the macOS notification route: registered only on the macOS desktop host, the probe, the `405` / `403` / `501` / `400` refusals, the arguments handed to the helper, and the click hand-off being taken exactly once. It fakes the platform and Electron version, needs no real helper, and runs on every platform.
452
+
453
+ `smoke/win-toast-test.mjs` runs the Windows native-toast route: the Windows desktop gate, the `GET` probe, the `405` / `403` / `501` / `400` refusals, the approval payload and its base64 pass-through, the three `HKCU\Software\Classes\dsh-notify-me` registration commands, approve / reject / open actions being claimed once, token expiry, and `{remove}` withdrawal. It drives `reg.exe` / `powershell.exe` through a fake `spawn`, so it needs no real Windows desktop host and runs on every platform.
454
+
419
455
  When `lib/focus-window.ps1` changes (Windows only), also run it by hand:
420
456
 
421
457
  ```powershell
@@ -439,8 +475,12 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # the last line
439
475
  | <a href="https://github.com/Donald-Yip"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/Donald-Yip.png" width="40" height="40" alt="@Donald-Yip"></a> | [#18](https://github.com/chromoany/dsh-notify-me/issues/18): the report that a Windows notification tag over the 64-character cap made the platform silently reject the approval test toast |
440
476
  | <a href="https://github.com/dunxuan"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/dunxuan.png" width="40" height="40" alt="@dunxuan"></a> | [#20](https://github.com/chromoany/dsh-notify-me/issues/20): the report that alerts for the open session showed a placeholder instead of the session title |
441
477
  | <a href="https://github.com/unnamed42"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/unnamed42.png" width="40" height="40" alt="@unnamed42"></a> | [#21](https://github.com/chromoany/dsh-notify-me/issues/21) / [#22](https://github.com/chromoany/dsh-notify-me/pull/22): the Linux `dsh://open` raise-path report and patch, which brought the deep link back on macOS / Linux in 1.14.4 |
442
- | <a href="https://github.com/LIEGU0317"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/LIEGU0317.png" width="40" height="40" alt="@LIEGU0317"></a> | [#24](https://github.com/chromoany/dsh-notify-me/issues/24) / [#25](https://github.com/chromoany/dsh-notify-me/pull/25): the host-side fallback push and same-origin relay modules (optional, off by default), with tests and docs |
478
+ | <a href="https://github.com/LIEGU0317"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/LIEGU0317.png" width="40" height="40" alt="@LIEGU0317"></a> | [#24](https://github.com/chromoany/dsh-notify-me/issues/24) / [#25](https://github.com/chromoany/dsh-notify-me/pull/25): the host-side fallback push and same-origin relay modules (optional, off by default), with tests and docs; [#29](https://github.com/chromoany/dsh-notify-me/issues/29) / [#30](https://github.com/chromoany/dsh-notify-me/pull/30): the host fallback ignored the 「Forward to external targets」 switch (the heartbeat and pagehide now carry `external`), landing in 1.19.0 |
443
479
  | <a href="https://github.com/ekexium"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/ekexium.png" width="40" height="40" alt="@ekexium"></a> | [#23](https://github.com/chromoany/dsh-notify-me/issues/23): the per-conversation mute request (an on/off switch per session, persistence across restarts, a mark on the session row), supported since 1.16.0 |
480
+ | <a href="https://github.com/AomiRaku"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/AomiRaku.png" width="40" height="40" alt="@AomiRaku"></a> | [#26](https://github.com/chromoany/dsh-notify-me/issues/26): the report that the row's hover buttons were covering the title, asking for a switchable mute bell and a mute entry in the context menu — shipped in 1.18.0 |
481
+ | <a href="https://github.com/Matthew-Laplace"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/Matthew-Laplace.png" width="40" height="40" alt="@Matthew-Laplace"></a> | [#27](https://github.com/chromoany/dsh-notify-me/issues/27) / [#28](https://github.com/chromoany/dsh-notify-me/pull/28): the `keepOnReturn` proposal and minimal patch (keep alerts after coming back to the page), plus the ask for a single "alert in the foreground too" preset — supported since 1.19.0 |
482
+ | <a href="https://github.com/xty13114150041"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/xty13114150041.png" width="40" height="40" alt="@xty13114150041"></a> | [#31](https://github.com/chromoany/dsh-notify-me/issues/31) / [#32](https://github.com/chromoany/dsh-notify-me/pull/32): the macOS Desktop "notifications never arrive" investigation and the host-helper approach (`lib/mac-notify.js` + `macos/`) — supported since 1.19.0 |
483
+ | <a href="https://github.com/Inh-ui"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/Inh-ui.png" width="40" height="40" alt="@Inh-ui"></a> | [#33](https://github.com/chromoany/dsh-notify-me/issues/33): the report that Windows Desktop approval notifications carry no Approve / Reject buttons, with the source-level finding that Electron drops `actions` and Desktop cannot register a Service Worker — fixed in 1.19.0 |
444
484
 
445
485
  Attribution policy: external PRs are landed as maintainer commits — the original commit is not reused and no Co-authored-by trailer is added, so GitHub's contributors graph lists the maintainer only and contributors are credited above.
446
486