@esso0428/pi-subagents 0.17.5 → 0.17.7

package/docs/superpowers/plans/2026-09-30-conversation-viewer-scrollbar.md

@@ -0,0 +1,216 @@
+# Conversation Viewer Scrollbar Implementation Plan
+
+> [!NOTE]
+> **For agentic workers:** `subagent-driven-development` and
+> `executing-plans` are optional execution helpers. When resolving either
+> skill, prefer the namespaced form (`superpowers:<skill-name>`) when
+> available, then the bare `<skill-name>` form.
+>
+> This name-resolution order does not give those skills priority over the
+> current agent or host framework's native execution/delegation policy.
+>
+> Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在主 `ConversationViewer` transcript viewport 加入與 Tool Output 一致的右側 track/thumb scrollbar，同時保留現有鍵盤、wheel、focus、search 與 read-only 行為。
+
+**Architecture:** 重用 `conversation-viewer.ts` 既有的 `renderScrollbarCell()`，只在 transcript content rows 預留最右一格 rail；header、invocation、分隔線、composer/search、footer 不加入 rail。沿用現有 `scrollOffset`、`viewportHeight()` 與 `autoScroll`，不引入第二個 viewport 狀態，也不改用原生 `ScrollView`。
+
+**Tech Stack:** TypeScript、`@earendil-works/pi-tui`、Vitest、Biome、TypeScript compiler。
+
+## Global Constraints
+
+- 只修改 `/tmp/pi-canonical/pi-subagents-work` canonical checkout，不修改 npm-installed copy 或研究專案根目錄。
+- Scrollbar 只提供視覺 track/thumb；不新增 mouse click-to-jump 或 drag-to-scroll。
+- 保留 `j/k`、方向鍵、PageUp/PageDown、Home/End、wheel、`g/G`、search match、message/tool focus 的既有語意。
+- 保留 ConversationViewer header 的 `[preview] [Esc]` actions；`[preview]` 與 `w` 必須呼叫同一個 focused-tool preview handler，且 action hit-test 不得重疊。
+- Tool Preview 維持 parent-owned in-place preview 與既有 scrollbar，不與主 viewer rail 共用 offset。
+- 不新增跨 package renderer dependency，不改變 transcript read-only 性質。
+- 新增或改寫的測試必須使用 local `vitest`；不能以全域 binary 或 npm-installed package 取代 canonical repo 驗證。
+- 完成後執行 targeted viewer test、`npm test`、`npm run lint`、`npm run typecheck`、`npm run build`、`npm run test:e2e` 與 `npm pack --dry-run`。
+
+---
+
+### Task 1: Add failing ConversationViewer scrollbar tests
+
+**Files:**
+- Modify: `test/ui/conversation-viewer.test.ts`
+
+**Interfaces:**
+- Consumes: current `ConversationViewer`, `createStaticConversationSource`, `tui()`, `record()` and test `theme` helpers.
+- Produces: regression coverage for the main transcript rail that Task 2 must satisfy.
+
+- [ ] **Step 1: Add a long-transcript fixture and rail assertions**
+
+Use a transcript longer than the current test TUI viewport:
+
+```ts
+const longText = Array.from({ length: 80 }, (_, index) => `line ${index + 1}`).join("\n");
+const viewer = new ConversationViewer(
+  tui(),
+  createStaticConversationSource([{ role: "assistant", content: [{ type: "text", text: longText }] }] as any),
+  record(),
+  undefined,
+  theme,
+  vi.fn(),
+);
+
+const atBottom = viewer.render(100);
+expect(atBottom.some((line) => line.includes("┃") || line.includes("█"))).toBe(true);
+```
+
+The test must also assert that a short transcript does not show a thumb:
+
+```ts
+const shortViewer = new ConversationViewer(
+  tui(),
+  createStaticConversationSource([{ role: "assistant", content: [{ type: "text", text: "short" }] }] as any),
+  record(),
+  undefined,
+  theme,
+  vi.fn(),
+);
+expect(shortViewer.render(100).join("\n")).not.toMatch(/[┃█]/u);
+```
+
+- [ ] **Step 2: Add thumb movement coverage**
+
+Capture the row containing the thumb before and after jumping to the top:
+
+```ts
+const bottomLines = viewer.render(100);
+const bottomThumb = bottomLines.findIndex((line) => line.includes("┃") || line.includes("█"));
+viewer.handleInput("g");
+const topLines = viewer.render(100);
+const topThumb = topLines.findIndex((line) => line.includes("┃") || line.includes("█"));
+expect(bottomThumb).toBeGreaterThan(topThumb);
+```
+
+Keep the assertion focused on the rail location, not on a particular color escape sequence, because the test theme intentionally strips most color styles.
+
+- [ ] **Step 3: Run the focused test and confirm it fails before implementation**
+
+Run:
+
+```bash
+cd /tmp/pi-canonical/pi-subagents-work
+npx vitest run test/ui/conversation-viewer.test.ts
+```
+
+Expected: the existing ConversationViewer tests pass, and the new long-transcript rail assertion fails because the main viewer currently has no `┃`/`█` rail. Do not change production code in this step.
+
+---
+
+### Task 2: Render the main transcript scrollbar without changing layout semantics
+
+**Files:**
+- Modify: `src/ui/conversation-viewer.ts:32-52, 444-548`
+
+**Interfaces:**
+- Consumes: `renderScrollbarCell()`, `scrollOffset`, `autoScroll`, `viewportHeight()`, `buildContentLines()`, and existing `handleMouse()` geometry.
+- Produces: main viewer content rows with a reserved rightmost rail while Tool Preview continues using its own `FullToolPreview` viewport.
+
+- [ ] **Step 1: Define the content rail width and preserve outer width**
+
+Inside `render(width)`, keep `innerW = width - 4` for the existing frame/header geometry. Define one transcript-width rule and use it at every content-line build site:
+
+```ts
+const transcriptWidth = (innerW: number): number => Math.max(1, innerW - 1);
+const contentWidth = transcriptWidth(innerW);
+```
+
+Use `contentWidth` when building transcript lines and rendering transcript text. Replace existing `buildContentLines(this.lastInnerW || 80)` calls in input/focus/search paths with `buildContentLines(transcriptWidth(this.lastInnerW || 80))`; use `transcriptWidth(innerW)` in mouse handling. Keep `lastInnerW` as the full inner width so header close-button geometry remains unchanged.
+
+- [ ] **Step 2: Add a content-row renderer that reserves the rail**
+
+Keep the current `row()` helper for header, invocation, separator, composer/search and footer. Add a separate content-row path with this shape:
+
+```ts
+const contentRow = (content: string, lineIndex: number, totalLines: number, viewportHeight: number, offset: number) => {
+  const rail = renderScrollbarCell(th, totalLines, viewportHeight, offset, lineIndex, false);
+  const text = truncateToWidth(pad(content, contentWidth), contentWidth, "...", true);
+  return th.fg("border", "│") + " " + text + rail + " " + th.fg("border", "│");
+};
+```
+
+The implementation may use an equivalent local helper, but the invariant is fixed: one rail cell is outside the transcript text width and the resulting row remains exactly `width` columns wide.
+
+- [ ] **Step 3: Apply the rail only to visible transcript rows**
+
+Build content lines at `contentWidth`, compute `visibleStart` and `viewportHeight` as before, and render each displayed/blank transcript row through `contentRow`. Pass the relative visible row index to `renderScrollbarCell()` with the existing total line count and `visibleStart` offset. Preserve the sticky role header replacement and all existing focus/search styling before adding the rail.
+
+Do not add a rail to the outer header, invocation row, separator, composer/search row, or footer. When `totalLines <= viewportHeight`, `renderScrollbarCell()` must leave the rail visually empty while preserving its width.
+
+- [ ] **Step 4: Preserve the `[preview] [Esc]` header actions**
+
+Keep the header action geometry separate from the content rail. Render `[preview]` immediately to the left of `[Esc]`, reserve both labels before truncating the agent header title, and route `[preview]` press/click through the same `openFocusedToolPreview()` method used by `w`. With no focused tool, `[preview]` remains a handled no-op and must never trigger close. Add mouse press capture for both actions so release/click cannot fall through to the timeline.
+
+- [ ] **Step 5: Keep mouse hit-testing out of the visual rail**
+
+In `handleMouse()`, use the same `contentWidth = Math.max(1, innerW - 1)` for content geometry. Preserve wheel scrolling over the viewport, but do not pass click/press/move events from the reserved rail column into `ConversationTimeline`; the rail is visual-only and must not become a focus target. Header `[preview]`/`[Esc]` hit testing continues to use full `innerW`.
+
+
+- [ ] **Step 6: Run the focused tests and iterate**
+
+Run:
+
+```bash
+cd /tmp/pi-canonical/pi-subagents-work
+npx vitest run test/ui/conversation-viewer.test.ts
+```
+
+Expected: all focused tests pass, including the long-transcript rail presence, short-transcript no-thumb, and thumb movement assertions. If the content width or mouse coordinate assumptions fail, fix only the viewer geometry and rerun this focused suite.
+
+---
+
+### Task 3: Verify regression coverage and package gates
+
+**Files:**
+- Inspect: `src/ui/conversation-viewer.ts`
+- Inspect: `test/ui/conversation-viewer.test.ts`
+- Inspect: `docs/superpowers/specs/2026-09-30-conversation-viewer-scrollbar-design.md`
+
+**Interfaces:**
+- Consumes: the implementation and tests from Tasks 1–2.
+- Produces: passing verification evidence and a clean diff suitable for release review.
+
+- [ ] **Step 1: Run the full unit suite**
+
+```bash
+cd /tmp/pi-canonical/pi-subagents-work
+npm test
+```
+
+Expected: all test files pass; skipped tests may remain only where the existing suite intentionally skips live-model coverage.
+
+- [ ] **Step 2: Run static checks and build**
+
+```bash
+cd /tmp/pi-canonical/pi-subagents-work
+npm run lint
+npm run typecheck
+npm run build
+```
+
+Expected: Biome reports no errors, TypeScript reports no errors, and `dist/` compiles successfully.
+
+- [ ] **Step 3: Run the e2e and package checks**
+
+```bash
+cd /tmp/pi-canonical/pi-subagents-work
+npm run test:e2e
+npm pack --dry-run
+```
+
+Expected: the faux/scripted e2e suite passes, the tarball includes the compiled `dist/ui/conversation-viewer.js`, and no test source is required at runtime.
+
+- [ ] **Step 4: Review the final diff and commit**
+
+```bash
+cd /tmp/pi-canonical/pi-subagents-work
+git diff --check
+git status --short
+git add src/ui/conversation-viewer.ts test/ui/conversation-viewer.test.ts docs/superpowers/plans/2026-09-30-conversation-viewer-scrollbar.md
+git commit -m "feat: add conversation viewer scrollbar"
+```
+
+Expected: only the intended viewer source, focused tests, and this implementation plan are included in the feature commit. Do not publish or push this feature unless the user explicitly requests a release after reviewing the verification results.

