pi-watchdog-supervisor 0.1.0

package/.tmp/2026-07-08_pi_watchdog_high_level_spec.md

@@ -0,0 +1,192 @@
+# pi-watchdog-supervisor — High-Level Tech Spec
+
+- Date: 2026-07-08
+- Target reader: RD / coding agent
+- Source requirement: `.tmp/2026-07-08_pi_watchdog_extension_requirement.md`
+- Status: v1 — ready for user review
+- Perspective: SDD（Spec-Driven Development），本文件只定義交付階段、功能目標與驗收標準，不涉及 source-code 層實作細節。
+
+---
+
+## 1. 需求摘要
+
+Pi 的 task sub-agent 可能陷入重複工具迴圈（同 command、同輸出、無新 patch），目前需人工介入。本專案建立一個 Pi extension `pi-watchdog-supervisor`，以三層分工實現自動監督：
+
+```txt
+extension runtime   = 確定性事件收集器 + stuck 偵測器（規則式，非 LLM）
+watchdog sub-agent  = 推理/摘要層，透過 watchdog_* tools 讀取狀態
+main agent          = 最終決策者（收到 alert 後決定是否送出救援訊息）
+```
+
+預設行為：偵測 stuck → alert main agent（`main_only`）→ main agent 決定；**不**自動 kill、**不**自動 steer。
+
+---
+
+## 2. 架構決策（本 spec 新增）
+
+### 2.1 觀察通道：子 session 自我回報 + 共享 state store
+
+API 查證（見 §3）確認：Pi 核心沒有 sub-agent API，extension 只能在自己所在的 session 內運作。但 `@gotgenes/pi-subagents` 的子 agent 會**繼承父 session 的 extensions**，因此：
+
+```txt
+Task Sub-agent Session（子）
+│  pi-watchdog-supervisor extension 也載入於此
+│  ├─ 監聽「自己的」tool_call / tool_result 事件
+│  ├─ 正規化 command、hash output
+│  └─ 寫入共享 state store（以 parent session 為 key 的檔案）
+│         ↓
+Main Agent Session（父）
+│  pi-watchdog-supervisor extension
+│  ├─ 訂閱 subagents:* 生命週期事件（建立 target registry）
+│  ├─ 讀取共享 store，彙整 ring buffer
+│  ├─ 執行確定性 stuck 偵測 + cooldown
+│  └─ 提供 watchdog_* tools 給 watchdog sub-agent
+│         ↓
+Watchdog Sub-agent Session
+   呼叫 watchdog_* tools → 產出 compact alert → main agent
+```
+
+此設計取代了需求文件 §12.3 的「僅追蹤本 session 可見 tool calls」的降級方案，直接解決「watchdog 無法觀察兄弟 sub-agent」的核心約束（§4），且不需輪詢完整對話 log，token 成本低。
+
+### 2.2 資料流圖
+
+```txt
+子 agent tool_call 事件
+    │
+    ▼
+子 session extension instance（normalize + hash）
+    │  append
+    ▼
+共享 state store（JSONL / 檔案，key = parent session id）
+    │  read + aggregate
+    ▼
+父 session extension（ring buffer + 規則偵測 + cooldown）
+    │  watchdog_* tools
+    ▼
+watchdog sub-agent（推理、產出 alert）
+    │  watchdog_alert_main（pi.sendMessage / pi-intercom）
+    ▼
+main agent（決策：steer / restart / ignore）
+```
+
+---
+
+## 3. API 查證結果（解決需求文件 §22 open questions）
+
+查證來源：Pi extensions 官方文件、`@gotgenes/pi-subagents` 與 `pi-intercom` 套件頁（accessed 2026-07-08，URL 見 §8）。
+
+| Open Question | 查證結果 |
+|---|---|
+| Pi 事件名稱 | 已確認：`tool_call`（可 block）、`tool_result`、`tool_execution_start/update/end`、`agent_start/end`、`turn_start/end`、`session_start` 等 |
+| Extension 能否送訊息進 session | 可以，但**僅限自己所在的 session**：`pi.sendMessage(..., { deliverAs: 'steer' \| 'followUp' \| 'nextTurn', triggerTurn })`、`pi.sendUserMessage()` |
+| Pi 核心是否有 sub-agent API | **沒有**。Extension 只在單一 session context 內運作 → 必須依賴 `@gotgenes/pi-subagents` |
+| `@gotgenes/pi-subagents` API 能力 | `getSubagentsService()`、`svc.spawn(type, prompt)`、`steer_subagent(agent_id, message)`、`get_subagent_result(agent_id, wait, verbose)`（verbose 可取完整對話 log）；透過 `pi.events` 發出 `subagents:created/started/completed/failed/steered/compacted` 事件（含 agent id、type、token 數、status） |
+| 跨 session 通訊 | `pi-intercom`：local broker + Unix socket，收件方 idle 時訊息會**觸發新 turn**；另有 subagent 專用 `contact_supervisor` tool（需 pi-subagents） |
+| 父子關係識別 | 子 agent 繼承父的 skills/extensions；權限系統有 `subagents:child:session-created` 可作確定性子 session 偵測 |
+
+### 仍未解之項（留給各 Task 的 low-level spec / 前置 spike）
+
+- `SubagentsService` 完整 method 簽名（需讀套件 `src/service/service.ts` 原始碼）。→ Task02 spike
+- `subagents:*` 事件是否含 per-tool-call 細節（推測不含，故採 §2.1 自我回報架構）。→ Task03 spike
+- 子 session 內的 extension 如何取得 parent session id。→ Task03 spike
+
+---
+
+## 4. Task 拆分
+
+對應需求文件 §17 Milestone 1–6。分類上全部屬於 `03. UI or Core Function`（新 extension 開發，無既有程式碼可 typing/refactor），測試併入各 Task 驗收。
+
+### 估算基準
+
+- `S` 基準 = Task01：extension 骨架 + 指令註冊 + config 載入，Pi 文件有完整範例、無外部整合風險，約 1x。
+- `M` ≈ 2-3x：需整合第三方套件事件或跨多檔案，有中等不確定性。
+- `L` ≈ 4-6x：跨 session 通道，最高的未知數與回歸風險。
+- 倍數為規劃輔助，非時間保證。
+
+### Task01 — Extension skeleton 與設定系統（S）
+
+- 目標：建立 `pi-watchdog-supervisor` package（含 pi manifest）；註冊 `/watchdog status|config|set|pause|resume|inspect` 指令；載入並合併 global（`~/.pi/agent/watchdog-supervisor/config.json`）與 project（`.pi/watchdog-supervisor.json`）config，project 覆蓋 global；定義 `WatchdogConfig` 預設值（含可設定的 rescueMessage）。
+- 驗收：
+  - `pi -e ./src/index.ts` 啟動後 `/watchdog status` 顯示 extension 已載入。
+  - `/watchdog config` 正確反映 global+project 合併結果；`/watchdog set rescueMessage <msg>` 於當前 session 生效。
+  - config merge 有 unit test。
+
+### Task02 — Sub-agent 發現與生命週期追蹤（M）
+
+- 目標：以 optional peer dependency 整合 `@gotgenes/pi-subagents`；訂閱 `subagents:created/started/completed/failed/steered/compacted`；維護 target registry（`WatchdogTarget`）；區分 watchdog / task agent；套件缺席時 extension 仍可載入並顯示降級狀態。
+- 前置 spike：讀 `@gotgenes/pi-subagents` 原始碼確認 `SubagentsService` 簽名與事件 payload。
+- 驗收：
+  - main session 有 2 個 task sub-agent + 1 個 watchdog sub-agent 時，`/watchdog status` 正確列出 3 個 target、kind 與 status。
+  - 未安裝 pi-subagents 時無錯誤，`/watchdog status` 顯示「subagent service unavailable」。
+
+### Task03 — 事件收集：子 session 自我回報 + 共享 store（L）
+
+- 目標：子 session 端 extension instance 監聽自身 `tool_call`/`tool_result`；實作 `normalizeCommand()`（trim、collapse spaces、strip ANSI）與 `hashOutput()`（strip ANSI、truncate、sha256、preview N 行）；寫入以 parent session 為 key 的共享 state store；父 session 端讀取彙整為每 target 的 ring buffer（`maxEventsPerAgent`，預設 200），只存 hash 與 preview，不存完整輸出。
+- 前置 spike：確認子 session 取得 parent session id 的方式；確認 `subagents:*` 事件是否已含 tool 細節（若有，可簡化架構）。
+- 驗收：
+  - 執行中 task sub-agent 的 tool call（含 command key、output hash）出現在父 session 的事件 buffer 中（Task05 後可經 `watchdog_read_events()` 驗證）。
+  - `normalizeCommand()` / `hashOutput()` / ring buffer 有 unit test。
+
+### Task04 — Stuck 偵測器（M）
+
+- 目標：實作規則式偵測：同 command + 同 output hash ≥ `repeatThreshold`（3）；同 typecheck error ≥ 2；`idleNoProgressSec`（300s）內無 edit/patch 但 tools 持續執行；read-only loop。輸出 `likelyStuck` + `confidence` + `reasons` + `evidence`。實作 per-target alert cooldown（60s）與同 evidence key 去重。
+- 驗收：
+  - 模擬同一 `rg` 指令重複 3 次（同輸出）→ `likelyStuck === true`、confidence ≥ medium、evidence 含 `repeated_command`。
+  - cooldown 期間相同 evidence 不重複產生 alert。
+  - 各偵測規則與 cooldown 有 unit test。
+
+### Task05 — Watchdog tools（M）
+
+- 目標：以 `pi.registerTool` 註冊需求文件 §9 全部工具：`watchdog_list_targets`、`watchdog_read_events`、`watchdog_detect_stuck`、`watchdog_alert_main`（優先 `pi.sendMessage` 注入 main session；pi-intercom 為跨 session 備援；最後 fallback UI 通知）、`watchdog_steer_subagent`（預設 `dryRun=true`，實際 steer 走 pi-subagents `steer_subagent`）、`watchdog_config`。輸出 schema 依需求文件 §9 定義。
+- 驗收：
+  - watchdog sub-agent 能呼叫 `watchdog_detect_stuck` 取得 evidence 並產出 §8.2 格式的 compact alert。
+  - `watchdog_alert_main` 的訊息實際出現在 main session。
+  - `watchdog_steer_subagent` 預設 dry-run 不實際送訊息。
+
+### Task06 — Supervisor 工作流與文件（M）
+
+- 目標：提供 watchdog agent prompt（`prompts/watchdog-agent.md`）、watchdog skill（§21）、範例 main-agent 指引（examples/AGENTS.md）；實作 main-agent-driven 輪詢流程（需求文件 §14 Option A）；README 與手動情境測試腳本（dummy loop agent 重複 `rg` 3 次）。
+- 驗收：
+  - 端到端手動測試：dummy task sub-agent 進入迴圈 → watchdog 偵測 → main agent 收到 `[Watchdog Alert]` → main agent 可選擇送出 rescue message（人工確認送達）。
+  - Extension-driven tick（Option B）明確標記為 post-MVP，不在本次交付。
+
+---
+
+## 5. 釋出安全性
+
+每個 Task 完成後皆可獨立釋出，不需等待後續 Task：
+
+- Task01–03 只收集資料、不產生任何 alert 或介入，對現有工作流零影響。
+- Task04–05 預設 `alertMode: "main_only"`、steer 預設 dry-run，不會自動介入 sub-agent。
+- 整體可用 `enabled: false` 或 `/watchdog pause` 一鍵停用。
+
+---
+
+## 6. 風險表（依查證結果更新需求文件 §24）
+
+| Risk | Impact | 變化 | Mitigation |
+|---|---:|---|---|
+| Pi 不暴露 sub-agent 內部 | Medium（原 High） | ↓ 已緩解 | 查證確認子 agent 繼承 extensions → 採自我回報架構（§2.1） |
+| 子 session 無法識別 parent id | Medium | 新增 | Task03 前置 spike；備援：pi-intercom 註冊回報 |
+| `@gotgenes/pi-subagents` API 與文件不符 | Medium | 新增 | Task02 spike 直接讀原始碼；adapter 隔離於 `integrations/` |
+| Watchdog sub-agent 閒置 | Medium | 不變 | MVP 採 main-agent-driven（Option A），Option B 為 post-MVP |
+| 誤報過多 | Medium | 不變 | cooldown、confidence 分級、main agent 最終審批 |
+| 監控造成 token 浪費 | Low（原 Medium） | ↓ | 只存 hash + preview；watchdog 只讀 compact 資料 |
+| 第三方 extension API 變動 | Medium | 不變 | adapter 隔離於 `integrations/` |
+
+---
+
+## 7. Revision History
+
+| Version | Change |
+|---|---|
+| v1 | 初版：API 查證結果 + 觀察通道架構決策 + Task01–06 拆分與驗收標準 |
+
+---
+
+## 8. Reference
+
+- reference01: https://pi.dev/docs/latest/extensions — 事件清單、registerTool/registerCommand、sendMessage/sendUserMessage、無 sub-agent API（accessed 2026-07-08）
+- reference02: https://pi.dev/packages/%40gotgenes/pi-subagents — service API、subagents:* 事件、steering、extension 繼承（accessed 2026-07-08）
+- reference03: https://pi.dev/packages/pi-intercom — broker 架構、turn 觸發、contact_supervisor（accessed 2026-07-08）
+- reference04: `.tmp/2026-07-08_pi_watchdog_extension_requirement.md` — 原始需求文件

