@esso0428/pi-subagents 0.17.16 → 0.17.17

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.17] - 2026-09-30
+
+### Changed
+- **Intentionally rolled the runtime and UI back to the v0.17.6 baseline (`64bbbb0`)** to reset the shipped behavior instead of carrying forward the post-v0.17.6 runtime changes.
+- **Archived post-v0.17.6 work as documentation-only specifications**: `ROADMAP.md` and `docs/post-0.17.6-*.md` remain included as v0.17.17 deliverables for future implementation, but are not part of the runtime reset.
+
 ## [0.17.16] - 2026-09-30
 
 ### Changed

package/ROADMAP.md

@@ -0,0 +1,87 @@
+# v0.17.17 回退與 v0.17.18+ 恢復路線圖
+
+本文件是 v0.17.17 的回退邊界與後續恢復決策，不是 runtime 實作計畫，也不承諾任何日曆日期。主要規格索引是 [`docs/post-0.17.6-feature-specs.md`](docs/post-0.17.6-feature-specs.md)；各階段都必須以該索引及其保存的原始 implementation、測試與 commit 證據為準。
+
+## 目標與不可變邊界
+
+- [x] 將 v0.17.17 定義為 intentional rollback：runtime/UI reset to v0.17.6 的 [`64bbbb0`](https://github.com/ESSO0428/pi-subagents/commit/64bbbb0)，而不是把後續功能當成已恢復功能。
+- [x] 保留 v0.17.6 的 ConversationViewer interaction baseline：scrollbar rail、`[preview]`/`[Esc]`、`w` focused-tool preview、in-place read-only Tool Output preview、keyboard/wheel scroll、focus 與 layout 行為。
+- [x] 在回退 runtime/UI 的同時保留 resource-policy metadata、資源規則與文件；特別是目前的 resource-safe local verification 政策（Vitest、E2E、build 需要明確授權，以及既有 worker/resource 限制）不得因功能恢復而被撤回。
+- [x] 保存 post-v0.17.6 規格與證據索引；文件保存不代表 v0.17.17 已重新提供該功能。
+- [ ] 後續任何恢復都必須先通過單一功能的證據與人工 UI latency acceptance，才可考慮與其他已驗證功能組合。
+
+## v0.17.17 回退內容
+
+- [x] runtime 與 UI 以 `64bbbb0`（v0.17.6）為基準；不得用 upstream viewer、FleetView 或 overlay 覆蓋既有 v0.17.6 viewer contract。
+- [x] 保留資源政策的文件與 metadata，不把 resource-policy rollback 混入功能 rollback；恢復功能也不得移除 `AGENTS.md`、CHANGELOG、package/Vitest 設定中對資源安全的約束。
+- [x] 本次交付只保存 Markdown 路線圖與既有規格索引；不修改 runtime source、package metadata，不 publish，也不在本路線圖階段執行 Vitest、E2E 或 build。
+- [ ] 將所有 post-v0.17.6 功能視為「待證據恢復」，而非在 v0.17.17 中隱式保留或半恢復。
+
+## v0.17.17 暫時移除的功能與保存規格
+
+以下功能在 v0.17.17 runtime/UI 回到 v0.17.6 時暫時不提供；每項都保留可追溯的 archived spec。這些勾選項是恢復清單，不表示本次要在 runtime 中實作。
+
+- [ ] **Durable agent history、transcript 與重新開啟**：`.pi-subagents` JSONL、partial turns、GC 後的 read-only history 與安全 locator。保存於 [`docs/post-0.17.6-durable-history-spec.md`](docs/post-0.17.6-durable-history-spec.md)。
+- [ ] **Workflow、lifecycle events 與 cross-extension RPC**：ready/created/completed 等 lifecycle、RPC ownership/consume、deterministic Workflow host 與 journal。保存於 [`docs/post-0.17.6-workflow-rpc-lifecycle-spec.md`](docs/post-0.17.6-workflow-rpc-lifecycle-spec.md)。
+- [ ] **Nested agents**：child-safe tool context、parent ownership、depth cap、allowlist、foreground/background 與 recursive cleanup。保存於 [`docs/post-0.17.6-nested-agents-spec.md`](docs/post-0.17.6-nested-agents-spec.md)。
+- [ ] **Recovery、stop/abort 與 shutdown**：checkpoint、partial recovery、terminal record、abort/queue 喚醒、`session_shutdown` 順序與 bounded cleanup。保存於 [`docs/post-0.17.6-recovery-shutdown-spec.md`](docs/post-0.17.6-recovery-shutdown-spec.md)。
+- [ ] **Agents roster、history navigation 與 ConversationViewer 整合**：single AgentWidget roster、selector input ownership、history row、viewer reopen 與 nested row 語意。保存於 [`docs/post-0.17.6-agents-roster-viewer-spec.md`](docs/post-0.17.6-agents-roster-viewer-spec.md)。
+- [ ] **Render-cost 與 UI latency 修復**：ConversationTimeline bounded cache、render path 不讀檔、AgentWidget cache、單一 roster、短 terminal 的 editor budget 與 redraw 限制。保存於 [`docs/post-0.17.6-ui-latency-baseline-spec.md`](docs/post-0.17.6-ui-latency-baseline-spec.md)。
+- [x] **v0.17.6 baseline 本身不是待移除功能**：其 viewer rail/preview/read-only 行為是所有後續恢復的不可回退基線；完整索引仍見 [`docs/post-0.17.6-feature-specs.md`](docs/post-0.17.6-feature-specs.md)。
+
+## 恢復證據規則
+
+- [ ] 每次恢復只選一個功能邊界，先從主索引找到對應 archived spec，再核對其中的原始 implementation files、tests、commit/tag 與既有錯誤語意。
+- [ ] 先建立 v0.17.6 baseline evidence：確認 viewer rail、preview、focus、keyboard/wheel scroll 與 read-only history 的行為沒有被待恢復變更改寫。
+- [ ] 對資料與安全邊界先取證：project-relative transcript/checkpoint、path traversal 拒絕、ownership、allowlist、depth cap、lifecycle 順序都要有可重現的證據。
+- [ ] 對 UI 功能另外保存人工操作紀錄：terminal 尺寸、操作步驟、畫面結果、可見延遲與任何回歸；不要把「測試通過」單獨當成 latency acceptance。
+- [ ] 若證據不足、行為與 archived spec 不一致，或人工操作出現可見卡頓，該功能停留在待恢復狀態，不與其他功能合併。
+- [ ] 本文件本身不執行 Vitest、E2E 或 build；恢復工作是否需要這些檢查，依當時授權與 `AGENTS.md` 的資源政策處理。
+
+## v0.17.18 的決策：只恢復 durable history 基礎層
+
+- [ ] 將 v0.17.18 限定為第一個、可獨立驗證的 durable history/recovery data plane：先處理 transcript 格式、project-local path safety、checkpoint metadata 與 flush/attach seam。
+- [ ] 以 [`docs/post-0.17.6-durable-history-spec.md`](docs/post-0.17.6-durable-history-spec.md) 和 [`docs/post-0.17.6-recovery-shutdown-spec.md`](docs/post-0.17.6-recovery-shutdown-spec.md) 為證據邊界；不得順便恢復 nested agents、Workflow/RPC、FleetView 或整套 Agents UI。
+- [ ] 確保 `output_transcript: false` 不會關閉 `.pi-subagents` durable history，且 GC/session cleanup 不會刪除仍可讀的 terminal record；壞 locator、壞 JSON 或 traversal input 必須 fail safely。
+- [ ] 在接受 v0.17.18 前，人工確認既有 v0.17.6 viewer interaction 沒有 layout/focus/scroll regression；若此基礎層不改 UI，也仍要記錄 baseline 操作結果。
+- [ ] v0.17.18 不承諾任何日曆日期；版本成立條件是上述單一功能的證據完整，而不是時間到期或功能數量達標。
+
+## v0.17.18 之後的證據驅動順序
+
+每一列都是獨立候選恢復項；「後續版本」只代表通過前一項 acceptance 後再決定的版本，不預設版本號或日期。
+
+| 順序 | 單一恢復項 | 主要證據與邊界 |
+|---|---|---|
+| 1 | Durable history 的 history list、read-only reopen 與 reload | [`durable-history`](docs/post-0.17.6-durable-history-spec.md)：先完成 history row/viewer wiring，再接各 spawn path；不得執行 tool 或改寫 transcript。 |
+| 2 | Recovery 的 restore、stop/abort 與 child shutdown | [`recovery-shutdown`](docs/post-0.17.6-recovery-shutdown-spec.md)：先保留 checkpoint/flush，再加入 `restoreRecovered`、queue wake-up 與 `session_shutdown` ordering。 |
+| 3 | Single Agents roster 與 selector ownership | [`agents-roster-viewer`](docs/post-0.17.6-agents-roster-viewer-spec.md)：先 cache durable rows/selection，再處理 selector input；不得重新引入已移除的 duplicate FleetView。 |
+| 4 | ConversationViewer 與 roster 的 latency/render bounds | [`ui-latency-baseline`](docs/post-0.17.6-ui-latency-baseline-spec.md)：bounded cache、render 不讀檔、arrow 不重建 widget、單一 roster、短 terminal 保留 editor 空間。 |
+| 5 | Nested agent ownership 與 lifecycle | [`nested-agents`](docs/post-0.17.6-nested-agents-spec.md)：先恢復 child-safe context、ownership/depth/allowlist，再接 manager spawn/abort/history；foreground/background 與 print-mode 另行取證。 |
+| 6 | Lifecycle events 與 cross-extension RPC | [`workflow-rpc-lifecycle`](docs/post-0.17.6-workflow-rpc-lifecycle-spec.md)：先恢復 event/RPC protocol、scope 與 ownership/consume，再接非 top-level child 的 activity 顯示。 |
+| 7 | Workflow worker、journal、schema 與 UI | [`workflow-rpc-lifecycle`](docs/post-0.17.6-workflow-rpc-lifecycle-spec.md)：最後接 Workflow host/runtime/UI；Workflow child 必須保留自己的 durable transcript，不得冒充 top-level roster。 |
+
+- [ ] 每完成一列，先獨立取證並完成人工 UI latency acceptance，再開始下一列。
+- [ ] 若某列需要前列的 seam，仍只接入必要依賴，不把後列功能預先帶入；依賴關係不能成為一次恢復多個 user-facing feature 的理由。
+
+## 人工 UI latency acceptance 門檻
+
+- [ ] **Viewer baseline**：在短、一般與較長 terminal 高度下，檢查 transcript scrollbar rail、hidden content、sticky/focus/search、`[preview]`、`[Esc]`、`w`、鍵盤與 wheel scroll；Tool Output preview 必須仍是 parent-owned、read-only、in-place。
+- [ ] **History path**：從 running、completed、stopped、recovered record 開啟 viewer，關閉後回到原 selector；selected row/viewport 不應跳回第一列，GC 後仍能從 durable transcript 讀取。
+- [ ] **Roster path**：大量 agent activity、長 transcript、多行 activity 與短 terminal 下，只有一個 roster；selector 開啟時 background widget 不得搶 key，editor 必須保留最小空間。
+- [ ] **Render path**：人工觀察長歷史與頻繁事件時沒有隨歷史長度惡化的可見卡頓；同時以規格列出的 perf guards 驗證 render 不做 filesystem I/O，並記錄證據而非臆測數字門檻。
+- [ ] **失敗處理**：任何可見延遲、focus/layout 變化、重複 redraw、stale row 或 history 消失都代表該單一功能未接受；先隔離或回退該變更，不得進入組合 release。
+
+## 0.17.18 與後續 release 的組合決策
+
+- [ ] **v0.17.18**：只接受 durable history/recovery 基礎層；不把 Agents UI、nested、RPC 或 Workflow 當作同一 release 的附帶恢復。
+- [ ] **後續版本**：只有已在獨立變更中完成 spec、targeted evidence 與人工 UI latency acceptance 的功能，才可在後續 release 與另一個已接受功能組合。
+- [ ] 組合前要重新執行人工回歸矩陣，特別是 viewer baseline、selector input ownership、長 transcript render 與 resource-policy metadata；單項通過不等於組合後通過。
+- [ ] 若組合回歸失敗，拆回最後一個已接受的功能邊界；不得為了湊版本內容而放寬 acceptance 或重新引入 duplicate UI。
+- [ ] 版本號只在證據與 release gate 都成立後決定；本路線圖不指定未來日期、不 publish、不替使用者執行 release 操作。
+
+## 完成定義與範圍守則
+
+- [ ] 每個恢復項都有對應 archived spec、implementation/test/commit evidence、人工 UI latency 紀錄與明確的保留/回退決策。
+- [ ] 所有恢復都維持 `64bbbb0` 的 viewer baseline，並保留 resource-policy metadata、資源規則與文件。
+- [ ] 不以功能數量、日期或單次自動檢查取代逐項 acceptance；不可接受的功能留在文件化的待恢復狀態。
+- [x] 本次工作只新增本根目錄 `ROADMAP.md`；沒有 runtime edits、測試、build 或 publish。

package/docs/post-0.17.6-agents-roster-viewer-spec.md

@@ -0,0 +1,42 @@
+# Agents roster、history navigation 與 ConversationViewer 規格
+
+## 基準與目標
+
+本規格保存 `64bbbb0`（v0.17.6）後的 Agents UI 演進，供 v0.17.17 之後逐項恢復。v0.17.6 的 ConversationViewer scrollbar/preview 是不可回退的 interaction baseline；Agents panel 則以 v0.17.0 的 single navigator 為前提，不恢復已移除的 duplicate FleetView。
+
+## UI 契約
+
+- above-editor `AgentWidget` 是唯一 roster；running 與 history selector 有各自 selected row 與 viewport。
+- `↑`/`↓`、Pi normalized key event、key-release filtering、`Enter`、`Esc`、`Ctrl-C` 的 ownership 要清楚：modal history selector 開啟時，background widget 不得偷吃輸入。
+- `Enter` 可開 live agent viewer 或 read-only durable history viewer；viewer 關閉後回到來源 submenu，selected row/viewport 要恢復。record 被 GC 時，用 nearest valid position，而不是跳回第一列或消失。
+- recovered/completed rows 保留 status、model、thinking、cost、tool uses、duration 與 transcript locator；nested child 只出現在 owning parent 的語意下，不污染 top-level roster。
+- widget 需按 terminal height 保留 editor 最小空間；overflow 顯示穩定，scrollbar bounds 不因短 terminal 或多行 activity 失效。
+- ConversationViewer 必須維持：主 transcript rail、sticky/focus/search、read-only history、`[preview]` 與 `[Esc]` 不重疊、`w` 與 header preview 共用 focused-tool preview、in-place Tool Output preview、鍵盤/wheel scroll。
+- viewer history 可顯示 Markdown mode、invocation/model/thinking、cost、truncation notice 與 terminal status，但不能透過 history mode 執行 tool 或改寫 transcript。
+
+## 原始實作與測試
+
+| 類別 | 原始路徑 |
+|---|---|
+| roster cache、selection、viewport、spinner、cost/status | `src/ui/agent-widget.ts`、`src/agent-color.ts` |
+| Agents command/menu、history restore、input routing | `src/index.ts`、`src/agent-history-list.ts`、`src/ui/select-item.ts`、`src/ui/viewer-keys.ts` |
+| transcript timeline、focus/search/preview/scrollbar | `src/ui/conversation-viewer.ts`、`src/ui/conversation-timeline.ts`、`src/ui/conversation-blocks.ts`、`src/ui/conversation-search.ts` |
+| roster/history unit tests | `test/agent-widget.test.ts`、`test/ui/agent-widget.test.ts`、`test/agent-menu-history-navigation.test.ts`、`test/agent-history-list.test.ts` |
+| viewer/key/mouse/search tests | `test/conversation-viewer.test.ts`、`test/ui/conversation-viewer.test.ts`、`test/conversation-viewer-keybindings.test.ts`、`test/ui/conversation-search.test.ts` |
+| wiring/model/history tests | `test/agent-widget-wiring.test.ts`、`test/agent-mention-wiring.test.ts`、`test/agent-manager-gc.test.ts`、`test/agent-manager-history.test.ts` |
+
+## 來源提交／tag
+
+- `64bbbb0`（v0.17.6）與 `77de83f`：ConversationViewer scrollbar rail、`[preview]` header action baseline。
+- `808cd81`：恢復 Agents history navigator。
+- `99f75a1`：修復 legacy Agents panel interactions。
+- `3706edc`：恢復 selected row/selection UX。
+- `a72ee7c`：把 history input 正確路由給 selector，並保留 live widget。
+- `32aba03`：重建 Agents widget lifecycle/cache/interaction model，保留 nested rows 與 durable records。
+- `5443fc5`：恢復 selector routing 與 peer metadata，不可讓 modal input 再被 widget 搶走。
+- `e42a8de`：移除 FleetView 與其 duplicate redraw/timer；只保留 AgentWidget/workflow menu。
+- `3d91023`：上游 ConversationViewer render-cost bound；整合時不可覆蓋 fork 的 rail/preview/in-place preview。
+
+## 選擇性恢復順序
+
+先恢復 durable history rows 與 `AgentWidget` selection cache，再恢復 selector input ownership，最後接 viewer renderer。`src/ui/fleet-list.ts` 及其 tests 是 `e42a8de` 移除的重複 surface，不應為了恢復 roster 而重新引入。

package/docs/post-0.17.6-durable-history-spec.md

@@ -0,0 +1,41 @@
+# Durable agent history 與 transcript 重新開啟規格
+
+## 狀態與邊界
+
+- 類型：歷史保存／未來選擇性恢復規格。
+- 基準：`64bbbb0`（v0.17.6）；主 viewer 的 scrollbar/preview baseline 見 `77de83f` 與 `b599e0e`。
+- 主要落地：`8d4d4a7`（v0.17.7 changelog 的 durable history 整合）。
+- 目標交付：v0.17.17 必須保留本規格，即使 runtime 先回退到基準。
+
+## 必須恢復的契約
+
+1. 每個可追蹤 spawn 在 queue/start 前建立 project-local `.pi-subagents/agent-transcripts/<safe-id>.jsonl`，寫入 initial user prompt；它是 history/UI/診斷的 source of truth。
+2. `Agent tool`、foreground/background、scheduler、mention/resume、cross-extension RPC、Workflow child 都走同一個 manager history seam；不能只在某一個 tool caller 補 transcript。
+3. 每個 turn 的 user/assistant/tool result（包含 details、error 與尚未完成的 partial assistant text）都要在 flush 時追加。`output_transcript: false` 只能關閉可選的 `.output` side transcript，不能關閉 `.pi-subagents`。
+4. parent record/checkpoint 保存 project-relative `transcriptPath`；清理 live session、TTL、session switch 後，terminal record 仍能由 `/agents` 或 ConversationViewer read-only 開啟。
+5. transcript 讀取必須拒絕絕對路徑、`..`、反斜線與不在 `.pi-subagents/agent-transcripts` namespace 的 locator；壞行可以跳過，不得令整份歷史消失。結果在 memory GC 後從 transcript 按需重載。
+6. viewer 要保留 v0.17.6 的 scrollbar rail、`[preview]`/`[Esc]` 與 `w` focused-tool preview，不用新的 nested overlay 取代歷史 viewer。
+
+## 原始實作與驗證索引
+
+| 類別 | 原始路徑 |
+|---|---|
+| JSONL 建立、stream、讀取、path safety | `src/agent-history.ts`、`src/output-file.ts` |
+| manager attach/checkpoint、GC 後 history record | `src/agent-manager.ts`、`src/types.ts` |
+| Agent tool、resume、scheduler/RPC/Workflow 的共同接線 | `src/index.ts` |
+| 歷史選擇與 read-only viewer | `src/agent-history-list.ts`、`src/ui/conversation-viewer.ts`、`src/ui/conversation-timeline.ts` |
+| 歷史/結果/安全 locator | `test/agent-history.test.ts`、`test/agent-history-list.test.ts`、`test/output-file-history.test.ts`、`test/output-file-path.test.ts`、`test/output-transcript-wiring.test.ts` |
+| manager attach、restore、GC | `test/agent-manager-history.test.ts`、`test/agent-manager-gc.test.ts`、`test/agent-manager.test.ts`、`test/agent-recovery.test.ts` |
+| viewer reload/render | `test/conversation-viewer.test.ts`、`test/ui/conversation-viewer.test.ts` |
+
+## 來源提交／tag
+
+- `64bbbb0`（v0.17.6 release）及 `77de83f`：viewer layout/focus baseline。
+- `8d4d4a7`：durable transcript、partial history、reopen 與 workflow/RPC history 接線。
+- `808cd81`、`a72ee7c`：history record 在 runtime cleanup 後仍留在 navigator，並重新路由 selector。
+- `32aba03`、`5443fc5`：Agents widget/selector 修復，避免重新開啟時遺失 durable row。
+- 對應既有設計：[`superpowers/specs/2026-09-30-upstream-event-workflow-partial-history-design.md`](superpowers/specs/2026-09-30-upstream-event-workflow-partial-history-design.md)、[`superpowers/plans/2026-09-30-upstream-event-workflow-partial-history.md`](superpowers/plans/2026-09-30-upstream-event-workflow-partial-history.md)。
+
+## 選擇性恢復順序
+
+先恢復 `agent-history.ts`/`output-file.ts` 的資料格式與 `AgentManager` attach/flush，再恢復 history list/viewer wiring，最後接上各 spawn path。若只能恢復部分功能，寧可保留可讀的 transcript 與 read-only viewer，也不要恢復會刪除 terminal history 的 GC。

package/docs/post-0.17.6-feature-specs.md

@@ -0,0 +1,50 @@
+# v0.17.17：0.17.6 之後功能保存規格
+
+## 文件用途
+
+這組文件是 **v0.17.17 的文件交付物**：保存 `v0.17.6` 之後、程式碼可能回退前的功能契約，讓日後可以按功能選擇性恢復。它不是新的 runtime 設計，也不取代原始測試。`v0.17.17` 目前只代表文件目標版本；本次不修改 package metadata、不 publish，也不刪除既有程式碼。
+
+- **基準**：`64bbbb0`（`chore: release 0.17.6`，v0.17.6）；其父提交 `77de83f` 是 scrollbar 實作。
+- **保存範圍**：基準之後至目前 `bad54e4` 的功能；上游整合參考 `upstream/master` 的 `e955e29`。
+- **既有準確文件**：
+  - [`docs/superpowers/specs/2026-09-30-upstream-event-workflow-partial-history-design.md`](superpowers/specs/2026-09-30-upstream-event-workflow-partial-history-design.md)
+  - [`docs/superpowers/plans/2026-09-30-upstream-event-workflow-partial-history.md`](superpowers/plans/2026-09-30-upstream-event-workflow-partial-history.md)
+  - [`docs/superpowers/specs/2026-09-30-conversation-viewer-scrollbar-design.md`](superpowers/specs/2026-09-30-conversation-viewer-scrollbar-design.md)
+  - [`docs/superpowers/plans/2026-09-30-conversation-viewer-scrollbar.md`](superpowers/plans/2026-09-30-conversation-viewer-scrollbar.md)
+  - [`docs/rpc.md`](rpc.md)、[`docs/workflows.md`](workflows.md)
+
+## 保存文件
+
+| 主題 | 規格 |
+|---|---|
+| Durable agent history、transcript 與重新開啟 | [`post-0.17.6-durable-history-spec.md`](post-0.17.6-durable-history-spec.md) |
+| Workflow、lifecycle events、cross-extension RPC | [`post-0.17.6-workflow-rpc-lifecycle-spec.md`](post-0.17.6-workflow-rpc-lifecycle-spec.md) |
+| Nested agents | [`post-0.17.6-nested-agents-spec.md`](post-0.17.6-nested-agents-spec.md) |
+| Recovery、stop、shutdown | [`post-0.17.6-recovery-shutdown-spec.md`](post-0.17.6-recovery-shutdown-spec.md) |
+| Agents roster、history navigation、ConversationViewer | [`post-0.17.6-agents-roster-viewer-spec.md`](post-0.17.6-agents-roster-viewer-spec.md) |
+| UI latency findings 與 v0.17.6 interaction baseline | [`post-0.17.6-ui-latency-baseline-spec.md`](post-0.17.6-ui-latency-baseline-spec.md) |
+
+## 不可遺失的 v0.17.6 baseline
+
+- `b599e0e`（v0.17.5）建立 read-only Tool Output 的 **in-place preview**；離開 preview 回到同一個 ConversationViewer。
+- `77de83f` 加入主 ConversationViewer 的右側 scrollbar rail；`64bbbb0` 將此契約標為 v0.17.6。
+- 主 viewer 必須保留 `[preview]`、`[Esc]`、`w` focused-tool preview、鍵盤/wheel 滾動、read-only history，以及 preview 不改變主 viewer focus/layout 的行為。
+
+後續整合（尤其 `8d4d4a7`）不得用上游 viewer、FleetView 或 overlay 取代這個 baseline。
+
+## 主要 post-baseline 提交索引
+
+- `8d4d4a7`：整合 upstream Workflow、lifecycle/RPC 與 durable agent history。
+- `8976c63`、`2966cd5`：nested delegation、深度/allowlist 與 fail-closed agent type。
+- `86c72ae`：background-by-default 及 background resume wiring。
+- `9afe114`：child session 在 dispose 前發出 `session_shutdown`。
+- `a9db27b`、`084d177`：RPC `consume`、scopeModels spawn 驗證。
+- `221df02`：deterministic Workflow tool、parallel/pipeline、journal、Workflow UI。
+- `3d91023`：ConversationViewer render-cost bound。
+- `808cd81`、`99f75a1`、`3706edc`、`a72ee7c`、`32aba03`、`5443fc5`、`e42a8de`：Agents roster/history 互動修復、輸入路由、移除重複 FleetView 與降低 redraw overhead。
+
+每一份子規格都列出原始 implementation files、tests、commit/tag；若程式碼回退，只按該表復原，不把本文件的歷史敘述當作可省略的測試。
+
+## 交付限制
+
+本次只新增/保存 Markdown 規格；runtime source、package metadata、`AGENTS.md` 與 publish 均不在範圍。依任務要求，不執行 Vitest、E2E 或 build。

package/docs/post-0.17.6-nested-agents-spec.md

@@ -0,0 +1,38 @@
+# Nested agents 規格
+
+## 目的與來源
+
+保存 `v0.17.6` 後 nested delegation 的行為，供 v0.17.17 之後選擇性恢復。基準是 `64bbbb0`；主要實作由 `8976c63`（#164）開始，後續由 `8d4d4a7` 與 background/workflow 整合延伸。
+
+## 必須保留的行為
+
+1. child tool 只由 owning parent 建立：`Agent`、`get_subagent_result`、`steer_subagent` 透過 child-safe context 注入，不暴露未授權的全域 manager 操作。
+2. 每個 child 帶有 `parentAgentId`、`depth`、`maxSubagentDepth`；達到深度上限時 fail closed。parent settle/abort 時要遞迴停止仍在跑的 children，避免隱形 token 消耗。
+3. `allowed_subagents` 若指定只能解析 allowlist；未指定才是所有 enabled agent。nested type 必須從繼承的 `configCwd` 解析，不可污染 process-global registry，也不可藉由 fallback policy 越權。
+4. child 的 `get result`、resume、steer 都要檢查 ownership；foreign child 不能讀取、操控或 resume。foreground child 預設 inline 等待並回傳結果；`run_in_background: true` 才交還 id，且 parent 結束前必須可被收回。
+5. nested child 與 workflow child 可以共用 manager 的 queue、model scope、worktree/abort/history seam，但 roster/lifecycle notification 不可把 child 假裝成 top-level agent。每個 child 仍應有自己的 durable transcript。
+6. nested path 必須保留既有錯誤語意：unknown/disabled type、allowlist violation、depth cap、foreign id 與 startup/isolation error 都回傳 tool error，而不是靜默 fallback。
+
+## 原始實作與測試
+
+| 類別 | 原始路徑 |
+|---|---|
+| child-safe tools、allowlist、depth、ownership、resume/steer/result | `src/nested-tools.ts`、`src/child-context.ts` |
+| parent/child record、queue、abort、usage、history | `src/agent-manager.ts`、`src/agent-runner.ts`、`src/types.ts` |
+| child session 注入與工具 veto | `src/index.ts`、`src/output-file.ts`、`src/model-scope.ts` |
+| 單元契約 | `test/nested-tools.test.ts`、`test/child-context.test.ts`、`test/model-scope.test.ts` |
+| 真實 boundary/print mode | `test/nested-delegation-e2e.test.ts`、`test/subagents-nested-print-mode-e2e.test.ts`、`test/subagents-print-mode-e2e.test.ts` |
+| queue/foreground lifecycle | `test/foreground-concurrency.test.ts`、`test/foreground-concurrency-wiring.test.ts`、`test/foreground-concurrency-print-mode-e2e.test.ts`、`test/foreground-result-retrieval.test.ts` |
+
+## 來源提交／tag
+
+- `8976c63`：opt-in nested subagent delegation、child context、depth 與 ownership 基礎。
+- `2966cd5`：fallbackSubagent fail-closed dispatch；nested unknown/disabled type 不可任意 fallback。
+- `86c72ae`：background-by-default 後仍維持 nested foreground 預設與明確 background opt-in。
+- `8d4d4a7`：將 nested spawn 接到 durable history、recovery、Workflow/RPC 及現有 fork UI。
+- `9ba6280`、`3f9d35c`：recursive nested print-mode boundary tests。
+- `64bbbb0`（v0.17.6）是 UI interaction baseline；nested child 不得破壞主 ConversationViewer 的 scrollbar/preview 行為。
+
+## 選擇性恢復順序
+
+先恢復 `NestedToolContext` 的 ownership/depth/allowlist，再接 manager spawn/abort/history；最後接 background/wait 與 print-mode boundary。不要以「允許 Agent tool」取代 child-safe tool set，也不要以 global agent registry 取代 inherited config root。

package/docs/post-0.17.6-recovery-shutdown-spec.md

@@ -0,0 +1,46 @@
+# Recovery、stop/abort 與 shutdown 規格
+
+## 目的與來源
+
+本文件保存 v0.17.6（`64bbbb0`）後的 interrupted-run 行為，目標是讓 v0.17.17 留下可檢視、可選擇恢復的規格。主要來源為 `8d4d4a7` 的 durable partial history，以及 `9afe114`／`9afe114` 對 child shutdown 的修正。
+
+## Checkpoint 與狀態契約
+
+- 每個 project 的 `.pi-subagents/agent-checkpoints/<id>.json` 是 atomic、可驗證的 metadata；包含 id/type/description/status、時間、tool uses、lifetime usage、compaction count、invocation 與 transcript locator。
+- 可保存狀態：`queued`、`running`、`completed`、`steered`、`stopped`、`aborted`、`error`。terminal status 不是刪除許可；只要有 transcript，就必須可列入歷史。
+- checkpoint 必須在 spawn/queue、session 建立、compaction、stop/abort、provider/startup error、completion、session switch/shutdown 等關鍵點更新；terminal checkpoint 前先 flush history/output。
+- 啟動時若讀到帶有效 transcript 的 `running`/`queued` checkpoint，必須轉成 `stopped` partial record；不能假報 completed，也不能因 live session 已不存在而丟失。
+- orphan、path traversal、壞 JSON、沒有有效 transcript 的 checkpoint/transcript 要被忽略；一個壞檔案不應阻塞其餘歷史。
+- `SIGKILL` 無法執行最後 flush；可恢復的語意是「最後一次已寫入 snapshot + stale active checkpoint 於下次啟動轉 stopped」，不是宣稱捕捉到 kill 當下的 delta。
+
+## Stop 與 shutdown 順序
+
+1. queued agent 先從 queue 移除並寫 `stopped` checkpoint；已跑的 agent 發 abort signal，仍要由 settle path flush。
+2. `abortAll()`、parent abort、session switch、dispose 都必須能喚醒等待 queue 的 caller，並保留 transcript locator。
+3. manager 在釋放 live handle 前 flush history；GC 只移除 session/promise/cleanup，不刪除有 durable transcript 的 row。
+4. child session teardown 先發 `session_shutdown` 給已 bind 的 extension runner，再呼叫 `session.dispose()`；handler 要有 bounded timeout，單一 hung handler 不能卡死 quit。
+5. dispose 可在自身被單獨呼叫時完成 abort/checkpoint/child teardown；正常 quit 的 shutdown handler 需 await child teardown。
+
+## 原始實作與測試
+
+| 類別 | 原始路徑 |
+|---|---|
+| checkpoint schema、驗證、atomic write/read | `src/agent-recovery.ts`、`src/agent-history.ts` |
+| abort、settle、queue、GC、dispose、child shutdown | `src/agent-manager.ts`、`src/agent-runner.ts` |
+| output/history flush 與 partial result | `src/output-file.ts`、`src/status-note.ts` |
+| recovery/checkpoint/partial output | `test/agent-recovery.test.ts`、`test/agent-manager-history.test.ts`、`test/agent-manager-gc.test.ts`、`test/output-file-history.test.ts` |
+| abort、startup/provider/error 狀態 | `test/abortable.test.ts`、`test/agent-startup-error.test.ts`、`test/subagent-error-status-e2e.test.ts`、`test/agent-runner.test.ts` |
+| child shutdown ordering/timeout | `test/child-session-shutdown.test.ts` |
+| nested parent cleanup | `test/nested-tools.test.ts`、`test/nested-delegation-e2e.test.ts` |
+
+## 來源提交／tag
+
+- `8d4d4a7`：recovery checkpoint、partial transcript flush、reload/reopen 與 manager seam。
+- `9afe114`：`session_shutdown` before child `dispose`（#242）。
+- `af04224`：RPC/非 Agent-tool spawn 的 activity 與 lifecycle 接線，避免 recovery row 沒有可見狀態。
+- `808cd81`、`a72ee7c`：GC/session cleanup 後恢復 history navigator。
+- `64bbbb0`：回退時仍必須保留的 v0.17.6 read-only viewer contract。
+
+## 選擇性恢復順序
+
+先恢復 checkpoint/path validation 與 flush ordering，再恢復 `restoreRecovered`、history row 與 child shutdown。不要用「dispose session」代替 `session_shutdown`，也不要在 abort 前先刪除 history/checkpoint；那會讓部分執行失去可解釋性。

package/docs/post-0.17.6-ui-latency-baseline-spec.md

@@ -0,0 +1,46 @@
+# UI latency findings 與 v0.17.6 interaction baseline
+
+## 定位
+
+這份文件把 post-0.17.6 的效能／互動修復保存成可驗證的 future-restoration spec。它不是新的 benchmark 結果，也不宣稱本次已重新執行測試。基準 commit/tag 為 `64bbbb0`（v0.17.6），上游 render-cost 來源為 `3d91023`，目前最後相關修復為 `e42a8de`。
+
+## v0.17.6 不可回退的 interaction baseline
+
+- 主 ConversationViewer transcript content 預留右側 rail；scroll offset、viewport、thumb 位置與 hidden content 狀態一致。
+- header 保留 `[preview]` 與 `[Esc]`；`[preview]` 和 `w` 使用同一個 focused-tool preview handler，hitbox 不重疊。
+- Tool Output preview 是 parent-owned、read-only、in-place；`Esc`/`q`/close 返回原 conversation，不能再開一層 overlay。
+- viewer 保留 focus、search、sticky header、read-only history、keyboard/page/wheel scroll、composer/search/footer 幾何。
+
+依據：`b599e0e`（v0.17.5 in-place preview）、`77de83f`（scrollbar 實作）、`64bbbb0`（v0.17.6 release）；詳細設計見 [`superpowers/specs/2026-09-30-conversation-viewer-scrollbar-design.md`](superpowers/specs/2026-09-30-conversation-viewer-scrollbar-design.md)。
+
+## 已觀察的 latency 根因與保存方案
+
+| 發現 | 保存的方案 | 來源 |
+|---|---|---|
+| transcript/tool/Markdown 事件頻繁時，整個 viewer 重新格式化會造成 render cost 隨歷史長度上升 | `ConversationTimeline`/viewer 保持 bounded cache、hidden tail/truncation，render 不做 filesystem I/O；局部 changed range 只更新受影響 rows | `3d91023`；`src/ui/conversation-viewer.ts`、`src/ui/conversation-timeline.ts` |
+| Agents widget 與 duplicate FleetView 都會對同一批 agent lifecycle 做 timer/refresh，造成 redraw 與 input surface 重複 | above-editor `AgentWidget` 作唯一 roster；`FleetView` 移除；`requestUiRefresh(force=false)` 預設正常 render，只有必要時 force | `e42a8de`；`src/ui/agent-widget.ts`、`src/index.ts`、`src/ui/workflow-menu.ts` |
+| widget 在 agent records 變動時重建 rows，selector 開啟時 background widget 仍可能搶 key | cache roster/record snapshot，arrow 只改 selection；selector modal 取得 input ownership，key-release/filter/normalized key 統一 | `32aba03`、`a72ee7c`、`5443fc5`；`src/ui/agent-widget.ts`、`src/index.ts` |
+| live cleanup、recovery restore 與 nested/RPC activity 令 UI row 閃爍或顯示 stale status | lifecycle update 只 invalidate 有效變更；durable history row 不隨 session handle GC 消失；RPC spawn 也建立 activity | `8d4d4a7`、`af04224`、`808cd81`、`3706edc` |
+| 短 terminal、長 roster、多行 activity 會侵蝕 editor 或越過 scrollbar bounds | 依 terminal height 計算 widget budget、保留 editor 最小空間、穩定 overflow/rail；不要新增第二個 roster | `99f75a1`、`32aba03`、`e42a8de`；`src/ui/agent-widget.ts` |
+
+## 原始實作與驗證索引
+
+| 類別 | 原始路徑 |
+|---|---|
+| viewer cache/render/preview/rail | `src/ui/conversation-viewer.ts`、`src/ui/conversation-timeline.ts`、`src/ui/conversation-blocks.ts` |
+| widget cache/refresh/viewport | `src/ui/agent-widget.ts`、`src/index.ts` |
+| interaction baseline tests | `test/conversation-viewer.test.ts`、`test/ui/conversation-viewer.test.ts`、`test/conversation-viewer-keybindings.test.ts`、`test/ui/agent-widget.test.ts` |
+| render/perf guards | `test/perf/no-fs-on-render.perf.test.ts`、`test/perf/render-invariants.perf.test.ts`、`test/perf/viewer.bench.ts`、`test/perf/widget.bench.ts`、`test/perf/formatters.bench.ts` |
+| selector/roster regression | `test/agent-widget.test.ts`、`test/agent-menu-history-navigation.test.ts`、`test/agent-widget-wiring.test.ts` |
+
+## 來源提交／tag
+
+- `64bbbb0`／v0.17.6、`77de83f`：baseline rail/preview contract。
+- `3d91023`：upstream render-cost bound；其方案只能移植到 fork 現有 viewer，不可覆蓋 scrollbar 或 preview ownership。
+- `808cd81`、`99f75a1`、`3706edc`、`a72ee7c`、`32aba03`、`5443fc5`：roster/history/selector latency 與 input ownership 修復。
+- `e42a8de`：FleetView removal、AgentWidget redraw overhead reduction。
+- `bad54e4`：local verification resource-safety；它不改 runtime latency，亦不應被誤記為 UI feature。
+
+## 恢復驗收（不在本次執行）
+
+恢復實作時至少要保留：render path 不讀檔、長 transcript cost 有 bound、widget cache 不因 arrow 重建、selector 開啟時 background input 不介入、只有一個 roster、v0.17.6 viewer rail/preview 行為不變。原始 perf/unit/e2e tests 是證據索引；本次任務依要求不執行 Vitest、E2E 或 build。

package/docs/post-0.17.6-workflow-rpc-lifecycle-spec.md

@@ -0,0 +1,54 @@
+# Workflow、lifecycle events 與 cross-extension RPC 規格
+
+## 狀態與基準
+
+這是 v0.17.17 保存用的歷史／未來恢復規格，不是要求本次重新整合 runtime。比較基準為 `64bbbb0`（v0.17.6）；主要功能在 `8d4d4a7`、`a9db27b`、`084d177`、`221df02` 落地。既有完整說明仍以 [`docs/rpc.md`](rpc.md)、[`docs/workflows.md`](workflows.md) 與 upstream partial-history spec 為準。
+
+## Lifecycle 契約
+
+- `session_start` 完成 extension 綁定後才廣播 `subagents:ready`，避免 caller 在 handler 尚未註冊時遺失 ready。
+- top-level agent 依序可發出 `subagents:created`、`subagents:started`、`subagents:compacted`、`subagents:steered`，終止時發出 `subagents:completed` 或 `subagents:failed`；nested/workflow-owned child 不應被誤報成獨立 top-level notification。
+- child `AgentSession` 由 manager 綁定 extension 後，清理/quit 必須先給其 extension runner `session_shutdown`，再 dispose；詳見 recovery/shutdown 規格。
+- completion notification 與 RPC consume 必須可去重；caller 已取得結果後不應再讓 parent model 收到同一份 completion。
+
+## RPC 契約
+
+所有 request 走同一個 in-process `pi.events` bus，reply 為 `subagents:rpc:<name>:reply:<requestId>`，envelope 是 `{ success: true, data? }` 或 `{ success: false, error }`。Protocol version 為 `2`。
+
+| channel | 用途與限制 |
+|---|---|
+| `subagents:rpc:ping` | 回報 protocol version。 |
+| `subagents:rpc:spawn` | 解析 string model、執行 scopeModels、建立 top-level agent，並 await startup error。 |
+| `subagents:rpc:stop` | 只允許 top-level owned record；停止 queued/running agent。 |
+| `subagents:rpc:consume` | 標記已取用的 terminal result，抑制重複 completion notification。 |
+
+RPC payload 不能偽造 `parentAgentId`、`workflowId`、`resumeSessionFile`、`rootSessionId` 等內部欄位；model 若由 caller 指定，要在 resolved model 上做 scope 檢查。這些限制是安全與 ownership 契約，不是可省略的輸入清理。
+
+## Workflow 契約
+
+`SubagentWorkflow` 是 deterministic script host：在 worker/sandbox 中提供 `agent`、`parallel`、`pipeline`、`workflow`、`phase`、`log` 等 orchestration API，受 schema、gate、concurrency、abort/resume 與 journal 約束；每個 child 仍由 manager 建立 durable history。Workflow progress/journal 與 agent transcript 分離：前者保存編排進度，後者保存每個 child 的對話。
+
+## 原始實作與測試
+
+| 類別 | 原始路徑 |
+|---|---|
+| event wiring、manager spawn/settle、ready/created/completed | `src/index.ts`、`src/agent-manager.ts`、`src/agent-runner.ts` |
+| RPC handlers、reply envelope、scope/ownership/consume | `src/cross-extension-rpc.ts`、`src/model-scope.ts`、`src/model-resolver.ts` |
+| Workflow host/runtime/task/journal/schema/progress | `src/workflow/entry.ts`、`host.ts`、`runtime.ts`、`task.ts`、`journal.ts`、`json-schema.ts`、`progress.ts`、`saved.ts`、`worker-source.ts` |
+| Workflow UI與註冊 | `src/ui/workflow-card.ts`、`src/ui/workflow-dialog.ts`、`src/ui/workflow-menu.ts`、`src/index.ts` |
+| event/RPC 行為 | `test/rpc-lifecycle-gating.test.ts`、`test/cross-extension-rpc.test.ts`、`test/rpc-result-consumption.test.ts`、`test/child-session-shutdown.test.ts` |
+| Workflow host/runtime/journal/schema/UI | `test/workflow-tool.test.ts`、`test/workflow-runtime.test.ts`、`test/workflow-task.test.ts`、`test/workflow-journal.test.ts`、`test/workflow-json-schema.test.ts`、`test/workflow-progress.test.ts`、`test/workflow-dialog.test.ts`、`test/workflow-render.test.ts`、`test/e2e/workflow.e2e.test.ts` |
+
+## 來源提交／tag
+
+- `8d4d4a7`：upstream Workflow、lifecycle/RPC、partial-history 的整合基線；同時保存 fork 的 history/ConversationViewer 特性。
+- `a9db27b`：新增 `subagents:rpc:consume` 與 result-consumption tests。
+- `084d177`：RPC spawn 的 resolved-model `scopeModels` enforcement。
+- `af04224`：RPC-spawn activity tracking，確保 widget/ConversationViewer 看得到正確生命週期。
+- `9afe114`：child shutdown event 順序。
+- `221df02`：Workflow tool、examples、worker runtime、journal 與 UI。
+- `e955e29`（`upstream/master`）：lowercase `workflow` tool compatibility 修正；恢復時需保留 fork 的命名 collision guard。
+
+## 恢復注意
+
+先恢復 event/RPC 協定與 manager ownership，再恢復 Workflow worker/UI；不要先把 Workflow child 當成 top-level roster，也不要用 parent session branch 取代 child 的 durable transcript。`docs/rpc.md` 中的 in-process 限制、reply race 與 error strings 也是恢復驗收的一部分。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.16",
+  "version": "0.17.17",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/agent-history.ts

@@ -1,8 +1,8 @@
 /** Durable, project-local transcript storage for subagents. */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 
 const SUBAGENTS_DIR = ".pi-subagents";
 const TRANSCRIPTS_DIR = "agent-transcripts";
@@ -46,58 +46,6 @@ export function agentHistoryLocator(cwd: string, historyPath: string): string {
   return relative(cwd, historyPath).split(sep).join("/");
 }
 
-function historyEntry(agentId: string, message: AgentSession["messages"][number], cwd: string): string {
-  return JSON.stringify({
-    isSidechain: true,
-    agentId,
-    type: message.role === "assistant" ? "assistant" : message.role === "user" ? "user" : "toolResult",
-    message,
-    timestamp: new Date().toISOString(),
-    cwd,
-  }) + "\n";
-}
-
-/** Write the first user prompt without involving the optional `.output` file. */
-export function writeAgentHistoryInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void {
-  if (existsSync(path)) return;
-  writeFileSync(path, historyEntry(agentId, { role: "user", content: prompt } as AgentSession["messages"][number], cwd), "utf8");
-}
-
-/** Stream every new session message to the mandatory durable history file. */
-export function streamAgentHistory(
-  session: AgentSession,
-  path: string,
-  agentId: string,
-  cwd: string,
-  startIndex = 1,
-): () => void {
-  let writtenCount = startIndex;
-  const messages = (): AgentSession["messages"] => Array.isArray(session.messages) ? session.messages : [];
-  const flush = () => {
-    const currentMessages = messages();
-    while (writtenCount < currentMessages.length) {
-      try {
-        appendFileSync(path, historyEntry(agentId, currentMessages[writtenCount]!, cwd), "utf8");
-      } catch {
-        // A read-only project must not turn a model event into a failed run.
-      }
-      writtenCount++;
-    }
-  };
-  const unsubscribe = typeof session.subscribe === "function"
-    ? session.subscribe((event: AgentSessionEvent) => {
-        if (event.type === "turn_end" || event.type === "compaction_start") flush();
-        if (event.type === "compaction_end" && !event.aborted && event.result) {
-          queueMicrotask(() => { writtenCount = messages().length; });
-        }
-      })
-    : () => {};
-  return () => {
-    flush();
-    unsubscribe();
-  };
-}
-
 /** Resolve only paths in this package's project-local transcript namespace. */
 export function resolveAgentHistoryPath(cwd: string, locator: string): string | undefined {
   // Locators are persisted data, not arbitrary paths. Reject traversal syntax