package/docs/superpowers/plans/2026-09-30-upstream-event-workflow-partial-history.md

@@ -0,0 +1,195 @@
+# 上游事件管理、Workflow 與中途歷史實作計畫
+
+> [!NOTE]
+> **給 agentic workers：** 本計畫以目前 fork `64bbbb0` 與 `upstream/master` `e955e29` 的實際差異為準。所有步驟使用 checkbox 追蹤；不得刪除 fork 的 durable history/recovery 與 ConversationViewer 特性。
+
+**目標：** 接收上游 Workflow、lifecycle/RPC 與 render-cost 改善，同時讓所有子代理 launch path 都留下可重新開啟的 stopped/aborted/partial `.pi-subagents` 歷史。
+
+**架構：** 先將上游功能整合進現有 manager/runner/index seam，再把 durable transcript 附掛下沉到 `AgentManager.spawn()`，使 Agent tool、scheduler、RPC、Workflow 共用同一歷史介面。`.output` 僅是可選的外部串流檔；`.pi-subagents` 是 UI/history/checkpoint 的永久資料源。
+
+**技術：** TypeScript、pi ExtensionAPI、pi-tui、Vitest、worker-thread Workflow runtime、JSONL transcript、atomic checkpoint。
+
+## 全域限制
+
+- 保留套件名稱 `@esso0428/pi-subagents` 與 JSON agent override。
+- 保留 pi peer floor `>=0.80.8`，除非 typecheck 證明不可行且另有相容性處理。
+- `output_transcript: false` 僅停用 temp `.output`，不得停用 `.pi-subagents` durable history。
+- 不刪除 `src/agent-history.ts`、`src/agent-history-list.ts`、`src/agent-recovery.ts`。
+- 不覆蓋 fork 的 ConversationViewer scrollbar、`[preview] [Esc]`、`w` focused-tool preview、in-place Tool Preview。
+- 任何新日期型路徑使用當天 `2026-09-30`。
+- 完成前執行 lint、typecheck、`npm test`、`npm run test:e2e`、build、pack；使用者已明確要求 commit、push、publish。
+
+---
+
+### Task 1：建立上游整合基線
+
+**Files:**
+- Modify: `src/agent-manager.ts`, `src/agent-runner.ts`, `src/agent-types.ts`, `src/types.ts`, `src/settings.ts`
+- Modify: `src/index.ts`, `src/cross-extension-rpc.ts`, `src/output-file.ts`, `src/ui/agent-widget.ts`, `src/ui/fleet-list.ts`
+- Add: `src/workflow/*.ts`, `src/ui/workflow-*.ts`, `docs/workflows.md`, `docs/rpc.md`, `examples/workflows/*`
+- Test: upstream workflow/RPC/lifecycle tests selected from `test/workflow-*.test.ts`, `test/rpc-result-consumption.test.ts`, `test/child-session-shutdown.test.ts`
+
+**Interfaces:**
+- Consumes: current fork manager/history/UI interfaces and `upstream/master` workflow/runtime/event contracts.
+- Produces: `SubagentWorkflow` registration, workflow host/runtime/task/journal modules, RPC `consume`, lifecycle event ordering, and RPC activity tracking.
+
+- [ ] **Step 1: Record the merge inventory.**
+
+  In `/tmp/pi-canonical/pi-subagents-work`, compare `git diff --name-status 64bbbb0..upstream/master` and group changes into workflow, lifecycle/RPC, UI, package metadata, and deleted history modules. Treat upstream deletions of fork history/recovery as rejected changes.
+
+- [ ] **Step 2: Integrate upstream workflow/event files without replacing fork metadata.**
+
+  Bring in `src/workflow/`, workflow UI, workflow docs/examples, RPC consume/result-consumption changes, session shutdown ordering, scope-model validation, and RPC-spawn activity tracking. Resolve `src/index.ts`, `src/agent-manager.ts`, `src/agent-runner.ts`, `src/types.ts`, `src/settings.ts`, `src/ui/agent-widget.ts`, `src/ui/fleet-list.ts`, and `src/ui/conversation-viewer.ts` manually. Keep `src/nico-overrides.ts` and fork package identity.
+
+- [ ] **Step 3: Keep event semantics explicit.**
+
+  Ensure readiness is emitted only after the extension is bound; normal Agent tool emits `created`, `started`, terminal `completed`/`failed`, compaction emits `compacted`, steering emits `steered`, and shutdown emits `session_shutdown` before child session disposal. RPC-spawned agents must be observable from returned id and must not rely on `created`.
+
+- [ ] **Step 4: Run integration-focused tests.**
+
+  Run:
+  ```bash
+  npx vitest run test/cross-extension-rpc.test.ts test/rpc-result-consumption.test.ts test/rpc-lifecycle-gating.test.ts test/child-session-shutdown.test.ts test/workflow-tool.test.ts test/workflow-runtime.test.ts test/workflow.e2e.test.ts
+  ```
+  Expected: all selected tests pass; failures caused by the history/UI seam remain for Tasks 2–3, not hidden by deleting assertions.
+
+---
+
+### Task 2：把 durable partial history 下沉到 manager seam
+
+**Files:**
+- Modify: `src/agent-manager.ts`
+- Modify: `src/index.ts`, `src/output-file.ts`
+- Modify: `src/agent-history.ts`, `src/agent-history-list.ts`, `src/agent-recovery.ts`
+- Modify: `src/types.ts`
+- Test: `test/agent-manager-history.test.ts`, `test/agent-history.test.ts`, `test/agent-history-list.test.ts`, `test/agent-recovery.test.ts`, `test/output-file-history.test.ts`, new `test/partial-history-lifecycle.test.ts`
+
+**Interfaces:**
+- Consumes: `createAgentHistoryPath`, `agentHistoryLocator`, `writeInitialEntry`, `streamToOutputFile`, `setTranscript`, `checkpoint`, `restoreRecovered`.
+- Produces: every `manager.spawn()` record has a project-local transcript before queue/start; `output_transcript` only controls `.output`; terminal records retain `transcriptPath`.
+
+- [ ] **Step 1: Add one manager-owned durable attach operation.**
+
+  Add a private operation in `AgentManager` that, for a new record, creates `.pi-subagents/agent-transcripts/<safe-id>.jsonl`, writes the initial user entry, assigns `historyFile`/`transcriptPath`, and checkpoints. Make it idempotent so Agent tool callers do not duplicate the initial entry. Invoke it before the external `onSpawned` callback and clean only the checkpoint/record on a failed spawn; do not discard a successfully created transcript.
+
+- [ ] **Step 2: Separate `.output` gating from durable history.**
+
+  Change `attachTranscript()` in `src/index.ts` so `outputTranscript === false` skips only `createOutputFilePath()` and the temp initial entry. It must still use the manager-provided `historyFile` and `transcriptPath`. Keep `streamToOutputFile()` dual-write behavior when `record.outputFile` exists, and ensure no duplicate JSONL entry is written to history.
+
+- [ ] **Step 3: Flush before every terminal checkpoint.**
+
+  In manager stop/abort/queue cancellation, runner completion/error, resume failure, parent abort, and session shutdown paths, call `flushOutput(record)` before `checkpoint(record)`. Preserve status precedence: externally stopped remains `stopped`; hard max-turn interruption becomes `aborted`; provider/length failure becomes `error`; partial assistant text remains in JSONL even when `record.result` is empty.
+
+- [ ] **Step 4: Make history visibly partial and reopenable.**
+
+  Extend `AgentHistoryStatus`/formatting only as needed to label `stopped`, `aborted`, and `error` as terminal partial-capable states. Keep `canOpenAgentHistory()` based on live session or durable locator. In `ConversationViewer`, use the persisted status/read-only source and show a concise status marker in the header/footer without removing `[preview] [Esc]` or existing scrollbar geometry.
+
+- [ ] **Step 5: Add path matrix regression tests.**
+
+  Cover:
+  - tool call in progress followed by `manager.abort()`;
+  - queued agent cancellation;
+  - provider error after an assistant partial delta;
+  - max-turn abort/steer;
+  - parent signal abort and `abortAll()`;
+  - manager restore of running checkpoint as stopped;
+  - scheduler and RPC spawn creating `.pi-subagents` history;
+  - `output_transcript: false` still retaining durable history;
+  - history menu and viewer reopening after live session disposal.
+
+  Run the focused history/lifecycle tests before proceeding.
+
+---
+
+### Task 3：合併 UI render-cost 與事件刷新防閃動
+
+**Files:**
+- Modify: `src/ui/conversation-viewer.ts`
+- Modify: `src/ui/agent-widget.ts`, `src/ui/fleet-list.ts`
+- Test: `test/ui/conversation-viewer.test.ts`, `test/conversation-viewer.test.ts`, `test/agent-widget.test.ts`, `test/fleet-list.test.ts`, `test/perf/render-invariants.perf.test.ts` if integrated
+
+**Interfaces:**
+- Consumes: `ConversationTimeline` cache, fork parent-owned `FullToolPreview`, existing deferred/coalesced refresh behavior, upstream `3d91023` render bound.
+- Produces: stable render cost under rapid text/tool events, no nested overlay/input theft, and regression evidence for the original Tool Output failure.
+
+- [ ] **Step 1: Port only the upstream render-cost changes.**
+
+  Inspect upstream `3d91023` and port bounded hidden-tail/truncation and Markdown fallback behavior into the fork's current viewer. Do not replace the fork's scrollbar rail, header action hitboxes, or `openFocusedToolPreview()` path.
+
+- [ ] **Step 2: Coalesce live refreshes.**
+
+  On session event bursts, invalidate only changed timeline/cache state and schedule one `requestRender()` per event-loop turn. Ensure preview mode owns all input/mouse events and returns to the parent viewer without a nested `ctx.ui.custom` overlay.
+
+- [ ] **Step 3: Test the event sequence.**
+
+  Assert that repeated `message_update`/tool activity does not rebuild unchanged rows indefinitely, that the visible scrollbar thumb remains stable, that Tool Output cannot close the underlying subagent panel, and that `Esc`/`q` restore parent focus. Run all focused UI tests.
+
+---
+
+### Task 4：文件、文件說明與相容性整理
+
+**Files:**
+- Modify: `README.md`, `CHANGELOG.md`, `AGENTS.md`
+- Modify: `docs/rpc.md`, `docs/workflows.md`
+- Add/modify: `examples/workflows/*`
+- Preserve: `package.json` identity and peer floor unless verification requires a documented change
+
+**Interfaces:**
+- Consumes: implemented lifecycle/workflow/history behavior and test evidence.
+- Produces: user-facing documentation that explains event channels, Workflow ownership, durable partial history, and `.output` opt-out distinction.
+
+- [ ] **Step 1: Document partial-history guarantees.**
+
+  State that `.pi-subagents` is always the durable diagnostic/history source, including stopped/aborted/error/partial runs; `output_transcript` controls only the temp `.output` mirror. Document reopenability and status labels.
+
+- [ ] **Step 2: Reconcile upstream docs.**
+
+  Add the upstream RPC/Workflow usage and caveats, including RPC readiness, no `created` guarantee for RPC spawns, workflow-owned hidden children, and journal replay rules. Keep fork branding and JSON override instructions.
+
+- [ ] **Step 3: Add Unreleased entries.**
+
+  Add separate changelog bullets for Workflow/event management, durable partial history, and UI render stability. Do not rewrite released sections.
+
+---
+
+### Task 5：完整驗證、版本、commit、push、publish
+
+**Files:**
+- Modify: `package.json`, `package-lock.json`, `CHANGELOG.md`, `README.md` only if release metadata requires it
+- Test: all repository gates
+
+- [ ] **Step 1: Run the full local gates from the canonical checkout.**
+
+  ```bash
+  npm run lint
+  npm run typecheck
+  npm test
+  npm run test:e2e
+  npm run build
+  npm pack --dry-run
+  ```
+  Fix every failure; do not weaken durable-history, RPC lifecycle, Workflow, or UI regression assertions.
+
+- [ ] **Step 2: Select a release version.**
+
+  Because Workflow and lifecycle management are notable additions, update the package to the next minor version after `0.17.6` only after all gates pass. Move Unreleased entries into that version and create a fresh Unreleased section.
+
+- [ ] **Step 3: Commit the complete integration.**
+
+  ```bash
+  git add docs src test README.md CHANGELOG.md package.json package-lock.json AGENTS.md examples
+  git commit -m "feat: integrate upstream workflows and durable partial history"
+  ```
+
+- [ ] **Step 4: Push and publish only after verification.**
+
+  ```bash
+  git push origin master
+  npm publish
+  ```
+  Then independently verify:
+  ```bash
+  git ls-remote origin refs/heads/master
+  npm view @esso0428/pi-subagents version dist-tags.latest
+  ```
+  Confirm the remote commit and npm version match the committed release.

