dsh-turn-ding 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# dsh-turn-ding
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 的「会话跑完了」提醒插件：**Windows 任务栏图标右上角显示未读数字徽标 + 可选提示音**，效果等同于 Codex 的完成提醒。
+
+> 结论先行：DSH 目前（0.2.1-alpha.2 / 桌面版 0.2.2-rc.1）**没有**这个功能。主进程不暴露任何 badge/托盘计数 IPC，官方插件目录里也没有相关插件。本插件补上这个缺口。
+
+---
+
+## 一、它做了什么
+
+| 能力 | 实现位置 | 说明 |
+| --- | --- | --- |
+| 数字徽标 | `lib/badge-server.ps1` | `ITaskbarList3.SetOverlayIcon` 把一张 32×32 的红底白字圆图贴到 DSH 任务栏按钮右上角 |
+| 提示音 | `lib/badge-server.ps1` | `System.Media.SoundPlayer` 播放指定 `.wav` |
+| 判定「完成」 | `lib/index.js` | 监听 `session/event`，只认 `turn/end` 且 `reason.kind === 'completed'` |
+| 每个会话完成都计数 | `lib/badge-server.ps1` | DSH 是一个窗口装多个会话，"窗口在前台"不等于"你正在看这个会话"，所以每次都加 1 |
+| 回到前台自动清零 | `lib/badge-server.ps1` | 500ms 轮询，检测到「后台→前台」的切换就清徽标；一直盯着屏幕时徽标约 10s 后自动淡出 |
+| 自愈 | `lib/badge-server.ps1` | 每 ~6s 重绘一次，Explorer 重启/窗口隐藏后徽标不会丢 |
+| 句柄重绑定 | `lib/badge-server.ps1` | 窗口句柄失效自动重新查找并补画 |
+
+`aborted` / `error` / `max-tokens` / `interrupted` / `forked` 这几种"中途结束"**不会**计数；子会话（subagent）默认也忽略。
+
+## 二、安装（给使用者）
+
+### 方式 A：插件页直接装（推荐，最简单）
+
+在 DSH 侧栏打开「插件」→「安装第三方插件 / 添加插件」，输入包名点安装：
+
+```
+dsh-turn-ding
+```
+
+桌面版需**完全退出** DSH 后再装/更新，装好重新打开。等价于命令行：
+
+```bash
+dsh plugin --profile desktop add dsh-turn-ding
+dsh plugin --profile web add dsh-turn-ding
+```
+
+> 终端里没有 `dsh` 的话，先在桌面版菜单选「管理 dsh 命令」。
+
+### 方式 B：在「发现」里浏览安装（0.2.2 实验功能）
+
+DSH `0.2.2` 及以上可在「插件 → 实验性插件」启用**自定义插件索引**（`0.2.1` 系列叫「自定义插件市场」），启用后插件页多出「已安装」「发现」两个标签。在「发现」里「管理索引源 / 添加索引源」填入本仓库的 `index.json` 地址，列表里点安装即可。索引只是省掉手输包名这一步，装的还是同一个 npm 包。
+
+```
+https://raw.githubusercontent.com/<你的GitHub用户名>/dsh-turn-ding/main/index.json
+```
+
+GitHub 直连不通时可用 jsDelivr CDN 镜像（可能比最新发布晚约 12 小时）：
+
+```
+https://cdn.jsdelivr.net/gh/<你的GitHub用户名>/dsh-turn-ding@main/index.json
+```
+
+### 方式 C：离线 / 本地目录
+
+```bash
+dsh plugin --profile desktop add "D:/path/to/dsh-turn-ding"
+# 或把 npm pack 出来的 tgz 当包名：
+dsh plugin --profile desktop add "file:D:/path/to/dsh-turn-ding-0.1.0.tgz"
+```
+
+### 本地开发时的安装记录（本机 desktop profile）
+
+本机是通过本地 `link:` 装进 desktop profile 的：
+
+```bash
+DSH="D:/Users/saiwa/AppData/Local/Programs/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd"
+"$DSH" plugin --profile desktop add "D:/projects/arron/DSH-Plugins/dsh-turn-ding"
+```
+
+注意：`plugin` 子命令必须在**桌面应用完全退出**时运行（它要改 profile 的 `package.json` 并跑 pnpm）。`--dump-config`、boot 这类子命令对 `desktop` profile 是被硬拒的（`profile "desktop" is managed exclusively by the Electron application`），`plugin` 子命令例外放行。
+
+装完的效果写在这两个文件里：
+
+- `C:\\Users\\saiwa\\.dsh\\profiles\\desktop\\package.json`
+  - `dependencies` 里加 `"dsh-turn-ding": "link:D:\\\\projects\\\\arron\\\\DSH-Plugins\\\\dsh-turn-ding"`
+  - `dsh.profile.bundles` 末尾加 `"dsh-turn-ding"`
+- `C:\\Users\\saiwa\\.dsh\\profiles\\desktop\\pnpm-lock.yaml` 里的 `dsh-turn-ding: version: link:...`
+
+回滚：把 `package.json.bak-turn-ding` 覆盖回去即可（同一目录下已备份）。
+
+## 三、配置
+
+在 `C:\\Users\\saiwa\\.dsh\\profiles\\desktop\\cordis.patch.yml` 里给这一行加 `config`：
+
+```yaml
+- id: turn-ding
+  name: 'dsh-turn-ding'
+  config:
+    sound: true
+    soundFile: 'C:\\Windows\\Media\\Windows Notify System Generic.wav'
+    badge: true
+    ignoreSubagents: true
+```
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `sound` | `true` | 是否播放提示音 |
+| `soundFile` | `C:\\Windows\\Media\\Windows Notify System Generic.wav` | 任意本地 `.wav` |
+| `badge` | `true` | 是否画数字徽标 |
+| `ignoreSubagents` | `true` | 是否忽略子会话的 turn 结束 |
+
+常用替代音效：`Windows Notify.wav`、`Windows Ding.wav`、`ding.wav`、`chimes.wav`、`Windows Notify Email.wav`，都在 `C:\\Windows\\Media\\`。
+
+## 四、为什么是这个架构
+
+排查过三条路，只有第三条通：
+
+1. **Electron 主进程通道** —— 不通。`apps/desktop/src/ipc.ts:8-34` 的 `DESKTOP_IPC` 白名单里没有 badge/tray/overlay/notification 任何一项；preload 只暴露 `browser / deviceInfo / keyboard / shortcuts / updates`，且仅 `dsh-app://app` origin 可用。已安装的 `app.asar` 里 `setBadgeCount` / `setOverlayIcon` 出现次数为 **0**。
+2. **渲染层 `navigator.setAppBadge()`** —— 理论可行（该 Electron 构建确实含 Chromium BadgeService），但无法在本机实机验证，且窗口隐藏到托盘时任务栏按钮消失、徽标也随之失效。
+3. **host 侧 Win32**（采用）—— host 是独立 Node 子进程（`host-process.ts:186-201`，`ELECTRON_RUN_AS_NODE=1`），拿不到 `BrowserWindow`，但**能按进程找到目标窗口的 HWND**，于是可以调 `ITaskbarList3.SetOverlayIcon`。这条路已用真实截图逐像素验证。
+
+`lib/index.js` 只负责「监听事件 + 通过 stdin 行协议驱动辅助进程」；所有 Win32/COM 调用都在 `lib/badge-server.ps1` 里。辅助进程常驻（不是每次完成都起一个），有 `ready` 握手和 pending 队列，启动失败会降级成「没有徽标」而不是报错。
+
+## 五、验证记录
+
+| 测试 | 命令 | 结果 |
+| --- | --- | --- |
+| host 半边逻辑 | `node test/host-harness.mjs` | 只注册 `session/event`；aborted/error/subagent 全部忽略；两次 completed 各触发一次；dispose 干净 |
+| 辅助进程协议 | `node test/server-proto.mjs` | `ready` → `ping/pong` → `set`/`notify`/`clear` → `bye`，exit 0 |
+| 端到端 | `node test/e2e-badge.mjs` | 真 ctx + 真 PowerShell + 真任务栏：idle → 1 次完成 → 2 次完成，徽标依次变 `1`、`2`；再灌 aborted/error/subagent 三个事件，**像素零变化** |
+| 自动清零 | `node test/autoclear.mjs` | 把目标指向当前前台进程，`set 4` 后 3.5s 内回 `autoclear` |
+| 前台也计数（回归） | `node test/focus-regression.mjs` | 窗口在前台时连发两次 `notify` → `count=1`、`count=2`，截图确认徽标「2」 |
+| 对照截图 | `node test/proof-badge.mjs` | clear 与 badge 两张任务栏截图 diff bbox = `(1781, 11, 1813, 42)`，正好 32px 宽的徽标区 |
+| 整 profile boot | `node test/verify-desktop-profile.mjs` | 用真实 desktop 配置克隆 boot，web 服务正常起来，唯一失败项是既有的 `experimental-inspector`（与本插件无关）；进程列表里抓到插件真正拉起了 `badge-server.ps1` |
+| 插件市场索引 | 用实装 `parseMarketIndex()` 校验 `index.json` | `VALID`，安装目标解析为 `dsh-turn-ding@0.1.0` |
+
+截图见 `test/e2e-2-two.png`（徽标「2」）、`test/proof-badge3.png`（徽标「3」）。
+
+## 六、发布（给维护者）
+
+本插件就是一个普通的 npm 包，`dsh.bundle.patch` 是「这是 DSH 插件」的唯一标记，`package.json` 里**没有** `private: true`。发布流程：
+
+```bash
+# 0. 首次：登录 npm（本机默认源是 npmmirror，publish 需显式指定官方源）
+npm login --registry=https://registry.npmjs.org/
+
+# 1. 改版本号、确认打包内容（files 白名单：lib/、cordis.patch.yml、README.md、LICENSE）
+npm version patch          # 0.1.0 → 0.1.1
+npm pack --dry-run
+
+# 2. 发布
+npm publish --registry=https://registry.npmjs.org/ --access public
+
+# 3. 同步刷新 index.json 里对应版本的 version / publishTimestamp（Unix 秒），
+#    让「发现」里出现新版本；改完用官方校验器复验一次。
+```
+
+`publishTimestamp` 用 `date +%s` 取当前 Unix 秒，必须落在 `[0, 10^11)`；`version` 必须是精确 SemVer。改完 `index.json` 后，用 `@deepseek-ai/dsh-plugin-market-index` 的 `parseMarketIndex(doc, indexUrl)` 校验，通过再推到 GitHub。
+
+`os: ["win32"]` 会阻止在非 Windows 机器上安装，避免用户装了却没有效果。`engines.dsh` 仅作声明（安装器实际只校验 `peerDependencies`，本包故意不写）。
+
+## 七、已知限制
+
+- **Windows only**。macOS/Linux 需要另一套实现（`app.dock.setBadge` 在 host 侧拿不到，得换方案）。`os: ["win32"]` 已经把这一点写进 manifest。
+- **需要重启 DSH** 才会加载（同名包换版本也要重启，host 会报 restart-required）。
+- **关闭到托盘时**任务栏按钮不存在，徽标自然看不见；重新显示窗口后会自愈重绘。
+- 依赖 `powershell.exe`。PowerShell 5.1 即可（本机已验证），不需要 `pwsh` 7。
+- 徽标是 **overlay 图标**，跟 Windows 通知中心里那个数字不是同一个东西——后者需要 Toast，本插件不做。
+
+## 八、文件
+
+```
+dsh-turn-ding/
+├── package.json          # dsh.bundle.patch 是"这是 DSH 插件"的唯一标记
+├── cordis.patch.yml      # - insert: [{ id: turn-ding, name: dsh-turn-ding }]
+├── index.json            # 插件市场「发现」用的格式 1 索引（发布后托管到可访问的 URL）
+├── LICENSE               # MIT
+├── README.md
+├── lib/
+│   ├── index.js          # host 半边：事件监听 + 辅助进程生命周期
+│   └── badge-server.ps1  # Win32 半边：COM overlay + 提示音 + 轮询维护
+└── test/                 # 上面那张表里的验证脚本与截图
+```

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-turn-ding: one row, no surface of its own.
+- insert:
+    - id: turn-ding
+      name: 'dsh-turn-ding'

