pi-windows-notifier 0.2.0 → 0.3.0

package/README.md

@@ -2,11 +2,15 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md)
 
-Get a Windows notification when Pi needs your attention—or when it's finished responding. The extension shows a toast and plays a system sound for permission requests, structured questions, and completed, interrupted, or failed responses, even while you're looking at another window.
+**Built specifically for Windows. Zero dependencies. Security-first alert sound and notification plugin.**
+
+Get a Windows notification when Pi needs your attention—or when it's finished responding. Shows a toast and plays a system sound or your own WAV file for permission requests, structured questions, and completed responses, even while you're looking at another window.
 
 Notifications stay on your machine. They don't pull questions, commands, file paths, or Pi's replies from your session; you can set your own static notification text. The extension doesn't approve permissions or answer questions for you.
 
-[GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
+Uses Pi-provided APIs, Node.js built-ins, and the built-in Windows notification and sound APIs—no extra notification library or external audio player to install. The design avoids risky patterns present in many other similar plugins. See [Privacy and process safety](#privacy-and-process-safety) for the protections and their limits.
+
+[Pi package page](https://pi.dev/packages/pi-windows-notifier) · [GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
 
 ## Install
 
@@ -37,7 +41,7 @@ pi remove npm:pi-windows-notifier
 |---|---|---|
 | `permission` | Pi needs you to review a permission request | Exclamation |
 | `question` | A supported question tool is waiting for your answer | Exclamation |
-| `completed` | Pi has finished responding | Asterisk |
+| `completed` | Pi has finished responding | Hand |
 | `aborted` | The response was interrupted | Exclamation |
 | `failed` | The response ended in an error | Exclamation |
 
@@ -61,11 +65,13 @@ Some question packages also ring the terminal bell themselves. If you hear an ex
 
 ## Settings
 
-To change the defaults, create `~/.pi/agent/pi-windows-notifier/config.json`. On Windows, that's `.pi\agent\pi-windows-notifier\config.json` inside your user home folder. The extension doesn't create or edit this file, and it doesn't read project-level settings.
+To change the defaults, create `~/.pi/agent/extensions/pi-windows-notifier/config.json`. On Windows, that's `.pi\agent\extensions\pi-windows-notifier\config.json` inside your user home folder. The extension doesn't create or edit this file, and it doesn't read project-level settings.
+
+The new path takes priority. Only when it doesn't exist does the extension read the old `~/.pi/agent/pi-windows-notifier/config.json`; the two files aren't merged. An invalid or unreadable new file disables notifications instead of falling back. To move your settings, place your existing config at the new path and reload. The extension won't move or rewrite either file.
 
 ### Complete config
 
-This example includes every supported field and all five events. You can copy it as a starting point, but **you only need to keep the fields you want to change**, along with `schemaVersion: 2`. Each event overrides the shared message below, so the example behaves like the built-in defaults.
+This example includes the system-sound fields and all five events; file sounds are shown separately below. You can copy it as a starting point, but **you only need to keep the fields you want to change**, along with `schemaVersion: 2`. Each event overrides the shared message below, so the example behaves like the built-in defaults.
 
 ```json
 {
@@ -99,7 +105,7 @@ This example includes every supported field and all five events. You can copy it
     "completed": {
       "enabled": true,
       "toast": { "enabled": true, "title": "Pi", "message": "Response complete" },
-      "sound": { "enabled": true, "source": { "type": "system", "name": "Asterisk" } }
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Hand" } }
     },
     "aborted": {
       "enabled": true,
@@ -130,22 +136,50 @@ Settings are applied in this order: **built-in event defaults → shared `defaul
 | `toast.title` | Static notification title |
 | `toast.message` | Static notification message |
 | `sound.enabled` | Turns the sound on or off |
-| `sound.source.type` | Only `"system"` is supported |
-| `sound.source.name` | `Asterisk`, `Beep`, `Exclamation`, `Hand`, or `Question`; case-sensitive |
+| `sound.source.type` | `"system"` for Windows sound events, or `"file"` for a local WAV |
+| `sound.source.name` | Required for `"system"`: `Asterisk`, `Beep`, `Exclamation`, `Hand`, or `Question`; case-sensitive |
+| `sound.source.path` | Required for `"file"`: an absolute local WAV path, up to 1024 UTF-16 code units |
 
-The `toast` and `sound` fields can appear under either `defaults` or an individual event. **The complete example explicitly sets every event field, so changing `defaults` alone won't change those overrides.** Remove the corresponding event fields if you want them to inherit shared settings. When setting `sound.source`, include both `type` and `name`; it replaces the source as a whole.
+The `toast` and `sound` fields can appear under either `defaults` or an individual event. **The complete example explicitly sets every event field, so changing `defaults` alone won't change those overrides.** Remove the corresponding event fields if you want them to inherit shared settings. When setting `sound.source`, include `type` and either `name` (system) or `path` (file), never both; it replaces the source as a whole.
 
 - **Toast only**: set `sound.enabled` to `false` and `toast.enabled` to `true`.
 - **Sound only**: set `toast.enabled` to `false` and `sound.enabled` to `true`.
 - If both channels are off, no helper starts. Event settings can override shared channel switches, but can't override a disabled master or event switch.
 
-Without a config file, all events and channels are enabled, the title is Pi, and messages are in English. Completion uses Asterisk; the other events use Exclamation.
+Without a config file, all events and channels are enabled, the title is Pi, and messages are in English. Completion uses Hand; the other events use Exclamation.
 
 ### Text and sound limits
 
 Text is used exactly as written—there are no templates or substitutions from your session. Titles can contain up to 128 UTF-16 code units and messages up to 512; an emoji may count as two. Both must be nonblank, single-line strings without control characters or invalid XML characters. Your text appears in Windows notifications, so don't put secrets in it. It isn't shown by `status` or error messages.
 
-Sound names select **Windows system sound events**, not separate audio files bundled with the package. The sound you hear depends on your Windows sound scheme: different events can use the same sound, or have no sound assigned. You can review or change these mappings in the Windows Sound settings; changes also affect other apps using those events. Custom sound files aren't supported.
+Sound names select **Windows system sound events**, not separate audio files bundled with the package. The sound you hear depends on your Windows sound scheme: different events can use the same sound, or have no sound assigned. You can review or change these mappings in the Windows Sound settings; changes also affect other apps using those events. Choosing a file source changes only this extension, not your Windows sound scheme.
+
+### Custom WAV sounds
+
+For example, use your own sound when a response completes:
+
+```json
+{
+  "schemaVersion": 2,
+  "events": {
+    "completed": {
+      "sound": {
+        "source": { "type": "file", "path": "C:/Users/you/Sounds/done.wav" }
+      }
+    }
+  }
+}
+```
+
+Use the same `sound.source` object under `defaults` to share a file across events, or choose different files for each event. Remove existing event-specific sources if you want them to inherit `defaults`.
+
+> The format, path, size, and duration limits are deliberate safety trade-offs: they keep file access and playback bounded without external codec/player selection or network audio sources. This extension favors short notification sounds over a general-purpose media player.
+- Supply an absolute path on a local **fixed drive**, such as `C:/Sounds/done.wav`. Forward slashes work and avoid JSON backslash escaping; with backslashes, write `C:\Sounds\done.wav` as `"C:\\Sounds\\done.wav"` in JSON.
+- Relative paths, `~`, environment-variable expansion, URLs, UNC paths, mapped network drives, device paths, alternate data streams, and reparse points (including ancestor junctions/symlinks) are not supported.
+- Files must be RIFF PCM WAV: mono or stereo, 8- or 16-bit, 8–48 kHz, at most **5 seconds** and **5 MiB**. MP3, compressed WAV, and WAV extensible are not supported. Renaming an MP3 to `.wav` won't work.
+- There is no per-sound volume setting, looping, external player, or bundled audio. Use audio you trust and have permission to use.
+- Paths are validated on reload; files are read and checked only when an enabled sound is actually submitted. A missing, unreadable, unsupported, or oversized file returns `SOUND_FAILED`; the toast is still attempted. There is no fallback to a system sound.
+- File paths are sent to the fixed helper through stdin, not command arguments, and aren't printed by `status` or error messages.
 
 ### Apply changes and older configs
 
@@ -155,7 +189,7 @@ The old unversioned format, with a boolean such as `events.completed.sound: fals
 
 ## Commands
 
-Run these inside Pi. After `/windows-notifier `, press **Tab** to complete `status`, `reload`, or `test`. After `test `, Tab completes the event name; partial prefixes such as `test co` also work.
+Run these inside Pi. After `/windows-notifier `, press **Tab** to show `status`, `reload`, or `test`, use **↑/↓** to choose, then press **Tab** to accept. Completing `test` adds a space automatically, so you can keep pressing **Tab** to show and accept an event name without typing a space. Partial prefixes such as `test co` also work.
 
 ```text
 /windows-notifier status
@@ -164,7 +198,7 @@ Run these inside Pi. After `/windows-notifier `, press **Tab** to complete `stat
 /windows-notifier test permission
 ```
 
-- `status` shows channel switches, sound choices, backend status, queue counters, and diagnostic codes—not your custom text or session content.
+- `status` shows channel switches, sound choices, backend status, queue counters, and diagnostic codes—not your custom text, file paths, or session content.
 - `reload` reads the config again and cancels old notification work.
 - `test` sends a completion notification by default. You can also choose `permission`, `question`, `completed`, `aborted`, or `failed`.
 
@@ -176,7 +210,7 @@ Run these inside Pi. After `/windows-notifier `, press **Tab** to complete `stat
 
 Windows still has the final say. Do Not Disturb, notification settings, your sound scheme, and muted audio can suppress a toast or sound even after the API accepts it.
 
-The sender may appear as **PowerShell** because the extension uses the `Microsoft.Windows.PowerShell` AppID. The toast title defaults to **Pi**, or the title you choose. Toast audio is disabled and the system sound is played separately to avoid a duplicate sound from this backend. If one fails, the other is still attempted. There is no fallback notification or audio player.
+The sender may appear as **PowerShell** because the extension uses the `Microsoft.Windows.PowerShell` AppID. The toast title defaults to **Pi**, or the title you choose. Toast audio is disabled and the selected sound is played separately to avoid a duplicate sound from this backend. If one fails, the other is still attempted. There is no fallback notification or audio player.
 
 Use `/windows-notifier status` to check these codes:
 
@@ -195,13 +229,16 @@ Automatic errors show at most one terminal warning per minute. Status uses fixed
 
 ## Privacy and process safety
 
-This extension uses Windows' built-in notification and sound APIs through a fixed PowerShell script. You don't need a separate notification server or audio player. There are no network notifications, telemetry, or custom sound files.
+This extension uses Windows' built-in notification and sound APIs through a fixed PowerShell script. You don't need a separate notification server or audio player. There are no network notifications, telemetry, downloads, or bundled sound files.
+
+Several feature restrictions are intentional security decisions, not just platform limitations. The safeguards below address command injection, executable lookup hijacking, accidental credential exposure, network-path access, unbounded process creation, and interference with unrelated applications. They are not a guarantee that the extension is vulnerability-free.
 
-- PowerShell is located using an absolute path under the startup environment's `SystemRoot` or `windir`, never the project directory or `PATH`.
-- The helper runs without a shell. It receives only the event type, validated channel settings, and static config text through stdin. Text is inserted using DOM text nodes, not interpolated into PowerShell commands or XML. No session content is passed to it.
-- The child process gets a limited set of Windows environment variables, not Pi's full environment or API tokens. `-ExecutionPolicy Bypass` applies only to that child; it doesn't grant administrator access or change permanent settings. Execution Policy isn't treated as a security boundary.
-- Only one helper runs at a time. The queue holds at most 16 notifications, launches are at least a second apart, queued work expires after 30 seconds, and the helper has a 10-second timeout. stdout and stderr are each capped at 8 KiB. Permission requests and questions take priority over response notifications.
-- It only attempts to stop its own child process, never every process with the same name. If Windows refuses to stop that process, new helpers wait for it to close instead of piling up.
+- To reduce executable lookup hijacking, PowerShell is located using an absolute path under the startup environment's `SystemRoot` or `windir`, never the project directory or `PATH`.
+- To avoid command/XML injection from config values, the helper runs without a shell. It receives only the event type, validated channel settings (including a local WAV path when configured), and static config text through stdin. Text is inserted using DOM text nodes, not interpolated into PowerShell commands or XML. No session content is passed to it.
+- To reduce accidental credential exposure, the child process gets a limited set of Windows environment variables, not Pi's full environment or API tokens. `-ExecutionPolicy Bypass` applies only to that child; it doesn't grant administrator access or change permanent settings. Execution Policy isn't treated as a security boundary.
+- WAV files are checked for local-drive paths and reparse points, read into size-limited memory, and validated before playback through `System.Media.SoundPlayer`. Playback stays in the same helper and is covered by its timeout and cancellation. File checks are not a sandbox against an attacker concurrently changing filesystem paths.
+- To limit process storms and resource consumption, only one helper runs at a time. The queue holds at most 16 notifications, launches are at least a second apart, queued work expires after 30 seconds, and the helper has a 10-second timeout. stdout and stderr are each capped at 8 KiB. Permission requests and questions take priority over response notifications.
+- To avoid terminating unrelated applications, it only attempts to stop its own child process, never every process with the same name. If Windows refuses to stop that process, new helpers wait for it to close instead of piling up.
 - Decisions, finished questions, new runs, reloads, session changes, and shutdown cancel the relevant old work. A toast already shown can't be taken back, and cancellation can race with submission to Windows.
 
 These safeguards assume that Windows' system directories, Pi's startup environment, and installed packages are trustworthy. They don't protect against a malicious extension running in the same process or a compromised user account. Pi's permission system doesn't sandbox extensions at the OS level.
@@ -214,7 +251,7 @@ npm run verify
 npm pack --dry-run
 ```
 
-Tests use a fake clock, event bus, and launcher. On Windows, they also check PowerShell syntax and invalid input handling. Normal `npm test` runs don't show toasts or play sounds. See the [verification notes (繁體中文)](docs/verification.md) for the test scope and remaining checks.
+Tests use a fake clock, event bus, and launcher. On Windows, they also check PowerShell syntax, invalid input handling, PCM WAV validation, bounded file reads, and junction rejection. Normal `npm test` runs don't show toasts or play sounds. See the [verification notes (繁體中文)](docs/verification.md) for the test scope and remaining checks.
 
 ## License
 

package/README.zh-TW.md

@@ -2,11 +2,15 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md)
 
-不用一直盯著 Pi。需要你確認權限、回答問題，或模型回應結束時，這個 extension 會跳出 Windows 通知並播放提示音。就算你正在看別的視窗，也會提醒。
+**專為 Windows 設計。0 依賴套件。以安全為優先的提示音與通知插件。**
+
+需要你確認權限、回答問題，或模型回應結束時，會自動跳出 Windows 通知，並播放系統提示音或你自訂的 WAV 音效。就算你正在看別的視窗也會提醒，讓你不用一直盯著 Pi。
 
 通知不會從 session 帶出問題、命令、檔案路徑或模型回答，但你可以設定自己的固定提醒文字。它也不會替你批准權限或回答問題，所有提醒都在本機處理。
 
-[GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
+使用 Pi 提供的 API、Node.js built-ins 與 Windows 內建通知和音效 API，不必另裝通知函式庫或外部播放器。設計上避開了許多其他同類套件的高風險做法；具體防護與限制見[隱私與程序安全](#隱私與程序安全)。
+
+[Pi 套件頁](https://pi.dev/packages/pi-windows-notifier) · [GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
 
 ## 安裝
 
@@ -37,7 +41,7 @@ pi remove npm:pi-windows-notifier
 |---|---|---|
 | `permission` | Permission approval needed | Exclamation |
 | `question` | Waiting for your answer | Exclamation |
-| `completed` | Response complete | Asterisk |
+| `completed` | Response complete | Hand |
 | `aborted` | Response interrupted | Exclamation |
 | `failed` | Response failed | Exclamation |
 
@@ -61,11 +65,13 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 
 ## 設定
 
-想改預設行為時，請自行建立 `~/.pi/agent/pi-windows-notifier/config.json`。在 Windows 上，就是使用者家目錄裡的 `.pi\agent\pi-windows-notifier\config.json`。套件不會替你建立或修改這個檔案，也不讀專案內的設定。
+想改預設行為時，請自行建立 `~/.pi/agent/extensions/pi-windows-notifier/config.json`。在 Windows 上，就是使用者家目錄裡的 `.pi\agent\extensions\pi-windows-notifier\config.json`。套件不會替你建立或修改這個檔案，也不讀專案內的設定。
+
+新路徑優先；只有新檔案不存在時，才讀舊的 `~/.pi/agent/pi-windows-notifier/config.json`，兩份設定不會合併。新檔案若無效或無法讀取，會停用通知，不會改讀舊檔。想搬移設定時，請自行將原本的設定檔放到新路徑後 reload；套件不會搬動或改寫任何一份檔案。
 
 ### 完整設定範例
 
-下面列出所有支援的欄位和五種事件，可以直接複製作為起點。不過，**實際只要保留想修改的欄位，加上 `schemaVersion: 2` 就好**。每個事件都覆寫了共用訊息，因此這份範例的效果等同內建預設。
+下面列出系統音效的欄位和五種事件，可以直接複製作為起點；檔案音效範例另列於下方。不過，**實際只要保留想修改的欄位，加上 `schemaVersion: 2` 就好**。每個事件都覆寫了共用訊息，因此這份範例的效果等同內建預設。
 
 ```json
 {
@@ -99,7 +105,7 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
     "completed": {
       "enabled": true,
       "toast": { "enabled": true, "title": "Pi", "message": "Response complete" },
-      "sound": { "enabled": true, "source": { "type": "system", "name": "Asterisk" } }
+      "sound": { "enabled": true, "source": { "type": "system", "name": "Hand" } }
     },
     "aborted": {
       "enabled": true,
@@ -130,22 +136,50 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 | `toast.title` | 固定的通知標題 |
 | `toast.message` | 固定的通知訊息 |
 | `sound.enabled` | 音效開關 |
-| `sound.source.type` | 目前只支援 `"system"` |
-| `sound.source.name` | `Asterisk`、`Beep`、`Exclamation`、`Hand`、`Question`，大小寫要一致 |
+| `sound.source.type` | `"system"` 使用 Windows 系統音效，`"file"` 使用本機 WAV |
+| `sound.source.name` | `"system"` 必填：`Asterisk`、`Beep`、`Exclamation`、`Hand`、`Question`，大小寫要一致 |
+| `sound.source.path` | `"file"` 必填：本機 WAV 的絕對路徑，最多 1024 個 UTF-16 code units |
 
-`toast` 和 `sound` 欄位都能放在 `defaults` 或個別事件底下。**完整範例已寫出每個事件的所有欄位，只改 `defaults` 不會改到已被事件覆寫的值。** 想讓事件沿用共用設定，請刪除該事件底下對應的欄位。設定 `sound.source` 時必須一起提供 `type` 和 `name`，它會整組取代原本的來源。
+`toast` 和 `sound` 欄位都能放在 `defaults` 或個別事件底下。**完整範例已寫出每個事件的所有欄位，只改 `defaults` 不會改到已被事件覆寫的值。** 想讓事件沿用共用設定，請刪除該事件底下對應的欄位。設定 `sound.source` 時必須提供 `type`，以及系統音效的 `name` 或檔案音效的 `path`，不能同時提供兩者；它會整組取代原本的來源。
 
 - **只要彈窗**：將 `sound.enabled` 設為 `false`、`toast.enabled` 設為 `true`。
 - **只要音效**：將 `toast.enabled` 設為 `false`、`sound.enabled` 設為 `true`。
 - 兩個通道都關閉時，不啟動 helper。事件可以覆寫共用通道開關，但不能繞過已關閉的總開關或事件開關。
 
-沒有設定檔時，所有事件與通道都開啟，標題是 Pi，訊息是英文。完成通知使用 Asterisk，其他事件使用 Exclamation。
+沒有設定檔時，所有事件與通道都開啟，標題是 Pi，訊息是英文。完成通知使用 Hand，其他事件使用 Exclamation。
 
 ### 文字與音效限制
 
 文字會照你寫的內容顯示，不會從 session 帶入變數，也沒有模板替換。標題最多 128 個 UTF-16 code units，訊息最多 512 個；emoji 可能算兩個。兩者都必須是非空白的單行字串，不能包含控制字元或不合法的 XML 字元。自訂文字會出現在 Windows 通知裡，請不要放敏感資訊；它不會顯示在 `status` 或錯誤提示中。
 
-音效名稱選的是 **Windows 系統音效事件**，不是套件內附的不同音效檔。實際聲音取決於 Windows 音效配置；不同事件可能共用同一個聲音，也可能沒有對應音效。你可以在 Windows「音效」設定中查看或修改對應，但修改也會影響使用相同事件的其他程式。目前不支援自訂音效檔。
+音效名稱選的是 **Windows 系統音效事件**，不是套件內附的不同音效檔。實際聲音取決於 Windows 音效配置；不同事件可能共用同一個聲音，也可能沒有對應音效。你可以在 Windows「音效」設定中查看或修改對應，但修改也會影響使用相同事件的其他程式。改用檔案來源只影響這個 extension，不會修改 Windows 音效配置。
+
+### 自訂 WAV 音效
+
+例如，讓回應完成時播放你自己的音效：
+
+```json
+{
+  "schemaVersion": 2,
+  "events": {
+    "completed": {
+      "sound": {
+        "source": { "type": "file", "path": "C:/Users/you/Sounds/done.wav" }
+      }
+    }
+  }
+}
+```
+
+同樣的 `sound.source` 也可以放在 `defaults`，讓多個事件共用檔案，或為每個事件選擇不同音效。想沿用 `defaults` 時，請移除原本事件底下的來源覆寫。
+
+> 格式、路徑、大小與長度限制是刻意的安全取捨：讓檔案存取與播放保持有界，不引入外部 codec／播放器選擇或網路音訊來源。這個 extension 著重短提示音，不是通用媒體播放器。
+- 使用本機**固定磁碟**上的絕對路徑，例如 `C:/Sounds/done.wav`。正斜線可以直接使用，避免 JSON 跳脫；使用反斜線時，`C:\Sounds\done.wav` 在 JSON 要寫成 `"C:\\Sounds\\done.wav"`。
+- 不支援相對路徑、`~`、環境變數展開、URL、UNC 路徑、網路磁碟、裝置路徑、alternate data streams 或 reparse points（包含上層目錄的 junction／symlink）。
+- 檔案必須是 RIFF PCM WAV：mono 或 stereo、8 或 16 bit、8–48 kHz，最多 **5 秒**、**5 MiB**。不支援 MP3、壓縮 WAV 或 WAV extensible；把 MP3 改名成 `.wav` 也不能播放。
+- 不提供個別音量、循環播放、外部播放器或內附音效。請使用可信任且有權使用的音訊。
+- reload 時驗證路徑；只有啟用的音效實際提交時，才讀取並檢查檔案。檔案不存在、無法讀取、格式不支援或超過限制時回報 `SOUND_FAILED`，彈窗仍會嘗試送出，不會改播系統音效。
+- 檔案路徑透過 stdin 送入固定 helper，不放在命令參數，也不顯示在 `status` 或錯誤提示中。
 
 ### 套用修改與舊格式相容
 
@@ -155,7 +189,7 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 
 ## 指令
 
-在 Pi 裡執行。輸入 `/windows-notifier ` 後按 **Tab**，可以補全 `status`、`reload` 或 `test`；輸入 `test ` 後，Tab 會補全事件名稱，也支援 `test co` 這類前綴。
+在 Pi 裡執行。輸入 `/windows-notifier ` 後按 **Tab**，會列出 `status`、`reload` 或 `test`；用 **↑/↓** 選擇，再按 **Tab** 接受。補完 `test` 會自動加上空白，接著連按 **Tab** 即可列出並接受事件名稱，不必手動輸入空白；也支援 `test co` 這類前綴。
 
 ```text
 /windows-notifier status
@@ -164,7 +198,7 @@ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好
 /windows-notifier test permission
 ```
 
-- `status`：查看通道開關、音效選擇、backend 狀態、佇列計數和診斷碼，不會顯示自訂文字或 session 內容。
+- `status`：查看通道開關、音效選擇、backend 狀態、佇列計數和診斷碼，不會顯示自訂文字、檔案路徑或 session 內容。
 - `reload`：重新讀取設定，取消舊的通知工作。
 - `test`：預設測試完成通知，也能指定 `permission`、`question`、`completed`、`aborted` 或 `failed`。
 
@@ -196,13 +230,16 @@ Windows 仍然有最終決定權。勿擾模式、通知設定、系統音效方
 
 ## 隱私與程序安全
 
-套件透過固定的 PowerShell 腳本呼叫 Windows 內建通知和音效 API，不用另外裝通知服務或播放器。沒有網路通知、遙測或自訂音效檔。
+套件透過固定的 PowerShell 腳本呼叫 Windows 內建通知和音效 API，不用另外裝通知服務或播放器。沒有網路通知、遙測、下載或內附音效檔。
+
+部分功能限制是刻意的安全設計，不只是平台限制。以下防護針對命令注入、執行檔搜尋劫持、憑證意外外洩、網路路徑存取、無界程序建立，以及誤傷其他程式等風險；不代表套件保證沒有漏洞。
 
-- PowerShell 使用啟動環境的 `SystemRoot`／`windir` 下的絕對路徑，不從專案目錄或 `PATH` 搜尋。
-- helper 不透過 shell 執行，只從 stdin 接收事件類型、已驗證的通道設定與固定設定文字。文字用 DOM text node 加進通知，不拼進 PowerShell 命令或 XML，也不傳入 session 內容。
-- 子程序只拿到必要的 Windows 環境變數，不繼承 Pi 的完整環境或 API tokens。`-ExecutionPolicy Bypass` 只作用於該子程序，不會取得管理員權限或改動永久設定，也不把 Execution Policy 當成安全邊界。
-- 同時最多一個 helper，佇列最多 16 筆，啟動至少間隔一秒。工作等待超過 30 秒會過期，helper 的 timeout 是 10 秒，stdout 和 stderr 各限制 8 KiB。權限和提問比回應結束通知優先。
-- 只嘗試終止自己建立的子程序，不會按名稱關閉其他程序。如果 Windows 不允許終止，就等它結束，不會繼續堆出新的 helper。
+- 為降低執行檔搜尋劫持風險，PowerShell 使用啟動環境的 `SystemRoot`／`windir` 下的絕對路徑，不從專案目錄或 `PATH` 搜尋。
+- 為避免設定值造成命令／XML 注入，helper 不透過 shell 執行，只從 stdin 接收事件類型、已驗證的通道設定（含自訂音效的本機 WAV 路徑）與固定設定文字。文字用 DOM text node 加進通知，不拼進 PowerShell 命令或 XML，也不傳入 session 內容。
+- 為降低憑證意外外洩風險，子程序只拿到必要的 Windows 環境變數，不繼承 Pi 的完整環境或 API tokens。`-ExecutionPolicy Bypass` 只作用於該子程序，不會取得管理員權限或改動永久設定，也不把 Execution Policy 當成安全邊界。
+- WAV 播放前會檢查本機磁碟路徑與 reparse points，讀入有大小限制的記憶體並驗證格式，再交給 `System.Media.SoundPlayer`。播放留在同一個 helper，沿用逾時與取消機制；檔案檢查不是防止攻擊者同時修改路徑的 sandbox。
+- 為限制大量程序啟動與資源消耗，同時最多一個 helper，佇列最多 16 筆，啟動至少間隔一秒。工作等待超過 30 秒會過期，helper 的 timeout 是 10 秒，stdout 和 stderr 各限制 8 KiB。權限和提問比回應結束通知優先。
+- 為避免誤關其他程式，只嘗試終止自己建立的子程序，不會按名稱關閉其他程序。如果 Windows 不允許終止，就等它結束，不會繼續堆出新的 helper。
 - 權限決策、問題結束、新回應、reload、session 切換和 shutdown 都會取消相關舊工作。已經顯示的 Toast 無法收回，取消和提交給 Windows 之間仍可能發生競態。
 
 這些防護假設 Windows 系統目錄、Pi 啟動環境和已安裝套件可信。它們無法防禦同程序裡的惡意 extension，或已遭入侵的使用者帳號。Pi permission system 並不是 extension 的 OS 沙盒。
@@ -215,7 +252,7 @@ npm run verify
 npm pack --dry-run
 ```
 
-測試使用假時鐘、event bus 和 launcher。Windows 上也會檢查 PowerShell 語法與無效輸入。一般 `npm test` 不會跳彈窗或播放音效；測試範圍與仍需確認的項目見[驗證紀錄](docs/verification.md)。
+測試使用假時鐘、event bus 和 launcher。Windows 上也會檢查 PowerShell 語法、無效輸入、PCM WAV 驗證、有界檔案讀取與 junction 拒絕。一般 `npm test` 不會跳彈窗或播放音效；測試範圍與仍需確認的項目見[驗證紀錄](docs/verification.md)。
 
 ## 授權
 

package/THIRD_PARTY_NOTICES.md

@@ -35,5 +35,5 @@ SOFTWARE.
 ## Other references
 
 - [UniPi notify](https://github.com/Neuron-Mr-White/UniPi/tree/main/packages/notify), reference commit `6ac5da3`: consulted for event/backend separation. No code was copied, and neither UniPi core nor node-notifier is included.
-- [pi-jingle](https://github.com/Git-Monke/pi-jingle), reference commit `7e265ce`: consulted for the idea of event-specific sounds. Its license was not confirmed during development, so no code or audio assets were copied.
+- [pi-jingle](https://github.com/Git-Monke/pi-jingle), reference commit `7e265ce`: consulted for the idea of event-specific sounds. Its license was not confirmed during development, so no code or audio assets were copied. Custom WAV support, path validation, bounded PCM parsing, and tests were implemented independently using Windows/.NET APIs.
 - Pi, pi-permission-system, RPIV/Lean, and Plan mode APIs and source were consulted to verify integration contracts. Their source code is not bundled in this package.

package/docs/verification.md

@@ -3,8 +3,9 @@
 ## 自動驗證
 
 - TypeScript `tsc --noEmit` 與 Node test runner 通過；測試覆蓋設定驗證、權限與提問事件、回應狀態、去重取消、限流佇列、PowerShell launcher、資源清理與發布檔案清單。
-- 設定測試涵蓋 schema v2 合併、舊格式相容、獨立通道、系統音效白名單、自訂文字上限與 Unicode／XML 驗證；status 與錯誤提示不展示設定文字。
-- Windows 測試檢查固定 PowerShell helper 語法、無效輸入，以及通道全關閉時的有效輸入；不呼叫 Toast 或音效 API。單通道成功／失敗結果由 mock launcher 驗證。
+- 設定測試涵蓋 schema v2 合併、舊格式相容、獨立通道、系統音效白名單、本機 WAV 路徑、自訂文字上限與 Unicode／XML 驗證；status 與錯誤提示不展示設定文字或檔案路徑。
+- Windows 測試檢查兩個固定 PowerShell 腳本的語法、無效輸入，以及通道全關閉時的有效輸入；不呼叫 Toast 或音效 API。單通道成功／失敗結果由 mock launcher 驗證。
+- WAV 測試使用自行合成的 PCM 資料，實際呼叫 helper 的讀取與驗證函式：mono／stereo、8／16 bit、五秒邊界、奇數 chunk padding、Unicode／引號／指令樣式檔名、超大／截斷／偽造格式、重複 chunks、缺失檔案、目錄與祖先 junction。這些測試不執行播放函式。
 - 發布包以 npm pack dry-run 核對；僅包含套件 metadata、runtime 原始碼、PowerShell helper、文件及授權。
 
 執行完整檢查：
@@ -21,6 +22,8 @@ npm pack --dry-run
 
 0.2.0 的自訂標題／訊息、Toast-only、sound-only 與新增系統音效選擇尚未完成實際可見／可聽驗收；不以舊版結果推論新 helper 已通過。
 
+新增的自訂 WAV 播放尚未完成實際可聽驗收。手動驗收時，請在全域 config 的 `events.completed.sound.source` 設定 `{ "type": "file", "path": "C:/Sounds/done.wav" }`，使用符合限制的可信任檔案，reload 後執行 `/windows-notifier test completed`。另需確認 sound-only、檔案缺失時 Toast 仍送出，以及播放中 reload／shutdown 的取消行為。這些指令會產生實際通知與聲音。
+
 這項 backend 驗證不等於所有 Pi 整合情境均已端到端驗收。以下項目仍需在實際使用環境確認：
 
 - `pi-permission-system` 的 ask／轉送權限請求。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-windows-notifier",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Windows notifications and sounds for Pi permission requests, questions, and completed, interrupted, or failed responses.",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/C-W-Z/pi-windows-notifier.git"
   },
-  "homepage": "https://github.com/C-W-Z/pi-windows-notifier#readme",
+  "homepage": "https://pi.dev/packages/pi-windows-notifier",
   "bugs": {
     "url": "https://github.com/C-W-Z/pi-windows-notifier/issues"
   },
@@ -23,7 +23,7 @@
   ],
   "files": [
     "src/**/*.ts",
-    "src/windows-notify.ps1",
+    "src/*.ps1",
     "README.md",
     "README.zh-TW.md",
     "docs/verification.md",

package/src/completion.ts

@@ -0,0 +1,42 @@
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
+import { KINDS } from "./types.ts";
+
+export function notifierArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+  const leading = prefix.match(/^\s*/u)![0];
+  const argument = prefix.slice(leading.length);
+  if (!/\s/u.test(argument)) {
+    const matches = ["status", "reload", "test"].filter(value => value.startsWith(argument));
+    // test 還有下一層參數；補上空白，讓下一次 Tab 能直接補事件名稱。
+    return matches.length ? matches.map(value => ({
+      value: leading + value + (value === "test" ? " " : ""), label: value,
+    })) : null;
+  }
+  const match = argument.match(/^test(\s+)(\S*)$/u);
+  if (!match) return null;
+  const matches = KINDS.filter(kind => kind.startsWith(match[2]));
+  // Pi 會替換整段 argument prefix；必須保留 test 與空白，不只回傳事件名稱。
+  return matches.length ? matches.map(kind => ({ value: leading + "test" + match[1] + kind, label: kind })) : null;
+}
+
+/** 只接管本指令的參數，避免選單關閉後的 Tab 改走 Pi 的強制檔案補全。 */
+export function withNotifierCompletions(current: AutocompleteProvider): AutocompleteProvider {
+  const argumentPrefix = (lines: string[], cursorLine: number, cursorCol: number) =>
+    cursorLine === 0 ? (lines[0] ?? "").slice(0, cursorCol).match(/^\s*\/windows-notifier (.*)$/u)?.[1] : undefined;
+  return {
+    triggerCharacters: current.triggerCharacters,
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      const prefix = argumentPrefix(lines, cursorLine, cursorCol);
+      if (prefix === undefined) return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      if (options.signal.aborted) return null;
+      const items = notifierArgumentCompletions(prefix);
+      return items ? { items, prefix } : null;
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      if (argumentPrefix(lines, cursorLine, cursorCol) !== undefined) return true;
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}

package/src/config.ts

@@ -1,7 +1,7 @@
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { KINDS, SYSTEM_SOUNDS, TITLE_LIMIT, MESSAGE_LIMIT, isRecord, onlyKeys, validText,
+import { KINDS, TITLE_LIMIT, MESSAGE_LIMIT, isRecord, onlyKeys, validText, validSoundSource,
   type NotificationKind, type ToastConfig, type SoundConfig } from "./types.ts";
 
 export interface EventConfig { enabled: boolean; toast: ToastConfig; sound: SoundConfig }
@@ -22,7 +22,7 @@ const MESSAGES: Record<NotificationKind, string> = {
 export function defaults(): Config {
   return { schemaVersion: 2, enabled: true, events: Object.fromEntries(KINDS.map(kind =>
     [kind, { enabled: true, toast: { enabled: true, title: "Pi", message: MESSAGES[kind] },
-      sound: { enabled: true, source: { type: "system", name: kind === "completed" ? "Asterisk" : "Exclamation" } } }])) as Config["events"] };
+      sound: { enabled: true, source: { type: "system", name: kind === "completed" ? "Hand" : "Exclamation" } } }])) as Config["events"] };
 }
 function applyChannels(target: EventConfig, value: Record<string, unknown>): boolean {
   if (Object.hasOwn(value, "toast")) {
@@ -48,10 +48,9 @@ function applyChannels(target: EventConfig, value: Record<string, unknown>): boo
     }
     if (Object.hasOwn(sound, "source")) {
       const source = sound.source;
-      if (!isRecord(source) || !onlyKeys(source, ["type", "name"]) ||
-          source.type !== "system" || !SYSTEM_SOUNDS.includes(source.name as SoundConfig["source"]["name"])) return false;
-      // source 作為完整單位覆寫，避免未來不同來源類型留下混合欄位。
-      target.sound.source = { type: "system", name: source.name as SoundConfig["source"]["name"] };
+      if (!validSoundSource(source)) return false;
+      // source 作為完整單位覆寫，不合併不同來源類型的欄位。
+      target.sound.source = { ...source };
     }
   }
   return true;
@@ -94,9 +93,16 @@ export function parseConfig(value: unknown): ConfigResult {
 }
 export const CONFIG_LIMIT = 16 * 1024;
 export function configPath(): string {
-  return join(homedir(), ".pi", "agent", "pi-windows-notifier", "config.json");
+  return join(homedir(), ".pi", "agent", "extensions", "pi-windows-notifier", "config.json");
 }
-export function loadConfig(path = configPath()): ConfigResult {
+/** 預設先讀新位置，只有檔案不存在才讀舊位置；明確傳入路徑時不讀取其他使用者設定。 */
+export function loadConfig(path?: string, fallbackPath?: string): ConfigResult {
+  const primary = path ?? configPath();
+  const legacy = fallbackPath ?? (path === undefined
+    ? join(homedir(), ".pi", "agent", "pi-windows-notifier", "config.json") : undefined);
+  return readConfig(primary) ?? (legacy ? readConfig(legacy) : undefined) ?? { ok: true, config: defaults() };
+}
+function readConfig(path: string): ConfigResult | undefined {
   let fd: number | undefined;
   try {
     fd = openSync(path, "r");
@@ -112,7 +118,7 @@ export function loadConfig(path = configPath()): ConfigResult {
     try { return parseConfig(JSON.parse(buffer.subarray(0, size).toString("utf8"))); }
     catch { return { ok: false, code: "CONFIG_INVALID", config: { ...defaults(), enabled: false } }; }
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ok: true, config: defaults() };
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
     return { ok: false, code: "CONFIG_READ_FAILED", config: { ...defaults(), enabled: false } };
   } finally {
     if (fd !== undefined) closeSync(fd);

package/src/launcher.ts

@@ -1,6 +1,6 @@
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import { statSync } from "node:fs";
-import { dirname, win32 } from "node:path";
+import { dirname, join, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isRecord, validPayload, type NotificationPayload } from "./types.ts";
 
@@ -79,7 +79,7 @@ export function createWindowsBackend(options: BackendOptions = {}): Backend {
   const script = options.scriptPath ?? SCRIPT;
   const isFile = options.isFile ?? (path => { try { return statSync(path).isFile(); } catch { return false; } });
   const available = platform === "win32" && ["x64", "arm64"].includes(arch) &&
-    !!paths && isFile(paths.executable) && isFile(script);
+    !!paths && isFile(paths.executable) && isFile(script) && isFile(join(dirname(script), "windows-sound.ps1"));
   const spawnProcess = options.spawnProcess ?? spawn;
   const code = available ? "OK" : "BACKEND_UNAVAILABLE";
   return {

package/src/runtime.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defaults, loadConfig, type ConfigResult } from "./config.ts";
+import { notifierArgumentCompletions, withNotifierCompletions } from "./completion.ts";
 import { createWindowsBackend, windowsPaths, type Backend } from "./launcher.ts";
 import { NotificationScheduler, systemClock, type Clock, type Submission } from "./scheduler.ts";
 import { NotificationState } from "./state.ts";
@@ -107,7 +108,10 @@ export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {})
     if (!target || target.disposed || target.backendCode === "ENV_UNSUPPORTED") return;
     try { handler(target.state); } catch { diagnose(target, "EVENT_INVALID"); }
   };
-  pi.on("session_start", async (_event, context) => { await transition(() => start(context)); });
+  pi.on("session_start", async (_event, context) => {
+    if (context.mode === "tui" && context.hasUI) context.ui.addAutocompleteProvider(withNotifierCompletions);
+    await transition(() => start(context));
+  });
   pi.on("session_shutdown", async () => { await transition(stop); });
   pi.on("tool_execution_start", event => { observe(state => state.toolStart(event)); });
   pi.on("tool_execution_end", event => { observe(state => state.toolEnd(event)); });
@@ -121,19 +125,7 @@ export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {})
 
   pi.registerCommand("windows-notifier", {
     description: "Windows 通知：status、reload、test [permission|question|completed|aborted|failed]",
-    getArgumentCompletions: prefix => {
-      const leading = prefix.match(/^\s*/u)![0];
-      const argument = prefix.slice(leading.length);
-      if (!/\s/u.test(argument)) {
-        const matches = ["status", "reload", "test"].filter(value => value.startsWith(argument));
-        return matches.length ? matches.map(value => ({ value: leading + value, label: value })) : null;
-      }
-      const match = argument.match(/^test(\s+)(\S*)$/u);
-      if (!match) return null;
-      const matches = KINDS.filter(kind => kind.startsWith(match[2]));
-      // Pi 會替換整段 argument prefix；必須保留 test 與空白，不只回傳事件名稱。
-      return matches.length ? matches.map(kind => ({ value: leading + "test" + match[1] + kind, label: kind })) : null;
-    },
+    getArgumentCompletions: notifierArgumentCompletions,
     handler: async (args, context) => {
       const parts = args.trim().split(/\s+/u);
       if (parts.length === 1 && parts[0] === "reload") {
@@ -147,11 +139,12 @@ export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {})
           backend: target?.backendCode ?? "NOT_STARTED",
           enabled: target?.result.config.enabled ?? false,
           schemaVersion: target?.result.config.schemaVersion,
-          // 自訂文字只送入 helper；status 不展示可能含敏感資訊的設定文字。
+          // 自訂文字與檔案路徑只送入 helper；status 不展示可能含敏感資訊的設定。
           events: target ? Object.fromEntries(KINDS.map(kind => {
             const event = target.result.config.events[kind];
             return [kind, { enabled: event.enabled, toast: { enabled: event.toast.enabled },
-              sound: { enabled: event.sound.enabled, source: { ...event.sound.source } } }];
+              sound: { enabled: event.sound.enabled, source: event.sound.source.type === "system"
+                ? { ...event.sound.source } : { type: "file" } } }];
           })) : undefined,
           ...target?.scheduler?.status(),
           diagnostics: [...(target?.diagnostics ?? [])],

package/src/types.ts

@@ -6,7 +6,9 @@ export type SystemSound = (typeof SYSTEM_SOUNDS)[number];
 export const TITLE_LIMIT = 128;
 export const MESSAGE_LIMIT = 512;
 export interface ToastConfig { enabled: boolean; title: string; message: string }
-export interface SoundConfig { enabled: boolean; source: { type: "system"; name: SystemSound } }
+export const SOUND_PATH_LIMIT = 1024;
+export type SoundSource = { type: "system"; name: SystemSound } | { type: "file"; path: string };
+export interface SoundConfig { enabled: boolean; source: SoundSource }
 export interface NotificationPayload { kind: NotificationKind; toast: ToastConfig; sound: SoundConfig }
 /** 限制單行 XML 文字；保留引號與 XML 字元，由 DOM 安全編碼。 */
 export function validText(value: unknown, limit: number): value is string {
@@ -16,6 +18,19 @@ export function validText(value: unknown, limit: number): value is string {
 export function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
   return Object.keys(value).every(key => keys.includes(key));
 }
+/** 僅接受一般磁碟上的絕對 WAV 路徑；不展開環境變數、家目錄或專案相對路徑。 */
+export function validSoundPath(value: unknown): value is string {
+  if (!validText(value, SOUND_PATH_LIMIT) || !/^[a-z]:[\\/]/iu.test(value) ||
+      /[<>:"|?*]/u.test(value.slice(2)) || !/\.wav$/iu.test(value)) return false;
+  return value.slice(3).split(/[\\/]/u).every(part => part.length > 0 && !/[. ]$/u.test(part) &&
+    !/^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/iu.test(part));
+}
+export function validSoundSource(value: unknown): value is SoundSource {
+  if (!isRecord(value)) return false;
+  return value.type === "system"
+    ? onlyKeys(value, ["type", "name"]) && SYSTEM_SOUNDS.includes(value.name as SystemSound)
+    : value.type === "file" && onlyKeys(value, ["type", "path"]) && validSoundPath(value.path);
+}
 export function validPayload(value: unknown): value is NotificationPayload {
   if (!isRecord(value) || !onlyKeys(value, ["kind", "toast", "sound"]) ||
       !KINDS.includes(value.kind as NotificationKind) || !isRecord(value.toast) || !isRecord(value.sound)) return false;
@@ -23,8 +38,7 @@ export function validPayload(value: unknown): value is NotificationPayload {
   return onlyKeys(toast, ["enabled", "title", "message"]) && typeof toast.enabled === "boolean" &&
     validText(toast.title, TITLE_LIMIT) && validText(toast.message, MESSAGE_LIMIT) &&
     onlyKeys(sound, ["enabled", "source"]) && typeof sound.enabled === "boolean" &&
-    isRecord(sound.source) && onlyKeys(sound.source, ["type", "name"]) &&
-    sound.source.type === "system" && SYSTEM_SOUNDS.includes(sound.source.name as SystemSound) &&
+    validSoundSource(sound.source) &&
     (toast.enabled || sound.enabled);
 }
 export interface NotificationJob {

package/src/windows-notify.ps1

@@ -1,8 +1,9 @@
-# 固定 helper：只接受已驗證的通道設定與靜態文字，不接受任意命令或音效路徑。
+# 固定 helper：只接受已驗證的通道設定、靜態文字與本機 WAV 路徑，不接受任意命令。
 Set-StrictMode -Version Latest
 $ErrorActionPreference = "Stop"
 [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false, $true)
 [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+. (Join-Path $PSScriptRoot "windows-sound.ps1")
 
 function Write-Result {
   param([string]$Code, [bool]$Toast, [string]$Sound)
@@ -67,10 +68,15 @@ try {
   Assert-Text $inputData.toast.message 512
   Assert-Keys $inputData.sound @("enabled", "source")
   if ($inputData.sound.enabled -isnot [bool]) { throw "INPUT_INVALID" }
-  Assert-Keys $inputData.sound.source @("type", "name")
-  if ($inputData.sound.source.type -cne "system" -or $inputData.sound.source.type -isnot [string] -or
-      $inputData.sound.source.name -isnot [string] -or
-      @("Asterisk", "Beep", "Exclamation", "Hand", "Question") -cnotcontains $inputData.sound.source.name) { throw "INPUT_INVALID" }
+  if ($inputData.sound.source.type -ceq "system") {
+    Assert-Keys $inputData.sound.source @("type", "name")
+    if ($inputData.sound.source.type -isnot [string] -or $inputData.sound.source.name -isnot [string] -or
+        @("Asterisk", "Beep", "Exclamation", "Hand", "Question") -cnotcontains $inputData.sound.source.name) { throw "INPUT_INVALID" }
+  } elseif ($inputData.sound.source.type -ceq "file") {
+    Assert-Keys $inputData.sound.source @("type", "path")
+    if ($inputData.sound.source.type -isnot [string]) { throw "INPUT_INVALID" }
+    Assert-SoundPath $inputData.sound.source.path
+  } else { throw "INPUT_INVALID" }
 }
 catch {
   Write-Result "INPUT_INVALID" $false "failed"
@@ -101,17 +107,21 @@ if ($inputData.toast.enabled) {
 
 if ($inputData.sound.enabled) {
   try {
-    # 固定 switch 不使用反射、動態 member access 或外部播放器。
-    switch -CaseSensitive ($inputData.sound.source.name) {
-      "Asterisk" { [System.Media.SystemSounds]::Asterisk.Play() }
-      "Beep" { [System.Media.SystemSounds]::Beep.Play() }
-      "Exclamation" { [System.Media.SystemSounds]::Exclamation.Play() }
-      "Hand" { [System.Media.SystemSounds]::Hand.Play() }
-      "Question" { [System.Media.SystemSounds]::Question.Play() }
+    if ($inputData.sound.source.type -ceq "file") {
+      Play-LocalWave $inputData.sound.source.path
+    } else {
+      # 固定 switch 不使用反射、動態 member access 或外部播放器。
+      switch -CaseSensitive ($inputData.sound.source.name) {
+        "Asterisk" { [System.Media.SystemSounds]::Asterisk.Play() }
+        "Beep" { [System.Media.SystemSounds]::Beep.Play() }
+        "Exclamation" { [System.Media.SystemSounds]::Exclamation.Play() }
+        "Hand" { [System.Media.SystemSounds]::Hand.Play() }
+        "Question" { [System.Media.SystemSounds]::Question.Play() }
+      }
+      # Play 非同步；有界等待不保證聲音實際送達，也不建立其他播放器。
+      Start-Sleep -Milliseconds 750
     }
     $soundStatus = "played"
-    # Play 非同步；有界等待不保證聲音實際送達，也不建立其他播放器。
-    Start-Sleep -Milliseconds 750
   }
   catch { $soundStatus = "failed" }
 }

package/src/windows-sound.ps1

@@ -0,0 +1,110 @@
+# 本機 WAV 的獨立驗證與有界讀取；不執行路徑，也不使用 URL、COM 或外部播放器。
+function Assert-SoundPath {
+  param($Value)
+  if ($Value -isnot [string] -or $Value.Length -gt 1024 -or
+      $Value -notmatch '^[a-zA-Z]:[\\/]' -or $Value -notmatch '(?i)\.wav$' -or
+      $Value -match '[\x00-\x1f\x7f-\x9f\u2028\u2029\ufffe\uffff]' -or
+      $Value.Substring(2) -match '[<>:"|?*]') { throw "INPUT_INVALID" }
+  [System.Xml.XmlConvert]::VerifyXmlChars($Value) | Out-Null
+  foreach ($part in ($Value.Substring(3) -split '[\\/]')) {
+    if ($part.Length -eq 0 -or $part -match '[. ]$' -or
+        $part -match '(?i)^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(\.|$)') { throw "INPUT_INVALID" }
+  }
+}
+
+function Assert-Wave {
+  param([byte[]]$Bytes)
+  # 僅接受 RIFF PCM：mono／stereo、8／16 bit、8–48 kHz，最多五秒。
+  if ($Bytes.Length -lt 44 -or $Bytes.Length -gt 5242880 -or
+      [Text.Encoding]::ASCII.GetString($Bytes, 0, 4) -cne "RIFF" -or
+      [Text.Encoding]::ASCII.GetString($Bytes, 8, 4) -cne "WAVE" -or
+      [BitConverter]::ToUInt32($Bytes, 4) -ne $Bytes.Length - 8) { throw "SOUND_FAILED" }
+  $offset = 12
+  $rate = 0
+  $alignment = 0
+  $dataSize = 0
+  $hasFormat = $false
+  $hasData = $false
+  while ($offset -lt $Bytes.Length) {
+    if ($Bytes.Length - $offset -lt 8) { throw "SOUND_FAILED" }
+    $tag = [Text.Encoding]::ASCII.GetString($Bytes, $offset, 4)
+    $size = [long][BitConverter]::ToUInt32($Bytes, $offset + 4)
+    $start = $offset + 8
+    $end = $start + $size + ($size % 2)
+    if ($end -gt $Bytes.Length) { throw "SOUND_FAILED" }
+    if ($tag -ceq "fmt ") {
+      if ($hasFormat -or ($size -ne 16 -and $size -ne 18)) { throw "SOUND_FAILED" }
+      if ([BitConverter]::ToUInt16($Bytes, $start) -ne 1 -or
+          ($size -eq 18 -and [BitConverter]::ToUInt16($Bytes, $start + 16) -ne 0)) { throw "SOUND_FAILED" }
+      $channels = [BitConverter]::ToUInt16($Bytes, $start + 2)
+      $sampleRate = [BitConverter]::ToUInt32($Bytes, $start + 4)
+      $rate = [BitConverter]::ToUInt32($Bytes, $start + 8)
+      $alignment = [BitConverter]::ToUInt16($Bytes, $start + 12)
+      $bits = [BitConverter]::ToUInt16($Bytes, $start + 14)
+      if (@(1, 2) -notcontains $channels -or @(8, 16) -notcontains $bits -or
+          $sampleRate -lt 8000 -or $sampleRate -gt 48000 -or
+          $alignment -ne $channels * ($bits / 8) -or $rate -ne $sampleRate * $alignment) { throw "SOUND_FAILED" }
+      $hasFormat = $true
+    } elseif ($tag -ceq "data") {
+      if (-not $hasFormat -or $hasData -or $size -eq 0) { throw "SOUND_FAILED" }
+      $dataSize = $size
+      $hasData = $true
+    }
+    $offset = [int]$end
+  }
+  if (-not $hasFormat -or -not $hasData -or $dataSize % $alignment -ne 0 -or
+      $dataSize -gt [long]$rate * 5) { throw "SOUND_FAILED" }
+}
+
+function Read-LocalWave {
+  param([string]$Path)
+  Assert-SoundPath $Path
+  # 拒絕網路磁碟及每一層 reparse point，避免一般 junction／symlink 指向遠端。
+  $fullPath = [IO.Path]::GetFullPath($Path)
+  $drive = [IO.DriveInfo]::new([IO.Path]::GetPathRoot($fullPath))
+  if ($drive.DriveType -ne [IO.DriveType]::Fixed) { throw "SOUND_FAILED" }
+  # 由磁碟根目錄往下檢查，不能先存取可能經由 junction 指向遠端的完整路徑。
+  $root = [IO.Path]::GetPathRoot($fullPath)
+  $current = $root
+  $parts = @("") + ($fullPath.Substring($root.Length) -split '\\')
+  foreach ($part in $parts) {
+    if ($part.Length -gt 0) { $current = [IO.Path]::Combine($current, $part) }
+    $attributes = [IO.File]::GetAttributes($current)
+    if (($attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0 -or
+        ($current -eq $fullPath -and ($attributes -band [IO.FileAttributes]::Directory) -ne 0)) { throw "SOUND_FAILED" }
+  }
+  $stream = $null
+  try {
+    # 開啟後不允許其他程序寫入或刪除；只從同一個 handle 讀入有界記憶體。
+    $stream = [IO.FileStream]::new($fullPath, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::Read)
+    if ($stream.Length -lt 44 -or $stream.Length -gt 5242880) { throw "SOUND_FAILED" }
+    $bytes = New-Object byte[] ([int]$stream.Length)
+    $offset = 0
+    while ($offset -lt $bytes.Length) {
+      $count = $stream.Read($bytes, $offset, $bytes.Length - $offset)
+      if ($count -eq 0) { throw "SOUND_FAILED" }
+      $offset += $count
+    }
+    Assert-Wave $bytes
+    # PowerShell 不可逐 byte 展開管線，保持 byte[] 型別。
+    return ,$bytes
+  } finally {
+    if ($null -ne $stream) { $stream.Dispose() }
+  }
+}
+
+function Play-LocalWave {
+  param([string]$Path)
+  $bytes = Read-LocalWave $Path
+  $memory = $null
+  $player = $null
+  try {
+    $memory = [IO.MemoryStream]::new($bytes, $false)
+    $player = [System.Media.SoundPlayer]::new($memory)
+    $player.Load()
+    $player.PlaySync()
+  } finally {
+    if ($null -ne $player) { $player.Dispose() }
+    if ($null -ne $memory) { $memory.Dispose() }
+  }
+}