pi-windows-notifier 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-windows-notifier contributors
+
+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,137 @@
-# Temporary Holding Version
+# pi-windows-notifier
 
-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.
+Pi 的 Windows 本機通知 extension：需要授權、回答結構化問題，或整次模型回應結束時，提交右下角 Toast 並播放系統提示音。
+
+**Windows-only、零額外 runtime dependencies、沒有網路通知。** 只觀察事件，不批准權限、不代答，不改寫第三方工具。
+
+## 環境與安裝
+
+- Windows 10／11、64 位元 Node.js 22.19+（x64 或 arm64）。
+- Pi 1.1.0+；開發型別檢查使用 1.1.0。舊版事件 API 不支援，沒有 fallback。
+- 僅互動式 TUI。RPC、print、JSON、非 Windows、32 位元 Node 停用通知，載入不拋錯。
+- 使用 Windows 內建 Windows PowerShell 5.1；不需要 ffplay、node-notifier 或另外下載 executable。
+
+單次載入，不修改 Pi 設定：
+
+```bash
+pi -e D:/Pi/pi-windows-notifier
+```
+
+確認後，可自行安裝本地 package：
+
+```bash
+pi install D:/Pi/pi-windows-notifier
+```
+
+目前只有本地 repository，未發布 npm，也沒有自動安裝到你的 Pi。使用此 package 不需要安裝開發依賴；只有開發與測試才需要 `npm ci --ignore-scripts`。
+
+## 提醒事件
+
+| 事件 | Toast 標題／內容 | 提示音 |
+|---|---|---|
+| permission | Pi／需要權限確認 | Exclamation |
+| question | Pi／有問題等待回答 | Exclamation |
+| completed | Pi／回應已完成 | Asterisk |
+| aborted | Pi／回應已中止 | Exclamation |
+| failed | Pi／回應失敗 | Exclamation |
+
+- **權限**：訂閱 `@gotgenes/pi-permission-system` 的 `permissions:ui_prompt`；自動 allow／deny、session approval 不提醒。支援轉送到父 session 的 subagent 詢問。
+- **提問**：支援 `ask_user_question`（包含 RPIV Lean）與 `plan_mode_question`。追蹤工具執行及真正等待 UI 的訊號，一次 questionnaire 只提醒一次，不按題數重複。
+- **回應結束**：僅在 `agent_settled` 發送。重試／續跑尚未結束時不報完成或失敗；重試成功只報完成，單一工具失敗不等於模型失敗。
+- 不辨識普通文字中的問句，不提醒單純手動設定 UI。不論終端是否在前景都提醒。
+- 提問與權限套件是可選整合來源，不是本 package 的 dependencies；沒有安裝時，回應結束通知仍可使用。
+
+### 提問辨識邊界
+
+Pi 的 UI 事件不含 toolCallId。只有恰好一個支援的提問工具正在執行，且沒有權限／已知不明 UI 佔用時才分類；不明時略過並記錄 `UI_AMBIGUOUS`，不攔截第三方 UI。另一個 UI 在提問 call 期間首次開啟時仍可能無法分辨，**不承諾任意並行 UI 的精確歸屬**。
+
+`rpiv:ask-user:blocked` 是補充訊號，與共通 UI 共用去重。第三方套件可能自行發出 terminal bell；那不是本 package 的第二次音效，請使用該套件／終端自身的設定調整。
+
+## 設定
+
+唯一位置：`~/.pi/agent/pi-windows-notifier/config.json`。
+
+不讀專案設定，不建立／自動修改檔案，不移植舊套件設定。沒有檔案時預設全部開啟：
+
+```json
+{
+  "enabled": true,
+  "events": {
+    "permission": { "enabled": true, "sound": true },
+    "question": { "enabled": true, "sound": true },
+    "completed": { "enabled": true, "sound": true },
+    "aborted": { "enabled": true, "sound": true },
+    "failed": { "enabled": true, "sound": true }
+  }
+}
+```
+
+可以只提供要修改的欄位，例如完成時靜音：
+
+```json
+{ "events": { "completed": { "sound": false } } }
+```
+
+總開關 `enabled` 與事件 `enabled` 控制提交；`sound` 只控制 package 音效。runtime 驗證所有欄位，拒絕未知欄位，檔案上限 16 KiB。讀取／解析／驗證失敗時 **fail closed**，停用通知並顯示固定診斷碼，不輸出原始設定。
+
+修改後執行 `/windows-notifier reload`，取消舊工作並重新讀取，不寫設定。
+
+## 指令
+
+```text
+/windows-notifier status
+/windows-notifier reload
+/windows-notifier test
+/windows-notifier test permission
+/windows-notifier test question
+/windows-notifier test completed
+/windows-notifier test aborted
+/windows-notifier test failed
+```
+
+`test` 預設為 completed，**會產生真實彈窗與提示音**，與自動通知共用開關、佇列、限流，不能繞過 disabled。`status` 只顯示有效開關、backend 狀態、佇列／丟棄數與固定診斷碼，不含工作內容。
+
+## 安全與資源限制
+
+- 通知不含問題原文、命令、路徑、session 名稱、模型回答或錯誤原文。沒有 recap、遙測、外部通知服務或模型可呼叫的通知工具。
+- SystemRoot／windir 僅來自啟動 OS 環境；拒絕相對、UNC、device 路徑，PowerShell 使用絕對路徑，不搜尋 cwd／PATH。
+- `spawn` 不開 shell，使用固定 package cwd／腳本、`-NoProfile`、`-NonInteractive`、`-STA`。child environment 僅允許必要 Windows 路徑欄位，不繼承整份 agent environment 或 API tokens。
+- stdin 僅含事件 enum 與音效 boolean；helper 再驗證，從固定字串表生成 DOM text node，不拼接 XML／PowerShell，不使用 Invoke-Expression。
+- `-ExecutionPolicy Bypass` 只限該 child；不取得管理員權限、不更改永久設定，也不把 Execution Policy 當安全邊界。
+- 最多一個 helper、佇列上限 16、啟動至少間隔一秒、等待上限 30 秒。權限／提問優先；滿載先丟棄最舊回應結束項目，否則丟棄最舊等待項目。
+- child timeout 10 秒，stdout／stderr 各最多 8 KiB；只終止自有 child，不按名稱殺程序，不無限重試。若 OS 拒絕終止，等待 close，寧可暫停後續通知，不啟動第二個 helper。
+- 決策、問題結束、新 run、reload、session 重建及 shutdown 取消相應舊工作。已展示的 Toast 不撤回；程序啟動與 Windows 提交仍有取消競態。
+- 不支援背景音樂、自訂音效／音量、遠端通知、定期催答或點擊 Toast 後的自動操作。
+
+**威脅模型**：防護不可信專案內容與事件資料；假設 Windows 系統目錄、啟動 OS 環境與安裝的 package 可信。不防禦惡意同程序 extension、被竄改的 SystemRoot 或遭入侵帳號。Pi permission system 不是 extension 的 OS 沙盒。
+
+## Windows 限制與排錯
+
+使用固定 `Microsoft.Windows.PowerShell` AppID，不寫 registry 或捷徑，來源可能顯示 **PowerShell**，文字標示 Pi。Toast 音效 silent，SystemSounds 分開播放，避免 backend 自己重複播放；沒有 NotifyIcon balloon、Console.Beep 或外部播放器 fallback。
+
+勿擾、Windows／PowerShell 通知設定、系統音效方案與靜音有最終控制權。**「已提交」不保證看見彈窗或聽到聲音**；played 只表示音效 API 呼叫成功。Toast 失敗仍嘗試音效，部分成功會如實回報。
+
+| 診斷碼 | 意義 |
+|---|---|
+| CONFIG_INVALID／CONFIG_TOO_LARGE／CONFIG_READ_FAILED | 修正全域設定後 reload |
+| ENV_UNSUPPORTED | 目前不是支援的 Windows 64 位元 TUI |
+| BACKEND_UNAVAILABLE | SystemRoot／PowerShell／helper 不可用 |
+| UI_AMBIGUOUS／TOOLS_LIMIT | 歸屬不明或追蹤上限，保守略過 |
+| QUEUE_DROPPED | 滿載丟棄 |
+| HELPER_TIMEOUT／OUTPUT_LIMIT／LAUNCH_FAILED | 超時、輸出超限或啟動失敗 |
+| TOAST_FAILED／SOUND_FAILED／BOTH_FAILED | Windows 提交／音效失敗 |
+| INPUT_INVALID／INTERNAL_ERROR／HELPER_PROTOCOL | helper 協定不符，檢查安裝完整性 |
+
+自動錯誤最多每分鐘一次固定 TUI 警告，累計診斷在 status，不顯示原始 stderr。
+
+## 開發與驗證
+
+```bash
+npm ci --ignore-scripts
+npm run verify
+npm pack --dry-run
+```
+
+Node test runner 搭配假時鐘、假 event bus 與 mock launcher。Windows 額外執行 PowerShell 語法解析及無效輸入路徑，**一般 npm test 不發 Toast、不播放音效**。成功路徑的可見通知驗收另行確認，詳見 [驗證紀錄](docs/verification.md)。
+
+MIT；來源與上游授權見 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。上游 checkout 位於 package 外部，不發布；沒有複製 pi-jingle 程式或音效，沒有引入 UniPi core。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# 上游來源與授權
+
+## pi-permission-windows-notifier
+
+- 來源：https://github.com/zhangyu-ch/pi-permission-windows-notifier
+- 參考：988decb1a28a38a6d5b8aa940ec2ceca22088c54
+- 範圍：權限事件、WinRT DOM text node、固定 PowerShell AppID、系統音效及 Toast silent。
+- 本 package 重寫執行檔定位、stdin 協定、資源限制、取消、設定與狀態機。沿用／改作片段保留以下原始 MIT 授權：
+
+```text
+MIT License
+
+Copyright (c) 2026 Yu Zhang
+
+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.
+```
+
+## 其他研究參考
+
+- UniPi notify：https://github.com/Neuron-Mr-White/UniPi/tree/main/packages/notify，參考 6ac5da3。只參考事件／backend 分層概念，未複製程式碼或引入 UniPi core／node-notifier。
+- pi-jingle：https://github.com/Git-Monke/pi-jingle，參考 7e265ce。只參考事件音效概念，未複製程式碼或音效，因為尚未確認其授權。
+- Pi、permission system、RPIV／Lean、Plan mode 的本機型別及原始碼用於核對契約，不把第三方程式碼放入發布包。
+
+本地上游 checkout 位於 `../references/upstream/`，不受此 repository 管理。