package/index.json

@@ -0,0 +1,49 @@
+{
+  "format": 1,
+  "title": {
+    "en": "DSH Completion Reminders",
+    "zh": "DSH 完成提醒插件索引"
+  },
+  "description": {
+    "en": "Community plugin index for dsh-turn-ding — taskbar badge and completion chime for DeepSeek Harness.",
+    "zh": "dsh-turn-ding 的社区插件索引——为 DeepSeek Harness 提供任务栏数字徽标与完成提示音。"
+  },
+  "metadata": {
+    "labels": {
+      "windows-only": {
+        "title": { "en": "Windows only", "zh": "仅限 Windows" }
+      }
+    }
+  },
+  "plugins": [
+    {
+      "name": "dsh-turn-ding",
+      "title": {
+        "en": "Turn Ding — completion badge & chime",
+        "zh": "完成提示 · 任务栏徽标与提示音"
+      },
+      "description": {
+        "en": "Shows an unread number badge on the Windows taskbar icon and plays a chime whenever a DeepSeek Harness session finishes.",
+        "zh": "每当一个 DeepSeek Harness 会话完成，就在 Windows 任务栏图标右上角显示未读数字徽标，并播放提示音。"
+      },
+      "author": "Arron",
+      "metadata": {
+        "keywords": ["badge", "notification", "taskbar", "windows", "completion"],
+        "labels": ["windows-only"]
+      },
+      "versions": [
+        {
+          "version": "0.1.0",
+          "publishTimestamp": 1794631126,
+          "source": {
+            "type": "npm",
+            "registry": "https://registry.npmjs.org/"
+          },
+          "engines": {
+            "dsh": ">=0.2.1-alpha.2 <0.4.0"
+          }
+        }
+      ]
+    }
+  ]
+}