package/docs/superpowers/specs/2026-09-30-conversation-viewer-scrollbar-design.md

@@ -0,0 +1,82 @@
+# Conversation Viewer 主內容 scrollbar 設計
+
+## 狀態
+
+- 狀態：已取得使用者對推薦方案的批准，等待 spec review
+- 日期：2026-09-30
+- 範圍：`src/ui/conversation-viewer.ts` 與對應 UI tests
+
+## 問題
+
+目前 `ConversationViewer` 的主 transcript 內容可以用 `j/k`、方向鍵、PageUp/PageDown、wheel 與 footer 百分比滾動，但內容列沒有右側 scrollbar。現有 `FullToolPreview` 已有 track/thumb，因此主 viewer 與 Tool Output 的 viewport 視覺契約不一致，使用者也無法快速判斷目前在 transcript 的位置。
+
+## 目標
+
+- 在 ConversationViewer 的 transcript content rows 右側提供真正可見的 track/thumb rail。
+- thumb 位置與高度反映完整 transcript 行數、目前 viewport 高度與 `scrollOffset`。
+- 保留現有鍵盤與 wheel 滾動行為，不增加滑鼠拖曳或點擊跳轉。
+- 保留 ConversationViewer header 的 `[preview]` action；它必須與 `w` 使用同一個 focused-tool preview handler，並與 `[Esc]` 保持不重疊。
+- 保留 message/tool focus、search highlight、sticky header、composer、read-only 行為與 Tool Output preview 行為。
+- 內容寬度預留 rail，避免文字覆蓋 scrollbar。
+
+## 非目標
+
+- 本次不新增可拖曳 thumb 或點擊 track 跳轉。
+- 本次不改用 Pi 原生 `ScrollView`。
+- 本次不重構 ConversationTimeline 或抽出跨元件 scrollbar package。
+- 不修改 Tool Output preview 已有的 scrollbar 行為。
+
+## 設計
+
+### 渲染幾何
+
+`ConversationViewer.render(width)` 維持現有外框、header、invocation row、footer 與 status layout。只在 transcript content viewport 中保留最右一格作 scrollbar rail：
+
+1. 計算原本的 `innerW`。
+2. 當 content row render 時，將可用文字寬度設為 `innerW - 1`，最右一格固定輸出 rail。
+3. 以 `cachedLines.length` 作為 `totalLines`，以 `viewportHeight()` 作為 `viewportHeight`，以 `visibleStart` 或 `scrollOffset` 作為目前 offset。
+4. 使用既有 `renderScrollbarCell()`：沒有 overflow 時輸出 track 空白；有 overflow 時輸出 track `│` 與 thumb `┃`，scrollbar active 時可使用醒目 thumb `█`。
+5. Header、invocation row、分隔線、composer/search/footer 不消耗 transcript rail，避免改變既有互動區域。
+
+content line 的文字、focus rail 與 search highlight 先完成，再將結果放入保留 rail 的寬度；不可讓 `truncateToWidth` 把 scrollbar 覆蓋掉。
+
+### 狀態與滾動
+
+沿用現有 `scrollOffset`、`autoScroll`、`viewportHeight()` 與 `scrollBy()`，不新增第二份 offset。既有的：
+
+- `j/k` 與方向鍵
+- PageUp/PageDown
+- Home/End
+- wheel
+- `g/G`
+- search match 跳轉
+- tool/message focus 導航
+
+都繼續更新同一個 offset，render 時由同一個 offset 計算 thumb。自動追蹤最新內容時 thumb 留在底部；使用者向上滾動後則依現有規則停止 auto-follow。
+
+### 互動與事件
+
+本次 scrollbar 是視覺 track/thumb，不是滑鼠控制元件。`ConversationViewer.handleMouse()` 的 wheel 路由維持不變；click/press 仍依現有 timeline 與 header action hit-test 處理，不讓 scrollbar rail 新增意外 focus target。
+
+ConversationViewer header 保留兩個 action：`[preview] [Esc]`。`[preview]` 的 click/press geometry 必須固定在 close action 左側，並呼叫與 `w` 相同的 `openFocusedToolPreview()`；沒有 focused tool 時維持 no-op。Scrollbar rail 不得改變 header action 的 hit-test。
+
+Tool Preview 開啟時仍由 `FullToolPreview` 完全接管 render/input/mouse，不將主 viewer rail 與 preview rail 混用。
+
+## 測試
+
+在 `test/ui/conversation-viewer.test.ts` 增加或調整測試：
+
+1. 建立超過 viewport 的長 transcript，確認 content row 最右側出現 track/thumb 字元。
+2. 使用 `j`、PageDown 或 wheel 後重新 render，確認 thumb 位置會改變，且 hidden content 仍可到達。
+3. 建立不超過 viewport 的短 transcript，確認不顯示 thumb，且既有文字與外框寬度不變。
+4. 確認 header `[preview]` 仍可見且可 click，並與 `w` 開啟相同的 read-only Tool Output preview；沒有 focused tool 時不會誤觸 close。
+5. 確認 search、message/tool focus 與 Tool Output preview 仍可正常使用，沒有因 rail 保留而改變快捷鍵或 close 行為。
+6. 執行 targeted viewer test，再執行完整 unit tests、lint、typecheck、build、e2e 與 pack。
+
+## 驗收條件
+
+- 長 transcript 的主 ConversationViewer 右側可見 track/thumb。
+- thumb 隨現有鍵盤或 wheel 滾動正確移動。
+- 短 transcript 不顯示誤導性的 thumb。
+- 所有原有 ConversationViewer 與 Tool Output 行為測試通過。
+- 不新增 nested overlay、不改變 transcript read-only 性質、不引入跨 package renderer dependency。