package/docs/verification.md

@@ -0,0 +1,26 @@
+# 驗證紀錄
+
+## 自動檢查
+
+- 本機 Windows、Node.js 24.18.0；開發型別依賴 Pi 1.1.0。
+- TypeScript noEmit 與 Node test runner 通過：32 個測試，0 失敗、0 跳過。
+- extension 入口可由 Node TypeScript strip-types 匯入；factory 未在此檢查中執行。
+- npm pack --dry-run 通過，發布清單為 13 個核准檔案，不產生／發布 tarball。
+- Windows PowerShell 語法解析與無效輸入路徑已執行，不呼叫 Toast 或音效。
+- mock 接線涵蓋 permission、RPIV／Lean、Plan mode 及完成／中止／失敗。
+- 涵蓋去重、取消、不明 UI、重試／續跑、空 run、開關、最小 payload、cwd／PATH 污染防護、佇列／輸出上限、timeout、reload／shutdown 清理。
+- 開發依賴使用 npm install --ignore-scripts；當次 npm audit 回報 0 個已知漏洞，不代表完整供應鏈或 OS 安全稽核。
+- 發布包只允許 metadata、runtime 原始碼、固定 helper、README、驗證文件及授權，不含 node_modules、測試、設定或上游 checkout。
+
+## 實機驗收狀態
+
+已經使用者明確同意，透過正式 scheduler／backend 依序執行 permission、question、completed、aborted、failed 五種成功路徑。五次皆回傳 submitted／OK；使用者確認五種都有右下角彈窗與提示音。所有自有 child 等待 close 後結束，沒有安裝套件或變更 Windows／Pi 設定。
+
+以下仍未完成實機端到端驗收：
+
+1. 真實互動式 Pi 的 permission ask、RPIV Lean、Plan mode、正常結束、Esc 及模型失敗（目前為 mock 接線驗證）。
+2. 第三方 terminal bell 是否造成額外聲響。
+3. 勿擾／通知關閉／靜音行為。
+4. 不同 extension 載入順序、reload、OS 程序監看及網路活動觀察（資源限制已由自動測試覆蓋）。
+
+mock 通過不能替代以上場景；一般提交成功不代表保證送達。這次可見／可聽 backend 結果由使用者確認，不能推論所有 Windows 環境皆通過。未自動安裝到使用者 Pi、未變更通知設定、未發布 npm 或 push。

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "pi-windows-notifier",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pi 的 Windows Toast 與系統提示音：權限、結構化提問及回應結束通知。",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "windows",
+    "notifications"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "src/windows-notify.ps1",
+    "README.md",
+    "docs/verification.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "^22.15.3",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "verify": "npm run check && npm test"
+  }
+}