package/.tmp/2026-07-08_pi_watchdog_task01_low_level_spec.md

@@ -0,0 +1,234 @@
+# Task01 — Extension Skeleton 與設定系統：Low-Level Detail Spec
+
+- Date: 2026-07-08
+- Target reader: coding agent / implementation engineer
+- Source:
+  - High-level spec: `.tmp/2026-07-08_pi_watchdog_high_level_spec.md`（Task01）
+  - Requirement: `.tmp/2026-07-08_pi_watchdog_extension_requirement.md`（§7.3, §10, §11, §16, §17 Milestone 1, §19）
+- Status: v1 — ready for user review
+- Perspective: TDD（先寫失敗測試，再實作使其通過）
+
+---
+
+## 1. 範圍
+
+### In scope
+
+- `pi-watchdog-supervisor` package 骨架（pi manifest、TypeScript、測試環境）。
+- `WatchdogConfig` 型別、預設值、global + project config 載入與合併（project 覆蓋 global）。
+- Session 層級的 runtime 狀態：`paused` 旗標、session-only `rescueMessage` 覆寫。
+- 指令註冊：`/watchdog status`、`/watchdog config`、`/watchdog set rescueMessage <msg>`、`/watchdog pause`、`/watchdog resume`、`/watchdog inspect <targetId>`（stub）。
+
+### Out of scope（後續 Task）
+
+- sub-agent 發現（Task02）、事件收集（Task03）、stuck 偵測（Task04）、watchdog tools（Task05）。
+- `/watchdog inspect` 只回覆「尚未實作，Task03 提供」的 stub 訊息。
+
+---
+
+## 2. 實作輸入（已查證的 API 事實）
+
+- Extension 進入點：default export factory，`export default function (pi: ExtensionAPI) { ... }`，可為 async。型別來自 `@earendil-works/pi-coding-agent`。
+- 開發載入：`pi -e ./src/index.ts`；extension 經 jiti 載入，TypeScript **免編譯**、可直接用 Node built-ins 與本地 npm 依賴。
+- 指令註冊：`pi.registerCommand(name, { description, handler: async (args: string, ctx: ExtensionCommandContext) => void })`。
+- 使用者輸出：`ctx.ui.notify(msg, "info" | ...)` 一行通知；互動前先檢查 `ctx.hasUI`（print/rpc 模式無 UI）。
+- Package manifest：`package.json` 的 `pi` key，`{ "extensions": ["./src/index.ts"] }`；`keywords: ["pi-package"]` 供 gallery 曝光。
+- Config 路徑（依需求文件 §11）：
+  - Global: `~/.pi/agent/watchdog-supervisor/config.json`
+  - Project: `.pi/watchdog-supervisor.json`
+
+---
+
+## 3. 檔案結構（本 Task 建立）
+
+```txt
+./                                  # repo root = package root
+├─ package.json                     # pi manifest + scripts
+├─ tsconfig.json
+├─ vitest.config.ts
+├─ src/
+│  ├─ index.ts                      # extension entry: 載入 config、註冊 commands
+│  ├─ types.ts                      # WatchdogConfig 等型別
+│  ├─ config.ts                     # DEFAULT_CONFIG、loadConfigFile、mergeConfig、getConfigPaths
+│  ├─ state.ts                      # SessionState: paused / rescueMessage 覆寫
+│  └─ commands.ts                   # registerWatchdogCommands(pi, store)
+└─ test/
+   ├─ config.test.ts
+   └─ state.test.ts
+```
+
+註：`detector.ts`、`events.ts`、`tools.ts`、`integrations/` 於後續 Task 依需求文件 §18 補齊。
+
+---
+
+## 4. 資料模型（本 Task 實作部分）
+
+```ts
+// src/types.ts
+type WatchdogConfig = {
+  enabled: boolean;              // default: true
+  rescueMessage: string;         // default: 需求文件 §2.2 中文預設訊息
+  repeatThreshold: number;       // default: 3
+  typecheckRepeatThreshold: number; // default: 2
+  idleNoProgressSec: number;     // default: 300
+  cooldownSec: number;           // default: 60
+  maxPreviewLines: number;       // default: 20
+  maxEventsPerAgent: number;     // default: 200
+  alertMode: 'main_only' | 'direct_subagent' | 'both'; // default: 'main_only'
+};
+
+// src/state.ts — session runtime 狀態（不落地）
+type SessionState = {
+  paused: boolean;                     // default: false
+  rescueMessageOverride?: string;      // /watchdog set rescueMessage 設定
+};
+```
+
+有效設定 = `DEFAULT_CONFIG ← global config ← project config ← session override`（右邊優先）。
+
+---
+
+## 5. 實作步驟（TDD）
+
+每步驟：先寫測試（紅）→ 實作（綠）→ 驗證指令。
+
+### Step 1 — Package 骨架與工具鏈
+
+- 建立 `package.json`：`"type": "module"`、`pi.extensions: ["./src/index.ts"]`、`keywords: ["pi-package"]`；devDependencies：`typescript`、`vitest`、`@earendil-works/pi-coding-agent`（型別用）；scripts：`"test": "vitest run"`、`"type-check": "tsc --noEmit"`。
+- 建立 `tsconfig.json`（ESM、strict）、`vitest.config.ts`。
+- 驗證：`npm install` 成功；`npm run type-check` 通過；`npm test` 可執行（0 test files 亦可）。
+
+### Step 2 — `types.ts` + `DEFAULT_CONFIG`
+
+- 先寫 `test/config.test.ts` 失敗測試：
+  - `DEFAULT_CONFIG` 各欄位值符合 §4（repeatThreshold=3、idleNoProgressSec=300、alertMode='main_only'、rescueMessage 為預設中文訊息…）。
+- 實作 `src/types.ts` 與 `src/config.ts` 的 `DEFAULT_CONFIG` 使測試通過。
+
+### Step 3 — Config 載入與合併
+
+- 先寫失敗測試（`test/config.test.ts`，用 temp dir 產生假 config 檔）：
+  1. 無任何 config 檔 → 回傳 `DEFAULT_CONFIG`。
+  2. 僅 global → default 被 global 覆蓋，未指定欄位保留 default。
+  3. global + project → project 欄位覆蓋 global，兩者未指定欄位保留 default。
+  4. config 檔為無效 JSON → 忽略該檔並回傳 warning 訊息（不 throw、不中斷載入）。
+  5. config 含未知欄位 → 忽略未知欄位。
+  6. `getConfigPaths(projectDir)` 回傳正確 global/project 路徑（global 以 `os.homedir()` 展開）。
+- 實作 `src/config.ts`：
+  - `getConfigPaths(projectDir: string): { globalPath: string; projectPath: string }`
+  - `loadConfigFile(path: string): { config: Partial<WatchdogConfig> | null; warning?: string }`（檔案不存在 → `null`，無 warning）
+  - `mergeConfig(...parts: Array<Partial<WatchdogConfig> | null | undefined>): WatchdogConfig`
+  - `loadEffectiveConfig(projectDir: string): { config: WatchdogConfig; warnings: string[] }`
+- 設計約束：`loadConfigFile` / `mergeConfig` 為純函式（I/O 與合併分離），方便測試；不做 file watch，config 於 extension 載入時讀一次（`/reload` 可重讀）。
+
+### Step 4 — Session 狀態
+
+- 先寫失敗測試（`test/state.test.ts`）：
+  1. 初始 `paused === false`、無 override。
+  2. `pause()` / `resume()` 切換 `paused`。
+  3. `setRescueMessage(msg)` 後 `getEffectiveRescueMessage(config)` 回傳 override；未設定時回傳 `config.rescueMessage`。
+- 實作 `src/state.ts`（簡單 in-memory store，供 commands 與後續 Task 共用）。
+
+### Step 5 — 指令註冊與 entry point
+
+- 實作 `src/commands.ts` 的 `registerWatchdogCommands(pi, store)`：
+
+| 指令 | 行為 |
+|---|---|
+| `/watchdog status` | 顯示：extension 版本、`enabled`、`paused`、config 摘要、target 數（Task01 固定顯示 `targets: 0 (subagent discovery: Task02)`） |
+| `/watchdog config` | 顯示有效 config 全文（JSON pretty print）+ 各值來源不需標註（post-MVP） |
+| `/watchdog set rescueMessage <msg>` | 設定 session override；`<msg>` 為空 → 顯示用法提示 |
+| `/watchdog pause` | `paused = true`，通知使用者 |
+| `/watchdog resume` | `paused = false`，通知使用者 |
+| `/watchdog inspect <id>` | 回覆 stub：`inspect not implemented yet (Task03)` |
+
+- 指令採單一 `/watchdog` 入口 + 子指令解析（`args.trim().split(/\s+/)`），未知子指令 → 顯示可用子指令清單。
+- 輸出方式：`ctx.ui.notify()`（單行）；config 全文等多行內容在 `ctx.hasUI` 時用 notify 逐段或 `ctx.ui.custom`，無 UI 模式（print/rpc）改 `console.log`。以最簡可行為準，不做花式 TUI。
+- 實作 `src/index.ts`：
+
+```ts
+export default function watchdogSupervisor(pi: ExtensionAPI) {
+  // load config once at startup; surface warnings via notify on session_start
+  // create session state store
+  // registerWatchdogCommands(pi, store)
+}
+```
+
+- config warning（如無效 JSON）在 `session_start` 時以 `ctx.ui.notify(warning, "warning")` 顯示一次。
+
+### Step 6 — 手動驗收
+
+依 §7 驗證指令逐項執行。
+
+---
+
+## 6. 測試覆蓋清單
+
+| 測試 | 檔案 | 類型 |
+|---|---|---|
+| DEFAULT_CONFIG 欄位與預設值 | test/config.test.ts | unit |
+| 無 config 檔 → defaults | test/config.test.ts | unit |
+| global 覆蓋 default | test/config.test.ts | unit |
+| project 覆蓋 global（部分欄位） | test/config.test.ts | unit |
+| 無效 JSON → warning、不 throw | test/config.test.ts | unit |
+| 未知欄位被忽略 | test/config.test.ts | unit |
+| getConfigPaths 路徑正確 | test/config.test.ts | unit |
+| pause/resume 切換 | test/state.test.ts | unit |
+| rescueMessage override 優先序 | test/state.test.ts | unit |
+| 指令行為（status/config/set/pause/resume/inspect） | 手動（§7） | manual |
+
+註：commands 與 pi API 的互動層薄、依賴 `ExtensionAPI` runtime，MVP 以手動驗收為主，不為其建 mock harness（避免單次使用的測試設施；若後續 Task 需要再引入）。
+
+---
+
+## 7. 驗收標準與驗證指令
+
+全部通過才算完成（依 completion verification 規則）：
+
+```bash
+npm run type-check        # tsc --noEmit 無錯誤
+npm test                  # vitest run 全綠
+```
+
+手動場景（在本 repo 內執行）：
+
+```txt
+1. pi -e ./src/index.ts
+2. /watchdog status
+   → 顯示 extension 已載入、enabled=true、paused=false、targets: 0
+3. /watchdog config
+   → 顯示 DEFAULT_CONFIG 全文
+4. 建立 .pi/watchdog-supervisor.json（如 {"repeatThreshold": 5}）→ /reload → /watchdog config
+   → repeatThreshold 顯示 5，其餘為 default
+5. /watchdog set rescueMessage 測試訊息
+   → /watchdog status 或 config 反映 session override
+6. /watchdog pause → status 顯示 paused=true；/watchdog resume → paused=false
+7. /watchdog inspect xyz
+   → 顯示 Task03 stub 訊息
+8. 將 .pi/watchdog-supervisor.json 改為無效 JSON → /reload
+   → extension 仍載入，顯示 warning，config 回退 default+global
+```
+
+---
+
+## 8. 風險與注意事項
+
+- `ExtensionCommandContext` 的 UI 細節（notify 多行支援、custom component 簽名）以實際型別定義為準；若與本 spec 假設不符，以「最簡輸出」原則調整，不影響驗收條件。
+- `/reload` 是否重新執行 extension factory（重讀 config）需在 Step 6 實測確認；若否，改於 `session_start` 重讀。
+- 依 karpathy 原則：不做 config file watch、不做來源標註、不做多語系輸出 — 未被要求的功能一律不加。
+
+---
+
+## 9. Revision History
+
+| Version | Change |
+|---|---|
+| v1 | 初版：TDD 步驟、config 合併規則、指令表、測試清單與手動驗收場景 |
+
+---
+
+## 10. Reference
+
+- reference01: https://pi.dev/docs/latest/extensions — entry point、registerCommand、ctx.ui、jiti 載入、`pi -e`（accessed 2026-07-08）
+- reference02: https://pi.dev/docs/latest/packages — pi manifest、config/settings 路徑、local dev workflow（accessed 2026-07-08）
+- reference03: `.tmp/2026-07-08_pi_watchdog_high_level_spec.md` — Task01 定義
+- reference04: `.tmp/2026-07-08_pi_watchdog_extension_requirement.md` — §7.3, §10, §11, §16, §19