package/lib/badge-server.ps1

@@ -0,0 +1,243 @@
+param(
+  [Parameter(Mandatory = $true)][int]$TargetPid,
+  [string]$Sound = 'C:\Windows\Media\Windows Notify System Generic.wav',
+  [int]$ClearOnFocus = 1,
+  [int]$SoundEnabled = 1,
+  [int]$BadgeEnabled = 1
+)
+
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+Add-Type -ReferencedAssemblies System.Drawing -TypeDefinition @'
+using System;
+using System.Drawing;
+using System.Drawing.Drawing2D;
+using System.Runtime.InteropServices;
+
+namespace DshBadge {
+  [ComImport, Guid("56FDF344-FD6D-11d0-958A-006097C9A090")]
+  public class TaskbarListCoclass { }
+
+  [ComImport, Guid("ea1afb91-9e28-4b86-90e9-9e9f8a5eefaf"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface ITaskbarList3 {
+    void HrInit();
+    void AddTab(IntPtr hwnd);
+    void DeleteTab(IntPtr hwnd);
+    void ActivateTab(IntPtr hwnd);
+    void SetActiveAlt(IntPtr hwnd);
+    void MarkFullscreenWindow(IntPtr hwnd, bool fFullscreen);
+    void SetProgressValue(IntPtr hwnd, ulong completed, ulong total);
+    void SetProgressState(IntPtr hwnd, int flags);
+    void RegisterTab(IntPtr hwndTab, IntPtr hwndMdi);
+    void UnregisterTab(IntPtr hwndTab);
+    void SetTabOrder(IntPtr hwndTab, IntPtr hwndInsertBefore);
+    void SetTabActive(IntPtr hwndTab, IntPtr hwndMdi, uint reserved);
+    void ThumbBarAddButtons(IntPtr hwnd, uint cButtons, IntPtr pButtons);
+    void ThumbBarUpdateButtons(IntPtr hwnd, uint cButtons, IntPtr pButtons);
+    void ThumbBarSetImageList(IntPtr hwnd, IntPtr himl);
+    void SetOverlayIcon(IntPtr hwnd, IntPtr hIcon, [MarshalAs(UnmanagedType.LPWStr)] string description);
+    void SetThumbnailTooltip(IntPtr hwnd, [MarshalAs(UnmanagedType.LPWStr)] string tip);
+  }
+
+  public static class Api {
+    static ITaskbarList3 list;
+
+    static ITaskbarList3 List() {
+      if (list == null) {
+        object coclass = new TaskbarListCoclass();
+        list = (ITaskbarList3)coclass;
+        list.HrInit();
+      }
+      return list;
+    }
+
+    public static void Apply(long hwndValue, int count, string tip) {
+      IntPtr hwnd = new IntPtr(hwndValue);
+      if (count <= 0) {
+        List().SetOverlayIcon(hwnd, IntPtr.Zero, "");
+        return;
+      }
+      IntPtr hicon = Render(count);
+      try { List().SetOverlayIcon(hwnd, hicon, tip == null ? "" : tip); }
+      finally { DestroyIcon(hicon); }
+    }
+
+    // 32x32 ARGB: red disc, white rim, bold white numeral -- the shape Windows
+    // itself uses for unread counts on a taskbar button.
+    public static IntPtr Render(int count) {
+      int s = 32;
+      Bitmap bmp = new Bitmap(s, s, System.Drawing.Imaging.PixelFormat.Format32bppArgb);
+      using (Graphics g = Graphics.FromImage(bmp)) {
+        g.SmoothingMode = SmoothingMode.AntiAlias;
+        g.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAliasGridFit;
+        g.Clear(Color.Transparent);
+        float pad = s * 0.04f;
+        using (SolidBrush fill = new SolidBrush(Color.FromArgb(255, 209, 52, 56)))
+        using (Pen edge = new Pen(Color.FromArgb(255, 255, 255, 255), s * 0.06f)) {
+          g.FillEllipse(fill, pad, pad, s - 2 * pad, s - 2 * pad);
+          g.DrawEllipse(edge, pad, pad, s - 2 * pad, s - 2 * pad);
+        }
+        string text = count > 99 ? "99+" : count.ToString();
+        float em = s * (text.Length > 2 ? 0.40f : text.Length > 1 ? 0.52f : 0.68f);
+        using (Font f = new Font("Segoe UI", em, FontStyle.Bold, GraphicsUnit.Pixel)) {
+          StringFormat sf = new StringFormat();
+          sf.Alignment = StringAlignment.Center;
+          sf.LineAlignment = StringAlignment.Center;
+          g.DrawString(text, f, Brushes.White, new RectangleF(0, s * 0.02f, s, s), sf);
+        }
+      }
+      return bmp.GetHicon();
+    }
+
+    [DllImport("user32.dll")]
+    public static extern bool DestroyIcon(IntPtr hIcon);
+    [DllImport("user32.dll")]
+    public static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll")]
+    public static extern bool IsWindow(IntPtr hWnd);
+    [DllImport("user32.dll")]
+    public static extern bool IsIconic(IntPtr hWnd);
+    [DllImport("user32.dll")]
+    public static extern bool IsWindowVisible(IntPtr hWnd);
+  }
+}
+'@
+
+function Write-Line([string]$text) {
+  [Console]::Out.WriteLine($text)
+  [Console]::Out.Flush()
+}
+
+# The DSH window is owned by the Electron main process -- our parent process.
+# Fall back to any process carrying a DSH main window if that lookup fails.
+function Find-Window {
+  if ($TargetPid -gt 0) {
+    $p = Get-Process -Id $TargetPid -ErrorAction SilentlyContinue
+    if ($p -and $p.MainWindowHandle -ne [IntPtr]::Zero) { return $p.MainWindowHandle }
+  }
+  foreach ($n in @('DeepSeek Harness', 'DSH')) {
+    $c = Get-Process -Name $n -ErrorAction SilentlyContinue |
+      Where-Object { $_.MainWindowHandle -ne [IntPtr]::Zero } |
+      Sort-Object StartTime | Select-Object -First 1
+    if ($c) { return $c.MainWindowHandle }
+  }
+  return [IntPtr]::Zero
+}
+
+function Play-Ding {
+  if ($SoundEnabled -ne 1) { return }
+  if (-not (Test-Path -LiteralPath $Sound)) { return }
+  try {
+    $player = New-Object System.Media.SoundPlayer -ArgumentList $Sound
+    $player.Play()
+  } catch { }
+}
+
+function Show-Badge([int]$n) {
+  if ($BadgeEnabled -ne 1 -or $n -le 0) { return }
+  if ($target -eq [IntPtr]::Zero) { return }
+  $tip = if ($n -eq 1) { '1 个会话已完成' } else { "$n 个会话已完成" }
+  try { [DshBadge.Api]::Apply($target.ToInt64(), $n, $tip) } catch { }
+}
+
+$target = Find-Window
+$count = 0
+$ticks = 0
+$wasFocused = ($target -ne [IntPtr]::Zero) -and ([DshBadge.Api]::GetForegroundWindow() -eq $target)
+$focusedTicks = 0
+$reader = New-Object System.IO.StreamReader([Console]::OpenStandardInput(), (New-Object System.Text.UTF8Encoding($false)))
+Write-Line ("ready hwnd=" + $target.ToInt64() + " pid=" + $TargetPid)
+
+$task = $reader.ReadLineAsync()
+while ($true) {
+  $got = $task.AsyncWaitHandle.WaitOne(500)
+  if ($got) {
+    $line = $task.Result
+    if ($null -eq $line) { break }
+    $task = $reader.ReadLineAsync()
+    $line = $line.Trim()
+    if ($line.Length -eq 0) { continue }
+    $parts = $line.Split(' ', [StringSplitOptions]::RemoveEmptyEntries)
+    $cmd = $parts[0].ToLowerInvariant()
+    if ($cmd -eq 'quit') { break }
+
+    if ($target -eq [IntPtr]::Zero -or -not [DshBadge.Api]::IsWindow($target)) { $target = Find-Window }
+
+    switch ($cmd) {
+      'notify' {
+        # A turn finished. Always counted: DSH is one window shared by several
+        # chats, so "the window has focus" says nothing about whether the user is
+        # watching *this* chat. Clearing happens on regaining focus instead.
+        $count += 1
+        Show-Badge $count
+        Play-Ding
+        Write-Line ("notify count=" + $count)
+      }
+      'set' {
+        $n = 1
+        if ($parts.Length -gt 1) { [int]::TryParse($parts[1], [ref]$n) | Out-Null }
+        if ($n -le 0) { $n = 1 }
+        $count = $n
+        Show-Badge $count
+        Write-Line ("set " + $count)
+      }
+      'clear' {
+        $count = 0
+        if ($target -ne [IntPtr]::Zero) { try { [DshBadge.Api]::Apply($target.ToInt64(), 0, "") } catch { } }
+        Write-Line "clear"
+      }
+      'sound' {
+        Play-Ding
+        Write-Line "sound"
+      }
+      'ping' { Write-Line "pong" }
+      default { Write-Line ("unknown " + $cmd) }
+    }
+    continue
+  }
+
+  $ticks += 1
+  if ($target -eq [IntPtr]::Zero -or -not [DshBadge.Api]::IsWindow($target)) {
+    $old = $target
+    $target = Find-Window
+    if ($target -ne [IntPtr]::Zero) {
+      Write-Line ("rebind hwnd=" + $target.ToInt64())
+      Show-Badge $count
+    }
+    continue
+  }
+
+  if ($count -gt 0) {
+    # Clear on a background -> foreground transition (the usual "I came back"
+    # case), or let a badge shown while already focused fade after ~10s so it
+    # cannot stick to a window the user never left.
+    $focusedNow = ($ClearOnFocus -eq 1) -and ([DshBadge.Api]::GetForegroundWindow() -eq $target)
+    if ($focusedNow -and -not $wasFocused) {
+      $count = 0
+      $focusedTicks = 0
+      try { [DshBadge.Api]::Apply($target.ToInt64(), 0, "") } catch { }
+      Write-Line "autoclear"
+    } elseif ($focusedNow -and $focusedTicks -ge 20) {
+      $count = 0
+      $focusedTicks = 0
+      try { [DshBadge.Api]::Apply($target.ToInt64(), 0, "") } catch { }
+      Write-Line "autofade"
+    } else {
+      if ($focusedNow) { $focusedTicks += 1 } else { $focusedTicks = 0 }
+      if ($ticks % 12 -eq 0) {
+        # Heal after Explorer restarts or a hide/show cycle drops the overlay.
+        Show-Badge $count
+      }
+    }
+    $wasFocused = $focusedNow
+  } else {
+    $wasFocused = ($ClearOnFocus -eq 1) -and ([DshBadge.Api]::GetForegroundWindow() -eq $target)
+    $focusedTicks = 0
+  }
+}
+
+if ($count -gt 0 -and $target -ne [IntPtr]::Zero) {
+  try { [DshBadge.Api]::Apply($target.ToInt64(), 0, "") } catch { }
+}
+Write-Line "bye"

package/lib/index.js

@@ -0,0 +1,168 @@
+/**
+ * dsh-turn-ding — host half.
+ *
+ * Watches `session/event` for completed turns and drives a long-lived PowerShell
+ * helper that paints a numeric overlay badge on the DSH taskbar button through
+ * `ITaskbarList3.SetOverlayIcon`, optionally playing a sound.
+ *
+ * The overlay icon is the only channel Windows gives a non-Electron process for
+ * a dock badge: the desktop main process exposes no badge IPC to the renderer,
+ * and the host runs as a separate Node child process, so Win32 from the host is
+ * the right seam.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+export const name = 'dsh-turn-ding'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+const DEFAULTS = {
+  sound: true,
+  soundFile: 'C:\\Windows\\Media\\Windows Notify System Generic.wav',
+  badge: true,
+  ignoreSubagents: true,
+}
+
+const POWERSHELL = 'powershell.exe'
+
+class BadgeServer {
+  constructor(options, logger) {
+    this.options = options
+    this.logger = logger
+    this.child = null
+    this.count = 0
+    this.pending = []
+    this.ready = false
+    this.broken = false
+  }
+
+  /** Launch the helper; failures degrade to "no badge" rather than throwing. */
+  start() {
+    const script = join(here, 'badge-server.ps1')
+    if (!existsSync(script)) {
+      this.broken = true
+      this.logger.warn('dsh-turn-ding: badge-server.ps1 is missing, badge disabled')
+      return
+    }
+
+    let child
+    try {
+      child = spawn(
+        POWERSHELL,
+        ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', script,
+          '-TargetPid', String(process.ppid || 0),
+          '-Sound', this.options.soundFile,
+          '-SoundEnabled', this.options.sound ? '1' : '0',
+          '-BadgeEnabled', this.options.badge ? '1' : '0'],
+        { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true },
+      )
+    } catch (error) {
+      this.broken = true
+      this.logger.warn(`dsh-turn-ding: could not start the badge helper (${String(error)})`)
+      return
+    }
+
+    this.child = child
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => {
+      for (const raw of String(chunk).split(/\r?\n/)) {
+        const line = raw.trim()
+        if (!line) continue
+        if (line.startsWith('ready')) {
+          this.ready = true
+          for (const command of this.pending.splice(0)) this.write(command)
+          continue
+        }
+        // The helper owns the authoritative counter: it reports the number it
+        // just painted, and tells us when it clears the badge itself.
+        const counted = /^notify count=(\d+)$/.exec(line)
+        if (counted) {
+          this.count = Number(counted[1])
+          continue
+        }
+        if (line === 'autoclear' || line === 'autofade') this.count = 0
+      }
+    })
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk) => {
+      const text = String(chunk).trim()
+      if (text) this.logger.warn(`dsh-turn-ding: badge helper: ${text}`)
+    })
+    child.on('error', (error) => {
+      this.broken = true
+      this.logger.warn(`dsh-turn-ding: badge helper failed (${String(error)})`)
+    })
+    child.on('exit', (code) => {
+      this.child = null
+      this.ready = false
+      if (code !== 0 && code !== null) this.logger.warn(`dsh-turn-ding: badge helper exited with ${code}`)
+    })
+  }
+
+  write(command) {
+    if (!this.child || this.child.killed) return
+    if (!this.ready) {
+      this.pending.push(command)
+      return
+    }
+    try {
+      this.child.stdin.write(`${command}\n`)
+    } catch {
+      // Helper died mid-write; the next start() call recovers.
+    }
+  }
+
+  /**
+   * A turn finished. `notify` lets the helper decide whether the moment is
+   * badge-worthy: it only increments while the DSH window is in the background,
+   * so a turn that ends while the user is watching never leaves a stale number.
+   */
+  bump() {
+    if (this.broken) return
+    if (!this.child) this.start()
+    this.write('notify')
+  }
+
+  clear() {
+    this.count = 0
+    this.write('clear')
+  }
+
+  dispose() {
+    this.count = 0
+    if (!this.child) return
+    try {
+      this.child.stdin.write('quit\n')
+      this.child.stdin.end()
+    } catch { /* already gone */ }
+    const child = this.child
+    this.child = null
+    setTimeout(() => {
+      if (!child.killed) {
+        try { child.kill() } catch { /* already gone */ }
+      }
+    }, 1500).unref?.()
+  }
+}
+
+export function apply(ctx, config) {
+  const options = { ...DEFAULTS, ...(config && typeof config === 'object' ? config : {}) }
+  const logger = ctx.logger ?? console
+  const server = new BadgeServer(options, logger)
+
+  ctx.effect(() => {
+    server.start()
+    return () => server.dispose()
+  })
+
+  ctx.on('session/event', (session, event) => {
+    if (!event || event.type !== 'turn/end') return
+    const reason = event.data?.reason
+    if (!reason || reason.kind !== 'completed') return
+    if (options.ignoreSubagents && (session?.header?.origin === 'subagent' || (session?.header?.delegationDepth ?? 0) > 0)) return
+    server.bump()
+  })
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "dsh-turn-ding",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Windows taskbar unread badge and completion chime for DeepSeek Harness turns",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "index.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "badge",
+    "notification",
+    "windows",
+    "taskbar"
+  ],
+  "author": "Arron",
+  "license": "MIT",
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.1-alpha.2 <0.4.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "manifestVersion": 1
+  }
+}