package/src/config.ts

@@ -0,0 +1,70 @@
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { KINDS, isRecord, type NotificationKind } from "./types.ts";
+
+export interface EventConfig { enabled: boolean; sound: boolean }
+export interface Config {
+  enabled: boolean;
+  events: Record<NotificationKind, EventConfig>;
+}
+export type ConfigResult =
+  | { ok: true; config: Config }
+  | { ok: false; code: "CONFIG_INVALID" | "CONFIG_TOO_LARGE" | "CONFIG_READ_FAILED"; config: Config };
+
+export function defaults(): Config {
+  return { enabled: true, events: Object.fromEntries(KINDS.map(kind =>
+    [kind, { enabled: true, sound: true }])) as Config["events"] };
+}
+function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).every(key => keys.includes(key));
+}
+export function parseConfig(value: unknown): ConfigResult {
+  const config = defaults();
+  const invalid = (): ConfigResult => ({ ok: false, code: "CONFIG_INVALID", config: { ...defaults(), enabled: false } });
+  if (!isRecord(value) || !onlyKeys(value, ["enabled", "events"])) return invalid();
+  if (Object.hasOwn(value, "enabled")) {
+    if (typeof value.enabled !== "boolean") return invalid();
+    config.enabled = value.enabled;
+  }
+  if (Object.hasOwn(value, "events")) {
+    if (!isRecord(value.events) || !onlyKeys(value.events, KINDS)) return invalid();
+    for (const kind of KINDS) {
+      if (!Object.hasOwn(value.events, kind)) continue;
+      const item = value.events[kind];
+      if (!isRecord(item) || !onlyKeys(item, ["enabled", "sound"])) return invalid();
+      for (const field of ["enabled", "sound"] as const) {
+        if (!Object.hasOwn(item, field)) continue;
+        if (typeof item[field] !== "boolean") return invalid();
+        config.events[kind][field] = item[field];
+      }
+    }
+  }
+  return { ok: true, config };
+}
+export const CONFIG_LIMIT = 16 * 1024;
+export function configPath(): string {
+  return join(homedir(), ".pi", "agent", "pi-windows-notifier", "config.json");
+}
+export function loadConfig(path = configPath()): ConfigResult {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "r");
+    if (!fstatSync(fd).isFile()) throw new Error("not a file");
+    const buffer = Buffer.alloc(CONFIG_LIMIT + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const count = readSync(fd, buffer, size, buffer.length - size, null);
+      if (count === 0) break;
+      size += count;
+    }
+    if (size > CONFIG_LIMIT) return { ok: false, code: "CONFIG_TOO_LARGE", config: { ...defaults(), enabled: false } };
+    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() };
+    return { ok: false, code: "CONFIG_READ_FAILED", config: { ...defaults(), enabled: false } };
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { registerNotifier as default } from "./runtime.ts";

package/src/launcher.ts