package/.tmp/2026-07-08_pi_watchdog_task02_low_level_spec.md

@@ -0,0 +1,158 @@
+# Task02 — Sub-agent 發現與生命週期追蹤：Low-Level Detail Spec
+
+- Date: 2026-07-08
+- Source: `.tmp/2026-07-08_pi_watchdog_high_level_spec.md`（Task02）；requirement §9.1, §10, §12.1
+- Status: v1 — 使用者已指示直接實作，本文件同步作為實作依據與追溯紀錄
+- Perspective: TDD
+
+---
+
+## 1. Spike 結果（讀 `@gotgenes/pi-subagents@18.0.1` 原始碼，已完成）
+
+`src/service/service.ts` 確認：
+
+```ts
+// 同步 accessor，service 發布於 globalThis Symbol.for("@gotgenes/pi-subagents:service")
+getSubagentsService(): SubagentsService | undefined
+
+interface SubagentsService {
+  spawn(type: string, prompt: string, options?: SpawnOptions): string;
+  getRecord(id: string): SubagentRecord | undefined;
+  listAgents(): SubagentRecord[];          // 最新在前
+  abort(id: string): boolean;
+  steer(id: string, message: string): Promise<boolean>;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+}
+
+interface SubagentRecord {
+  id: string; type: string; description: string;
+  status: SubagentStatus;                  // queued|running|completed|steered|aborted|stopped|error
+  result?: string; error?: string;
+  toolUses: number; startedAt: number; completedAt?: number;
+  lifetimeUsage: LifetimeUsage; compactionCount: number;
+}
+```
+
+`src/observation/subagent-events-observer.ts` 確認事件 payload：
+
+| Channel | Payload |
+|---|---|
+| `subagents:created` | `{ id, type, description, isBackground: true }` |
+| `subagents:started` | `{ id, type, description }` |
+| `subagents:completed` / `subagents:failed` | `buildEventData(record)`（含 id；failed = status ∈ error/stopped/aborted） |
+| `subagents:steered` | `{ id, message }` |
+| `subagents:compacted` | `{ id, type, description, reason, tokensBefore, compactionCount }` |
+
+另確認（Task03 可用，本 Task 不用）：`subagents:child:session-created` payload 為 `{ sessionId, parentSessionId? }` — parent id 取得方式已解。
+
+**重要推論**：`listAgents()` 已提供 status/toolUses/lastActive 基礎資料 → Task02 採「事件驅動 + 指令時 `listAgents()` 對帳」雙軌，不需自建完整狀態機。
+
+---
+
+## 2. 範圍
+
+### In scope
+
+- `src/integrations/gotgenes-subagents.ts`：optional 整合 adapter（dynamic import + try/catch；未安裝時回傳 unavailable）。
+- `src/registry.ts`：target registry — 從 `SubagentRecord` 映射為 `WatchdogTarget`，事件更新 `lastActiveAt`。
+- kind 分類：`type` 或 `description` 含 `watchdog`（不分大小寫）→ `'watchdog'`，否則 `'task'`；無法判斷 → `'unknown'`。
+- `/watchdog status` 改為列出 targets（id、name/description、kind、status、toolUses、lastActiveAt）；service 缺席時顯示 `subagent service unavailable (install @gotgenes/pi-subagents)`。
+- `@gotgenes/pi-subagents` 列為 optional peerDependency + devDependency（開發/驗收用）。
+
+### Out of scope
+
+- tool_call 級事件收集、共享 store（Task03）；stuck 偵測（Task04）；watchdog tools（Task05）。
+
+---
+
+## 3. 資料模型
+
+```ts
+// src/types.ts 新增
+type TargetKind = 'task' | 'watchdog' | 'unknown';
+
+type WatchdogTarget = {
+  id: string;
+  name?: string;              // record.description
+  kind: TargetKind;
+  status: 'queued' | 'running' | 'completed' | 'steered' | 'aborted' | 'stopped' | 'error';
+  toolCallCount: number;      // record.toolUses
+  createdAt: number;          // record.startedAt
+  lastActiveAt: number;       // 事件時間戳更新；初始 = startedAt
+};
+```
+
+映射規則 `toWatchdogTarget(record, now)` 為純函式，事件套用 `applyEvent(targets, channel, payload, now)` 亦為純函式（I/O 分離）。
+
+---
+
+## 4. 實作步驟（TDD）
+
+### Step 1 — registry 純函式（紅→綠）
+
+`test/registry.test.ts` 失敗測試：
+
+1. `classifyKind`：type 含 watchdog → `'watchdog'`；description 含 Watchdog → `'watchdog'`；一般 type → `'task'`。
+2. `toWatchdogTarget`：欄位映射正確（toolUses→toolCallCount、startedAt→createdAt/lastActiveAt）。
+3. `applyEvent`：`subagents:started` 更新既有 target 的 status 與 lastActiveAt；未知 id 時建立 minimal target；`subagents:failed` → status 依 payload；payload 缺 id → 不變。
+4. `syncFromRecords`：以 `listAgents()` 結果對帳 — 新 record 加入、既有 target 保留較新的 lastActiveAt。
+
+實作 `src/registry.ts` 使通過。
+
+### Step 2 — 整合 adapter
+
+`src/integrations/gotgenes-subagents.ts`：
+
+```ts
+type SubagentsIntegration =
+  | { available: true; listAgents: () => SubagentRecordLike[]; }
+  | { available: false; reason: string };
+
+// dynamic import in try/catch; getSubagentsService() 回 undefined 也算 unavailable
+const connectSubagents = async (): Promise<SubagentsIntegration> => { ... }
+```
+
+- 型別以本地最小結構型別（`SubagentRecordLike`）宣告，不直接 import 套件型別到核心模組 — adapter 隔離（高階 spec 風險緩解）。
+- 事件訂閱：以 `pi.events.on(channel, handler)` 訂閱 §1 表列 6 個 channel（實作時以 `@earendil-works/pi-coding-agent` 型別宣告為準；若 API 名稱不同，於回報中註明實際名稱）。
+- 測試：unavailable 分支（import 失敗 / service undefined）回傳 reason；available 分支以 fake globalThis service 測試。
+
+### Step 3 — 接線 `index.ts` + `/watchdog status`
+
+- `index.ts`：載入時 `connectSubagents()`，建立 registry，訂閱事件 → `applyEvent`。
+- `commands.ts` `status`：先 `syncFromRecords(listAgents())` 對帳，再輸出：
+
+```txt
+watchdog-supervisor loaded | enabled=true | paused=false
+targets (3):
+  [task]      a1b2c3  running    tools=12  "explore campaign-list"
+  [task]      d4e5f6  running    tools=3   "fix type errors"
+  [watchdog]  g7h8i9  running    tools=1   "supervise task agents"
+```
+
+- service 缺席：`targets: unavailable — install @gotgenes/pi-subagents`。
+
+### Step 4 — 驗證
+
+- `npm run type-check`、`npm test` 全綠（既有 14 tests 不得回歸）。
+- Smoke：`pi -e ./src/index.ts` 載入無錯誤（未裝 pi-subagents 時顯示降級訊息）。
+
+---
+
+## 5. 驗收標準
+
+- [ ] `classifyKind` / `toWatchdogTarget` / `applyEvent` / `syncFromRecords` unit tests 通過。
+- [ ] 未安裝（或 service 未發布）時 extension 正常載入，`/watchdog status` 顯示 unavailable 訊息。
+- [ ] 安裝 pi-subagents 後：main session 有 2 task + 1 watchdog sub-agent 時 `/watchdog status` 正確列出 3 個 target 的 kind 與 status（手動場景，需 pi TUI）。
+- [ ] type-check + 全部測試通過。
+
+## 6. Revision History
+
+| Version | Change |
+|---|---|
+| v1 | 初版：含 spike 結果（service 簽名、事件 payload、parent id 解法）與 TDD 步驟 |
+
+## 7. Reference
+
+- reference01: `@gotgenes/pi-subagents@18.0.1` npm tarball `src/service/service.ts`、`src/observation/subagent-events-observer.ts`、`src/lifecycle/{subagent-state,child-lifecycle}.ts`（accessed 2026-07-08）
+- reference02: `.tmp/2026-07-08_pi_watchdog_high_level_spec.md` — Task02 定義