package/docs/superpowers/specs/2026-09-30-upstream-event-workflow-partial-history-design.md

@@ -0,0 +1,49 @@
+# 上游事件管理、Workflow 與中途歷史設計規格
+
+## 目標
+
+在保留 fork 既有 JSON agent override、ConversationViewer scrollbar、in-place Tool Output preview 與 `.pi-subagents` 本地資料層的前提下，接收上游的 Workflow 與 lifecycle/RPC 事件管理；任何子代理即使被停止、逾時、達到 turn limit、父程序中斷或 session shutdown，都要留下可重新開啟、可解釋的中途歷史。
+
+## 範圍
+
+### 必須接收
+
+- 上游 `SubagentWorkflow`：`agent`、`parallel`、`pipeline`、`workflow`、`phase`、`log`、schema/gate、retry/resume、journal、saved workflow、worker-thread sandbox、Workflow UI。
+- 上游 lifecycle/RPC 管理：`subagents:ready`、`created`、`started`、`completed`、`failed`、`steered`、`compacted`、`session_shutdown`，以及 `ping`、`spawn`、`stop`、`consume` reply channels。
+- 上游 RPC spawned agent 的 activity tracking、scopeModels 驗證、completion consume 去重與 shutdown 順序。
+- 上游 ConversationViewer render-cost bound；但不覆蓋 fork 已有的 scrollbar、`[preview] [Esc]`、focused-tool preview 與 in-place overlay 行為。
+
+### 必須保留或強化
+
+- `src/agent-history.ts`、`src/agent-history-list.ts`、`src/agent-recovery.ts` 與相關測試不可因上游刪檔而移除。
+- `.pi-subagents/agent-transcripts/<agent-id>.jsonl` 是 UI 與診斷所需的 durable source of truth；`.output` 是可選的 Claude-compatible side transcript。`output_transcript: false` 只能停用 `.output`，不可停用 `.pi-subagents` 歷史。
+- durable transcript 必須涵蓋 Agent tool、foreground/background、scheduler、cross-extension RPC 與 Workflow child 所有 manager spawn path。
+- transcript 必須逐步保存 user prompt、assistant partial text、tool call、tool result/error、steering message、compaction 前後可恢復內容與終止狀態。
+- checkpoint 必須在 spawn/queued、session 建立、turn/compaction、stop/abort/error/completion/shutdown 等關鍵時點更新；重新啟動時 running/queued checkpoint 若有 transcript，一律還原為可開啟的 `stopped` partial record。
+- `/agents` 與 ConversationViewer 必須把 `stopped`、`aborted`、`error`、`steered` 等終止狀態顯示清楚，歷史可重新開啟且 read-only。
+
+## 設計決策
+
+1. **事件管理採上游協定，資料層採 fork durable history。** `pi.events` 只負責 lifecycle/RPC 通知與跨 extension 協調；`.pi-subagents` 保存完整可解釋過程，兩者不互相取代。
+2. **歷史附掛下沉至 `AgentManager.spawn()`。** 不再只由 Agent tool 的 `attachTranscript()` 建立歷史；manager 在 caller callback 前確保 project-local transcript 已建立並寫入 initial user entry，因此 scheduler、RPC、Workflow child 也不會漏記。
+3. **輸出與歷史分離。** `record.outputFile` 仍受 `output_transcript` 控制；`record.historyFile`／`record.transcriptPath` 永遠建立（若檔案系統失敗，checkpoint 仍保存 metadata 並以 warning 呈現）。streamer 同時寫入兩個檔案時必須去重。
+4. **終止狀態不是刪除。** abort/stop 先停止 session、flush transcript、寫 checkpoint，再釋放 live handle；TTL 只釋放 session，不刪除有 `transcriptPath` 的 record。清理與 session shutdown 不得讓已寫入的歷史消失。
+5. **Workflow child 的生命週期由 Workflow 管理，但 manager 仍是歷史附掛的單一 seam。** Workflow 事件可維持上游的 hidden child 語義；`.pi-subagents` 以 child id 保存每個 worker 的工具與結果，Workflow journal 另外保存 orchestration progress。
+6. **UI 閃動採上游 render-cost bound 加 fork 的 deferred/coalesced refresh。** 不引入第二個 overlay，也不讓 spinner/timer 直接重建整個 viewer；只在有效 session change 時 invalidate/requestRender，並以 render key/cache 保持穩定行數。
+7. **套件身份與相容性不盲目照搬。** 保留 `@esso0428/pi-subagents`、JSON override 與 pi `>=0.80.8` peer floor；只在 typecheck/test 證明 API 必須提高時才調整。
+
+## 驗收條件
+
+- upstream Workflow 文件、實作、examples、tests 均可在 fork 中使用，且與 JSON override / existing Agents UI 共存。
+- RPC `consume` 可抑制重複 completion notification；RPC spawn/stop/ready/failed 流程有測試。
+- 各 spawn path 的 `.pi-subagents` transcript 都存在；在 tool call 尚未完成時 stop/abort，重新開啟仍可看到 prompt、tool call、tool result/error 與 partial assistant output。
+- turn limit、provider failure、父 signal abort、session shutdown、SIGKILL 後的 checkpoint restore 都標成 stopped/aborted/error/partial，而不是消失或誤報 completed。
+- ConversationViewer 仍保有 scrollbar rail、`[preview] [Esc]`、`w` 同一路徑與 in-place Tool Preview，並有 render cost regression coverage。
+- 通過 lint、typecheck、完整 unit、E2E、build、pack；版本更新、commit、push、publish 後以 GitHub 與 npm 狀態獨立確認。
+
+## 不在本次範圍
+
+- 不刪除 fork 的 durable history/recovery 模組來追上游檔案布局。
+- 不把上游 package name、作者、README branding 或 peer floor 直接覆蓋到 fork。
+- 不以「有 output transcript」替代 `.pi-subagents` durable history。
+- 不把 UI flicker 宣稱為上游已完全解決；上游 0.19.0 的 3d91023 是 render cost bound，仍需以 fork regression test 驗證實際事件序列。