@@ -0,0 +1,143 @@
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { statSync } from "node:fs";
+import { dirname, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isRecord, type NotificationKind } from "./types.ts";
+
+export const HELPER_TIMEOUT = 10_000;
+export const OUTPUT_LIMIT = 8 * 1024;
+export type LaunchCode = "OK" | "TOAST_FAILED" | "SOUND_FAILED" | "BOTH_FAILED" |
+  "INPUT_INVALID" | "INTERNAL_ERROR" | "BACKEND_UNAVAILABLE" | "LAUNCH_FAILED" |
+  "HELPER_TIMEOUT" | "OUTPUT_LIMIT" | "HELPER_PROTOCOL" | "CANCELLED";
+export interface LaunchResult {
+  code: LaunchCode;
+  toast: boolean;
+  sound: "played" | "disabled" | "failed";
+}
+export interface Backend {
+  available: boolean;
+  code: string;
+  launch(kind: NotificationKind, sound: boolean, signal: AbortSignal): Promise<LaunchResult>;
+}
+const SCRIPT = fileURLToPath(new URL("./windows-notify.ps1", import.meta.url));
+const ENV_KEYS = ["SystemRoot", "windir", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "TEMP", "TMP", "USERNAME", "USERDOMAIN"];
+const HELPER_CODES = new Set(["OK", "TOAST_FAILED", "SOUND_FAILED", "BOTH_FAILED", "INPUT_INVALID", "INTERNAL_ERROR"]);
+
+/** 僅信任啟動 Pi 的 OS 環境；專案設定與 PATH 不能參與執行檔定位。 */
+export function windowsPaths(env: NodeJS.ProcessEnv): { executable: string; env: NodeJS.ProcessEnv } | undefined {
+  const get = (key: string): string | undefined => {
+    const actual = Object.keys(env).find(item => item.toLowerCase() === key.toLowerCase());
+    return actual ? env[actual] : undefined;
+  };
+  const root = get("SystemRoot") ?? get("windir");
+  if (!root || !/^[a-z]:[\\/]/iu.test(root) || /[<>:"|?*\u0000-\u001f]/u.test(root.slice(2))) return undefined;
+  const clean = win32.normalize(root);
+  if (!win32.isAbsolute(clean) || clean.startsWith("\\\\")) return undefined;
+  const result: NodeJS.ProcessEnv = {};
+  for (const key of ENV_KEYS) {
+    const value = get(key);
+    if (value !== undefined) result[key] = value;
+  }
+  result.SystemRoot = clean;
+  result.windir = clean;
+  return { executable: win32.join(clean, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), env: result };
+}
+function failed(code: LaunchCode): LaunchResult { return { code, toast: false, sound: "failed" }; }
+function parseResult(output: Buffer, exitCode: number | null, sound: boolean): LaunchResult {
+  try {
+    const parsed: unknown = JSON.parse(output.toString("utf8").trim());
+    if (!isRecord(parsed) || Object.keys(parsed).length !== 3 ||
+        typeof parsed.code !== "string" || !HELPER_CODES.has(parsed.code) || typeof parsed.toast !== "boolean" ||
+        typeof parsed.sound !== "string" || !["played", "disabled", "failed"].includes(parsed.sound)) return failed("HELPER_PROTOCOL");
+    const code = parsed.code as LaunchCode;
+    const audio = parsed.sound as LaunchResult["sound"];
+    const expected = parsed.toast
+      ? (audio === "failed" ? "SOUND_FAILED" : "OK")
+      : (audio === "failed" ? "BOTH_FAILED" : "TOAST_FAILED");
+    if (audio === "disabled" && sound || audio === "played" && !sound) return failed("HELPER_PROTOCOL");
+    if (["INPUT_INVALID", "INTERNAL_ERROR"].includes(code)) {
+      return !parsed.toast && audio === "failed" && exitCode !== 0 ? failed(code) : failed("HELPER_PROTOCOL");
+    }
+    if (code !== expected || exitCode !== (code === "OK" ? 0 : 1)) return failed("HELPER_PROTOCOL");
+    return { code, toast: parsed.toast, sound: audio };
+  } catch { return failed("HELPER_PROTOCOL"); }
+}
+export interface BackendOptions {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  arch?: string;
+  scriptPath?: string;
+  isFile?: (path: string) => boolean;
+  spawnProcess?: (file: string, args: string[], options: SpawnOptions) => ChildProcess;
+  timeoutMs?: number;
+}
+export function createWindowsBackend(options: BackendOptions = {}): Backend {
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const paths = windowsPaths(options.env ?? process.env);
+  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);
+  const spawnProcess = options.spawnProcess ?? spawn;
+  const code = available ? "OK" : "BACKEND_UNAVAILABLE";
+  return {
+    available, code,
+    launch(kind, sound, signal) {
+      if (!available || !paths) return Promise.resolve(failed("BACKEND_UNAVAILABLE"));
+      if (signal.aborted) return Promise.resolve(failed("CANCELLED"));
+      return new Promise(resolve => {
+        let child: ChildProcess;
+        try {
+          child = spawnProcess(paths.executable,
+            ["-NoLogo", "-NoProfile", "-NonInteractive", "-STA", "-ExecutionPolicy", "Bypass", "-File", script],
+            { shell: false, windowsHide: true, cwd: dirname(script), env: { ...paths.env }, stdio: ["pipe", "pipe", "pipe"] });
+        } catch { resolve(failed("LAUNCH_FAILED")); return; }
+        let reason: LaunchCode | undefined;
+        let output = Buffer.alloc(0);
+        let stderrSize = 0;
+        let done = false;
+        const stop = (code: LaunchCode) => {
+          if (reason || done) return;
+          reason = code;
+          // Windows 的 kill 只作用於這個 ChildProcess，不搜尋或終止其他同名程序。
+          try { child.kill(); } catch { /* 保留有界輸出並等待 close，不允許再啟動第二個 helper。 */ }
+        };
+        const onAbort = () => stop("CANCELLED");
+        const timer = setTimeout(() => stop("HELPER_TIMEOUT"), options.timeoutMs ?? HELPER_TIMEOUT);
+        timer.unref();
+        signal.addEventListener("abort", onAbort, { once: true });
+        const finish = (result: LaunchResult) => {
+          if (done) return;
+          done = true;
+          clearTimeout(timer);
+          signal.removeEventListener("abort", onAbort);
+          resolve(result);
+        };
+        child.on("error", () => {
+          reason ??= "LAUNCH_FAILED";
+          // spawn 失敗會有 close；等待它以免提前釋放單一 helper 的配額。
+        });
+        child.stdout?.on("data", (chunk: Buffer | string) => {
+          if (reason) return;
+          const bytes = Buffer.from(chunk);
+          if (output.length + bytes.length > OUTPUT_LIMIT) { stop("OUTPUT_LIMIT"); return; }
+          output = Buffer.concat([output, bytes]);
+        });
+        child.stderr?.on("data", (chunk: Buffer | string) => {
+          if (reason) return;
+          stderrSize += Buffer.byteLength(chunk);
+          if (stderrSize > OUTPUT_LIMIT) stop("OUTPUT_LIMIT");
+          // 不保存或展示 PowerShell 的原始錯誤文字。
+        });
+        child.once("close", exitCode => finish(reason ? failed(reason) : parseResult(output, exitCode, sound)));
+        child.stdin?.on("error", () => stop("LAUNCH_FAILED"));
+        child.stdout?.on("error", () => stop("LAUNCH_FAILED"));
+        child.stderr?.on("error", () => stop("LAUNCH_FAILED"));
+        try { child.stdin?.end(JSON.stringify({ kind, sound })); }
+        catch { stop("LAUNCH_FAILED"); }
+        if (signal.aborted) onAbort();
+      });
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,160 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defaults, loadConfig, type ConfigResult } from "./config.ts";
+import { createWindowsBackend, windowsPaths, type Backend } from "./launcher.ts";
+import { NotificationScheduler, systemClock, type Clock, type Submission } from "./scheduler.ts";
+import { NotificationState } from "./state.ts";
+import { KINDS, type NotificationKind } from "./types.ts";
+
+export interface RuntimeOptions {
+  platform?: NodeJS.Platform;
+  arch?: string;
+  readConfig?: () => ConfigResult;
+  backend?: () => Backend;
+  clock?: Clock;
+}
+interface Session {
+  context: ExtensionContext;
+  state: NotificationState;
+  scheduler?: NotificationScheduler;
+  result: ConfigResult;
+  backendCode: string;
+  diagnostics: Set<string>;
+  unsubscribe: Array<() => void>;
+  disposed: boolean;
+  lastWarning: number;
+  testId: number;
+}
+const SUBMISSION_MESSAGES: Record<Submission["status"], string> = {
+  submitted: "Windows 通知已提交；實際顯示與音效仍由 Windows 設定決定。",
+  partial: "Windows 通知僅部分提交；請用 status 查看固定診斷碼。",
+  disabled: "通知已停用，或目前不支援此環境／事件。",
+  cancelled: "測試通知已取消。",
+  dropped: "測試通知因佇列滿載而被丟棄。",
+  expired: "測試通知已過期。",
+  failed: "Windows 通知提交失敗；請用 status 查看固定診斷碼。",
+};
+
+/** factory 只註冊 API；程序、timer 與 event bus 訂閱皆屬於啟動後的 session。 */
+export function registerNotifier(pi: ExtensionAPI, options: RuntimeOptions = {}): void {
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  // 僅捕捉必要 OS 環境，不保留 agent 的完整環境或 API token。
+  const environment = windowsPaths(process.env)?.env ?? {};
+  const makeBackend = options.backend ?? (() => createWindowsBackend({ env: environment, platform, arch }));
+  const readConfig = options.readConfig ?? loadConfig;
+  const clock = options.clock ?? systemClock;
+  let session: Session | undefined;
+  let lifecycle = Promise.resolve();
+  // reload／session start／shutdown 必須串行，避免前一個 helper 尚未 close 就建立新 session。
+  const transition = (action: () => Promise<void>) => {
+    const next = lifecycle.then(action);
+    lifecycle = next.catch(() => {});
+    return next;
+  };
+
+  const diagnose = (target: Session, code: string) => {
+    if (target.disposed) return;
+    if (target.diagnostics.size < 32) target.diagnostics.add(code);
+    const now = clock.now();
+    try {
+      if (target.context.mode !== "tui" || !target.context.hasUI || now - target.lastWarning < 60_000) return;
+      target.lastWarning = now;
+      target.context.ui.notify(`Windows notifier：${code}。可用 /windows-notifier status 查看狀態。`, "warning");
+    } catch { /* session 更換時的 stale context／UI 不影響 agent。 */ }
+  };
+  const stop = async () => {
+    const previous = session;
+    session = undefined;
+    if (!previous) return;
+    previous.disposed = true;
+    for (const unsubscribe of previous.unsubscribe) { try { unsubscribe(); } catch {} }
+    previous.unsubscribe = [];
+    previous.state.reset();
+    await previous.scheduler?.close();
+  };
+  const start = async (context: ExtensionContext) => {
+    await stop();
+    let result: ConfigResult;
+    try { result = readConfig(); }
+    catch { result = { ok: false, code: "CONFIG_READ_FAILED", config: { ...defaults(), enabled: false } }; }
+    const eligible = platform === "win32" && ["x64", "arm64"].includes(arch) && context.mode === "tui" && context.hasUI;
+    let backend: Backend | undefined;
+    try { if (eligible) backend = makeBackend(); } catch { /* 不展示 backend 原始錯誤。 */ }
+    const target: Session = {
+      context, state: undefined!, result, backendCode: eligible ? backend?.code ?? "BACKEND_UNAVAILABLE" : "ENV_UNSUPPORTED",
+      diagnostics: new Set(), unsubscribe: [], disposed: false, lastWarning: -Infinity, testId: 0,
+    };
+    const scheduler = backend && eligible
+      ? new NotificationScheduler(backend, () => target.result.config, code => diagnose(target, code), clock) : undefined;
+    target.scheduler = scheduler;
+    target.state = new NotificationState(scheduler ?? { enqueue() {}, cancel() {} }, code => diagnose(target, code));
+    session = target;
+    if (!result.ok) diagnose(target, result.code);
+    if (eligible && !backend?.available) diagnose(target, "BACKEND_UNAVAILABLE");
+    if (!eligible) return;
+    const listen = (channel: string, handler: (raw: unknown) => void) => {
+      target.unsubscribe.push(pi.events.on(channel, raw => {
+        if (target.disposed || session !== target) return;
+        try { handler(raw); } catch { diagnose(target, "EVENT_INVALID"); }
+      }));
+    };
+    listen("permissions:ui_prompt", raw => target.state.permissionPrompt(raw));
+    listen("permissions:decision", raw => target.state.permissionDecision(raw));
+    listen("rpiv:ask-user:blocked", raw => target.state.rpivBlocked(raw));
+  };
+  const observe = (handler: (state: NotificationState) => void) => {
+    const target = session;
+    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_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)); });
+  pi.on("ui_prompt_start", () => { observe(state => state.uiStart()); });
+  pi.on("ui_prompt_end", () => { observe(state => state.uiEnd()); });
+  pi.on("agent_start", () => { observe(state => state.agentStart()); });
+  pi.on("message_end", event => { observe(state => state.messageEnd(event)); });
+  pi.on("turn_end", event => { observe(state => state.boundary(event)); });
+  pi.on("agent_before_settle", event => { observe(state => state.boundary(event)); });
+  pi.on("agent_settled", event => { observe(state => state.settled(event)); });
+
+  pi.registerCommand("windows-notifier", {
+    description: "Windows 通知：status、reload、test [permission|question|completed|aborted|failed]",
+    handler: async (args, context) => {
+      const parts = args.trim().split(/\s+/u);
+      if (parts.length === 1 && parts[0] === "reload") {
+        await transition(() => start(context));
+        context.ui.notify("Windows notifier 設定已重新載入；請用 status 查看有效狀態。", "info");
+        return;
+      }
+      const target = session;
+      if (!args.trim() || parts.length === 1 && parts[0] === "status") {
+        const status = {
+          backend: target?.backendCode ?? "NOT_STARTED",
+          enabled: target?.result.config.enabled ?? false,
+          events: target?.result.config.events,
+          ...target?.scheduler?.status(),
+          diagnostics: [...(target?.diagnostics ?? [])],
+        };
+        context.ui.notify(JSON.stringify(status), "info");
+        return;
+      }
+      if (parts[0] === "test" && parts.length <= 2 &&
+          (parts[1] === undefined || KINDS.includes(parts[1] as NotificationKind))) {
+        if (!target?.scheduler || target.disposed) {
+          context.ui.notify(SUBMISSION_MESSAGES.disabled, "warning");
+          return;
+        }
+        const result = await target.scheduler.submit({ key: "test:" + ++target.testId,
+          kind: (parts[1] ?? "completed") as NotificationKind,
+          valid: () => session === target && !target.disposed });
+        // reload／session 切換後不再使用已失效的 command context。
+        if (session === target && !target.disposed) context.ui.notify(SUBMISSION_MESSAGES[result.status],
+          result.status === "submitted" ? "info" : "warning");
+        return;
+      }
+      context.ui.notify("用法：/windows-notifier status | reload | test [permission|question|completed|aborted|failed]", "warning");
+    },
+  });
+}

package/src/scheduler.ts

@@ -0,0 +1,137 @@
+import type { Config } from "./config.ts";
+import type { Backend, LaunchResult } from "./launcher.ts";
+import type { Diagnostic, NotificationJob } from "./types.ts";
+
+export interface Clock {
+  now(): number;
+  set(fn: () => void, delay: number): unknown;
+  clear(handle: unknown): void;
+}
+export const systemClock: Clock = {
+  now: () => performance.now(),
+  set: (fn, delay) => { const timer = setTimeout(fn, delay); timer.unref(); return timer; },
+  clear: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+export interface Submission {
+  status: "submitted" | "partial" | "disabled" | "cancelled" | "dropped" | "expired" | "failed";
+  code?: string;
+}
+interface Pending {
+  job: NotificationJob;
+  created: number;
+  resolve(result: Submission): void;
+}
+export const QUEUE_LIMIT = 16;
+export const MIN_INTERVAL = 1_000;
+export const QUEUE_TTL = 30_000;
+const waiting = (job: NotificationJob) => job.kind === "permission" || job.kind === "question";
+
+/** 單一 helper、有界佇列、過期取消；所有 promise 都以固定狀態結束，不外洩原始錯誤。 */
+export class NotificationScheduler {
+  private backend: Backend;
+  private config: () => Config;
+  private diagnose: Diagnostic;
+  private clock: Clock;
+  private queue: Pending[] = [];
+  private timer: unknown;
+  private lastStart = -Infinity;
+  private active: { key: string; abort: AbortController; finished: Promise<void> } | undefined;
+  private closed = false;
+  dropped = 0;
+
+  constructor(backend: Backend, config: () => Config, diagnose: Diagnostic = () => {}, clock: Clock = systemClock) {
+    this.backend = backend;
+    this.config = config;
+    this.diagnose = diagnose;
+    this.clock = clock;
+  }
+  private enabled(job: NotificationJob): boolean {
+    const config = this.config();
+    return !this.closed && this.backend.available && config.enabled && config.events[job.kind].enabled;
+  }
+  private valid(job: NotificationJob): boolean {
+    try { return job.valid(); } catch { return false; }
+  }
+  enqueue(job: NotificationJob): void { void this.submit(job); }
+  submit(job: NotificationJob): Promise<Submission> {
+    if (!this.enabled(job)) return Promise.resolve({ status: "disabled" });
+    if (!this.valid(job)) return Promise.resolve({ status: "cancelled" });
+    if (this.queue.some(item => item.job.key === job.key) || this.active?.key === job.key) {
+      return Promise.resolve({ status: "cancelled" });
+    }
+    this.prune();
+    if (this.queue.length >= QUEUE_LIMIT) {
+      const index = this.queue.findIndex(item => !waiting(item.job));
+      const [removed] = this.queue.splice(index < 0 ? 0 : index, 1);
+      removed.resolve({ status: "dropped" });
+      this.dropped++;
+      this.diagnose("QUEUE_DROPPED");
+    }
+    const result = new Promise<Submission>(resolve => this.queue.push({ job, created: this.clock.now(), resolve }));
+    this.wake();
+    return result;
+  }
+  cancel(key: string): void {
+    this.queue = this.queue.filter(item => {
+      if (item.job.key !== key) return true;
+      item.resolve({ status: "cancelled" });
+      return false;
+    });
+    if (this.active?.key === key) this.active.abort.abort();
+    if (!this.queue.length && this.timer !== undefined) {
+      this.clock.clear(this.timer);
+      this.timer = undefined;
+    }
+  }
+  private prune(): void {
+    const now = this.clock.now();
+    this.queue = this.queue.filter(item => {
+      if (now - item.created >= QUEUE_TTL) { item.resolve({ status: "expired" }); return false; }
+      if (!this.enabled(item.job)) { item.resolve({ status: "disabled" }); return false; }
+      if (!this.valid(item.job)) { item.resolve({ status: "cancelled" }); return false; }
+      return true;
+    });
+  }
+  private wake(): void {
+    if (this.closed || this.active || this.timer !== undefined || !this.queue.length) return;
+    this.timer = this.clock.set(() => { this.timer = undefined; this.start(); },
+      Math.max(0, this.lastStart + MIN_INTERVAL - this.clock.now()));
+  }
+  private start(): void {
+    if (this.closed || this.active) return;
+    this.prune();
+    if (!this.queue.length) return;
+    const index = this.queue.findIndex(item => waiting(item.job));
+    const [item] = this.queue.splice(index < 0 ? 0 : index, 1);
+    const abort = new AbortController();
+    const active = { key: item.job.key, abort, finished: Promise.resolve() };
+    this.active = active;
+    this.lastStart = this.clock.now();
+    active.finished = this.deliver(item, abort.signal).finally(() => {
+      if (this.active === active) this.active = undefined;
+      this.wake();
+    });
+  }
+  private async deliver(item: Pending, signal: AbortSignal): Promise<void> {
+    let result: LaunchResult;
+    try { result = await this.backend.launch(item.job.kind, this.config().events[item.job.kind].sound, signal); }
+    catch { result = { code: "LAUNCH_FAILED", toast: false, sound: "failed" }; }
+    if (signal.aborted || result.code === "CANCELLED") { item.resolve({ status: "cancelled" }); return; }
+    if (result.code !== "OK") this.diagnose(result.code);
+    item.resolve({
+      status: result.code === "OK" ? "submitted" : result.toast || result.sound === "played" ? "partial" : "failed",
+      code: result.code,
+    });
+  }
+  status(): { queued: number; active: boolean; dropped: number } {
+    return { queued: this.queue.length, active: !!this.active, dropped: this.dropped };
+  }
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.timer !== undefined) { this.clock.clear(this.timer); this.timer = undefined; }
+    for (const item of this.queue) item.resolve({ status: "cancelled" });
+    this.queue = [];
+    this.active?.abort.abort();
+    await this.active?.finished;
+  }
+}

package/src/state.ts

@@ -0,0 +1,155 @@
+import { isRecord, safeId, type Diagnostic, type NotificationSink, type Outcome } from "./types.ts";
+
+const QUESTION_TOOLS = new Set(["ask_user_question", "plan_mode_question"]);
+interface Question { name: string; waiting: boolean; notified: boolean }
+
+/** 純觀察狀態機：不回傳工具攔截結果、不保存 arguments 或訊息內容。 */
+export class NotificationState {
+  private sink: NotificationSink;
+  private diagnose: Diagnostic;
+  private seen = new Set<string>();
+  private permissions = new Set<string>();
+  private questions = new Map<string, Question>();
+  private ui: { question?: string } | undefined;
+  private rpivCall: string | undefined;
+  private running = false;
+  private generation = 0;
+  private terminalKey: string | undefined;
+  private assistantSeen = false;
+  private outcome: Outcome | undefined;
+
+  constructor(sink: NotificationSink, diagnose: Diagnostic = () => {}) {
+    this.sink = sink;
+    this.diagnose = diagnose;
+  }
+  permissionPrompt(raw: unknown): void {
+    if (!isRecord(raw) || !safeId(raw.requestId)) { this.diagnose("EVENT_INVALID"); return; }
+    const id = raw.requestId;
+    if (this.seen.has(id)) return;
+    this.seen.add(id);
+    if (this.seen.size > 256) this.seen.delete(this.seen.values().next().value!);
+    this.permissions.add(id);
+    if (this.permissions.size > 256) {
+      const oldest = this.permissions.values().next().value!;
+      this.permissions.delete(oldest);
+      this.sink.cancel("permission:" + oldest);
+    }
+    this.sink.enqueue({ key: "permission:" + id, kind: "permission", valid: () => this.permissions.has(id) });
+  }
+  permissionDecision(raw: unknown): void {
+    if (!isRecord(raw) || !safeId(raw.requestId)) return;
+    this.permissions.delete(raw.requestId);
+    this.sink.cancel("permission:" + raw.requestId);
+  }
+  toolStart(raw: unknown): void {
+    if (!isRecord(raw) || typeof raw.toolName !== "string" || !QUESTION_TOOLS.has(raw.toolName)) return;
+    if (!safeId(raw.toolCallId)) { this.diagnose("EVENT_INVALID"); return; }
+    if (this.questions.has(raw.toolCallId)) return;
+    if (this.questions.size >= 32) { this.diagnose("TOOLS_LIMIT"); return; }
+    this.questions.set(raw.toolCallId, { name: raw.toolName, waiting: false, notified: false });
+  }
+  toolEnd(raw: unknown): void {
+    if (!isRecord(raw) || !safeId(raw.toolCallId)) return;
+    this.sink.cancel("question:" + raw.toolCallId);
+    this.questions.delete(raw.toolCallId);
+    if (this.rpivCall === raw.toolCallId) this.rpivCall = undefined;
+  }
+  private wait(id: string): void {
+    const question = this.questions.get(id);
+    if (!question) return;
+    question.waiting = true;
+    if (question.notified) return;
+    question.notified = true;
+    this.sink.enqueue({ key: "question:" + id, kind: "question",
+      valid: () => this.questions.get(id) === question && question.waiting });
+  }
+  private stopWait(id: string): void {
+    const question = this.questions.get(id);
+    if (question) question.waiting = false;
+    this.sink.cancel("question:" + id);
+  }
+  uiStart(): void {
+    if (this.ui) {
+      if (this.ui.question) this.stopWait(this.ui.question);
+      if (this.rpivCall) this.stopWait(this.rpivCall);
+      this.ui = {};
+      this.diagnose("UI_AMBIGUOUS");
+      return;
+    }
+    this.ui = {};
+    if (this.permissions.size) return;
+    if (this.questions.size !== 1) {
+      if (this.questions.size > 1) this.diagnose("UI_AMBIGUOUS");
+      return;
+    }
+    const id = this.questions.keys().next().value!;
+    this.ui.question = id;
+    this.wait(id);
+  }
+  uiEnd(): void {
+    if (this.ui?.question) this.stopWait(this.ui.question);
+    this.ui = undefined;
+  }
+  rpivBlocked(raw: unknown): void {
+    if (!isRecord(raw) || typeof raw.active !== "boolean") return;
+    if (!raw.active) {
+      if (this.rpivCall) this.stopWait(this.rpivCall);
+      this.rpivCall = undefined;
+      return;
+    }
+    if (this.rpivCall) return;
+    if (this.permissions.size || this.questions.size !== 1 ||
+        (this.ui && !this.ui.question)) { this.diagnose("UI_AMBIGUOUS"); return; }
+    const [id, question] = this.questions.entries().next().value!;
+    if (question.name !== "ask_user_question") return;
+    this.rpivCall = id;
+    this.wait(id);
+  }
+  agentStart(): void {
+    if (this.running) return; // retry／續跑仍屬於同一個邏輯 run。
+    if (this.terminalKey) this.sink.cancel(this.terminalKey);
+    this.terminalKey = undefined;
+    this.running = true;
+    this.generation++;
+    this.assistantSeen = false;
+    this.outcome = undefined;
+  }
+  messageEnd(raw: unknown): void {
+    if (!this.running || !isRecord(raw) || !isRecord(raw.message) || raw.message.role !== "assistant") return;
+    this.assistantSeen = true;
+    this.outcome = raw.message.stopReason === "aborted" ? "aborted" :
+      raw.message.stopReason === "error" ? "error" : "completed";
+  }
+  boundary(raw: unknown): void {
+    if (!this.running || !isRecord(raw)) return;
+    if (raw.outcome === "completed" || raw.outcome === "aborted" || raw.outcome === "error") {
+      this.outcome = raw.outcome;
+    }
+  }
+  settled(raw: unknown): void {
+    if (!this.running || !isRecord(raw) || typeof raw.aborted !== "boolean") return;
+    this.running = false;
+    const kind = raw.aborted || this.outcome === "aborted" ? "aborted" :
+      this.outcome === "error" ? "failed" : this.assistantSeen ? "completed" : undefined;
+    if (!kind) return;
+    const generation = this.generation;
+    const key = "run:" + generation;
+    this.terminalKey = key;
+    this.sink.enqueue({ key, kind, valid: () => this.generation === generation && !this.running });
+  }
+  reset(): void {
+    for (const id of this.permissions) this.sink.cancel("permission:" + id);
+    for (const id of this.questions.keys()) this.sink.cancel("question:" + id);
+    if (this.terminalKey) this.sink.cancel(this.terminalKey);
+    this.seen.clear();
+    this.permissions.clear();
+    this.questions.clear();
+    this.ui = undefined;
+    this.rpivCall = undefined;
+    this.running = false;
+    this.assistantSeen = false;
+    this.outcome = undefined;
+    this.terminalKey = undefined;
+    this.generation++;
+  }
+}

package/src/types.ts

@@ -0,0 +1,21 @@
+export const KINDS = ["permission", "question", "completed", "aborted", "failed"] as const;
+export type NotificationKind = (typeof KINDS)[number];
+export type Outcome = "completed" | "aborted" | "error";
+export interface NotificationJob {
+  key: string;
+  kind: NotificationKind;
+  /** 送出前重新確認事件仍有效，不保留工作內容。 */
+  valid(): boolean;
+}
+export interface NotificationSink {
+  enqueue(job: NotificationJob): void;
+  cancel(key: string): void;
+}
+export type Diagnostic = (code: string) => void;
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function safeId(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 256 &&
+    !/[\u0000-\u001f\u007f]/u.test(value);
+}

package/src/windows-notify.ps1

@@ -0,0 +1,78 @@
+# 固定 helper：stdin 僅接受事件 enum 與音效開關，不接受任意訊息或命令。
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+function Write-Result {
+  param([string]$Code, [bool]$Toast, [string]$Sound)
+  [Console]::Out.WriteLine((@{ code = $Code; toast = $Toast; sound = $Sound } | ConvertTo-Json -Compress))
+}
+
+try {
+  $buffer = New-Object char[] 513
+  $size = 0
+  while ($size -lt $buffer.Length) {
+    $count = [Console]::In.Read($buffer, $size, $buffer.Length - $size)
+    if ($count -eq 0) { break }
+    $size += $count
+  }
+  if ($size -gt 512) { throw "INPUT_INVALID" }
+  $inputData = (-join $buffer[0..($size - 1)]) | ConvertFrom-Json
+  $names = @($inputData.PSObject.Properties.Name)
+  if ($names.Count -ne 2 -or -not ($names -contains "kind") -or -not ($names -contains "sound") -or
+      $inputData.kind -isnot [string] -or $inputData.sound -isnot [bool]) { throw "INPUT_INVALID" }
+  $messages = @{
+    permission = "需要權限確認"
+    question = "有問題等待回答"
+    completed = "回應已完成"
+    aborted = "回應已中止"
+    failed = "回應失敗"
+  }
+  # PowerShell hashtable 預設不區分大小寫，先以 case-sensitive 比較鎖定 enum。
+  if (-not (@("permission", "question", "completed", "aborted", "failed") -ccontains $inputData.kind)) {
+    throw "INPUT_INVALID"
+  }
+}
+catch {
+  Write-Result "INPUT_INVALID" $false "failed"
+  exit 1
+}
+
+$toastOk = $false
+$soundStatus = "disabled"
+try {
+  [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+  [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+  $xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(
+    [Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+  $nodes = $xml.GetElementsByTagName("text")
+  $nodes.Item(0).AppendChild($xml.CreateTextNode("Pi")) | Out-Null
+  $nodes.Item(1).AppendChild($xml.CreateTextNode($messages[$inputData.kind])) | Out-Null
+  $audio = $xml.CreateElement("audio")
+  $audio.SetAttribute("silent", "true")
+  $xml.DocumentElement.AppendChild($audio) | Out-Null
+  $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+  $notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Microsoft.Windows.PowerShell")
+  $notifier.Show($toast)
+  $toastOk = $true
+}
+catch { $toastOk = $false }
+
+if ($inputData.sound) {
+  try {
+    if ($inputData.kind -ceq "completed") { [System.Media.SystemSounds]::Asterisk.Play() }
+    else { [System.Media.SystemSounds]::Exclamation.Play() }
+    $soundStatus = "played"
+    # Play 非同步；有界等待不保證聲音實際送達，也不建立其他播放器。
+    Start-Sleep -Milliseconds 750
+  }
+  catch { $soundStatus = "failed" }
+}
+
+$code = if ($toastOk) {
+  if ($soundStatus -eq "failed") { "SOUND_FAILED" } else { "OK" }
+} else {
+  if ($soundStatus -eq "failed") { "BOTH_FAILED" } else { "TOAST_FAILED" }
+}
+Write-Result $code $toastOk $soundStatus
+if ($code -eq "OK") { exit 0 } else { exit 1 }