@gotgenes/pi-subagents 6.15.0 → 6.16.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.16.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.16.0...pi-subagents-v6.16.1) (2026-05-23)
+
+
+### Bug Fixes
+
+* **pi-subagents:** theme parentheses and separator in formatSessionTokens ([33b67f6](https://github.com/gotgenes/pi-packages/commit/33b67f63915563c41605addb885af52b47844e96))
+
+
+### Documentation
+
+* plan split AgentWidget rendering from lifecycle ([#148](https://github.com/gotgenes/pi-packages/issues/148)) ([24c11d5](https://github.com/gotgenes/pi-packages/commit/24c11d51f2b6c9d2712815fbe46ede72084ffcbb))
+* **retro:** add retro notes for issue [#144](https://github.com/gotgenes/pi-packages/issues/144) ([f3cdfd4](https://github.com/gotgenes/pi-packages/commit/f3cdfd46fe223d6cecb5dad0d739f053e7468433))
+* update architecture for widget rendering extraction ([#148](https://github.com/gotgenes/pi-packages/issues/148)) ([450707e](https://github.com/gotgenes/pi-packages/commit/450707e1d0f41ae78f1a655ab350fd8f4fd64125))
+
+## [6.16.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.15.0...pi-subagents-v6.16.0) (2026-05-23)
+
+
+### Features
+
+* add session and outputFile convenience getters to AgentRecord ([#144](https://github.com/gotgenes/pi-packages/issues/144)) ([b451894](https://github.com/gotgenes/pi-packages/commit/b451894d101b43be9115dcf6d45725a09da81df8))
+
+
+### Documentation
+
+* mark Step L complete, remove resolved smells from architecture doc ([#144](https://github.com/gotgenes/pi-packages/issues/144)) ([36ab7a5](https://github.com/gotgenes/pi-packages/commit/36ab7a51d0320666b71d6c9e20c3bbf63b7c43c5))
+* plan consolidate observation model ([#144](https://github.com/gotgenes/pi-packages/issues/144)) ([9aa2c85](https://github.com/gotgenes/pi-packages/commit/9aa2c8508079c6ae847662631afd223e8966e12e))
+* **retro:** add retro notes for issue [#145](https://github.com/gotgenes/pi-packages/issues/145) ([2d23081](https://github.com/gotgenes/pi-packages/commit/2d230817d53357a62eb752b56f8b1c8ce4af718c))
+
 ## [6.15.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.14.1...pi-subagents-v6.15.0) (2026-05-23)
 
 

package/docs/architecture/architecture.md

@@ -69,7 +69,8 @@ renderer.ts               - notification TUI component
 record-observer.ts        - session-event observer for record statistics
 
 ui/display.ts             - pure formatters, display helpers, and shared types (Theme, AgentDetails)
-ui/agent-widget.ts        - above-editor live status widget
+ui/agent-widget.ts        - above-editor live status widget (thin lifecycle wrapper)
+ui/widget-renderer.ts     - pure rendering functions for agent widget
 ui/agent-menu.ts          - /agents slash command menu
 ui/conversation-viewer.ts - scrollable session overlay
 ui/ui-observer.ts         - session-event observer for UI streaming
@@ -615,15 +616,13 @@ Phase 9 targets the next layer: observation model consolidation, `ExtensionConte
 
 ### Current smells
 
-| Smell                                            | Location                                                              | Evidence                                                                                                                                                       | Severity |
-| ------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| Dual observation                                 | `record-observer.ts`, `ui-observer.ts`                                | Both independently count tool uses and accumulate lifetime usage from the same session events; consumers use `activity?.toolUses ?? record.toolUses` fallbacks | High     |
-| `execute` does config resolution for its callees | `agent-tool.ts` (145-line `execute`)                                  | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep                                 | Medium   |
-| Wide `ctx` in menu handlers                      | `agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts` | Functions declare `ctx: ExtensionContext` but only call `ctx.ui.select/confirm/input/notify/editor`; 43 `ctx as any` casts across 3 test files                 | Medium   |
-| `record.execution?.session` traversal            | 15+ callsites across tools, notification, widget, menu                | Callers reach through `ExecutionState` to access session and outputFile - Law of Demeter violation                                                             | Medium   |
-| Direct SDK import in `conversation-viewer.ts`    | `conversation-viewer.test.ts`                                         | Hoisted `vi.mock("@earendil-works/pi-tui")` to intercept `wrapTextWithAnsi`                                                                                    | Low      |
-| Widget mixes rendering, lifecycle, and state     | `agent-widget.ts` (370 lines)                                         | `renderWidget` is ~109 lines mixing data collection, formatting, and overflow layout; constructor takes 3 concrete collaborators                               | Low      |
-| `deps.` prefix noise in function bodies          | 12 modules across tools, UI, notification, service-adapter            | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line                                      | Low      |
+| Smell                                            | Location                                                              | Evidence                                                                                                                                       | Severity |
+| ------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `execute` does config resolution for its callees | `agent-tool.ts` (145-line `execute`)                                  | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep                 | Medium   |
+| Wide `ctx` in menu handlers                      | `agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts` | Functions declare `ctx: ExtensionContext` but only call `ctx.ui.select/confirm/input/notify/editor`; 43 `ctx as any` casts across 3 test files | Medium   |
+| Direct SDK import in `conversation-viewer.ts`    | `conversation-viewer.test.ts`                                         | Hoisted `vi.mock("@earendil-works/pi-tui")` to intercept `wrapTextWithAnsi`                                                                    | Low      |
+| ~~Widget mixes rendering, lifecycle, and state~~ | ~~`agent-widget.ts` (370 lines)~~                                     | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                                         | Done     |
+| `deps.` prefix noise in function bodies          | remaining modules across tools, UI, service-adapter                   | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line                      | Low      |
 
 ### Dependency bag convention
 
@@ -634,9 +633,9 @@ Applied incrementally as each step touches a module:
 
 This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
 
-### Step L: Consolidate observation model (#144)
+### Step L: Consolidate observation model (#144) ✓
 
-Remove `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
+Removed `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
 UI consumers read stats from `AgentRecord` instead of the tracker.
 The UI observer retains event subscriptions for re-render triggers but no longer accumulates stats independently.
 
@@ -690,13 +689,11 @@ Apply the dependency bag convention: `ConversationViewerOptions` is destructured
 
 Impact: eliminates the hoisted `vi.mock("@earendil-works/pi-tui")` in `conversation-viewer.test.ts`.
 
-### Step P: Split AgentWidget rendering (#148)
+### Step P: Split AgentWidget rendering (#148) ✓
 
-Extract pure rendering functions from `AgentWidget` into `ui/widget-renderer.ts`.
-The widget becomes a thin lifecycle/polling wrapper that calls pure render functions.
-Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle.
-
-Depends on Step L: once the tracker drops stats fields, the renderer reads from `AgentRecord` for tool uses and usage, and from `AgentActivityTracker` only for live UI state (active tools, response text, turn count).
+Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
+The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
+Rendering functions receive data (agent list, activity map, registry) and return formatted strings — testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
 
 ### Step dependencies
 

package/docs/plans/0144-consolidate-observation-model.md

@@ -0,0 +1,263 @@
+---
+issue: 144
+issue_title: "Consolidate observation model (Phase 9, Step L)"
+---
+
+# Consolidate observation model
+
+## Problem Statement
+
+`record-observer.ts` and `ui-observer.ts` independently count tool uses and accumulate lifetime usage from the same session events.
+`AgentRecord` owns `_toolUses` and `_lifetimeUsage` (accumulated by the record observer), while `AgentActivityTracker` maintains its own `_toolUses` and `_lifetimeUsage` (accumulated by the UI observer).
+Consumers use `activity?.toolUses ?? record.toolUses` fallbacks to paper over the ambiguity.
+
+Separately, 15+ callsites navigate `record.execution?.session` and `record.execution?.outputFile`, leaking the `ExecutionState` structure to every consumer.
+
+Finally, `NotificationDeps` (4 fields) is a dependency bag on a class where every method uses every field — plain constructor parameters are simpler.
+
+## Goals
+
+- Remove `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker` so stats have a single source of truth on `AgentRecord`.
+- Update UI consumers (widget, conversation viewer, notification, foreground runner) to read stats from `AgentRecord` instead of the tracker.
+- Remove the `onToolEnd` counter and `onUsageUpdate` accumulator from `AgentActivityTracker`, keeping only live UI state (active tools, response text, turn count).
+- Stop the UI observer from duplicating `tool_execution_end` counting and `message_end` usage accumulation.
+- Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
+- Replace `NotificationDeps` interface with plain parameters on `NotificationManager` constructor.
+
+## Non-Goals
+
+- Splitting `AgentWidget` rendering into pure functions (Step P / #148 — depends on this work).
+- Narrowing `ExtensionContext` for menu handlers (Step N / #146 — independent track).
+- Injecting text wrapping into `ConversationViewer` (Step O / #147 — independent track).
+
+## Background
+
+### Dual counting
+
+Both observers subscribe to the same session events:
+
+| Event                 | `record-observer.ts`         | `ui-observer.ts`                      |
+| --------------------- | ---------------------------- | ------------------------------------- |
+| `tool_execution_end`  | `record.incrementToolUses()` | `tracker.onToolEnd()` → `_toolUses++` |
+| `message_end` (usage) | `record.addUsage(delta)`     | `tracker.onUsageUpdate(delta)`        |
+
+The widget reads `bg?.toolUses ?? a.toolUses` and the conversation viewer reads `this.activity?.toolUses ?? this.record.toolUses`, preferring the tracker when alive and falling back to the record.
+After this change, there is one source: `AgentRecord`.
+
+### `execution?.` traversal
+
+`ExecutionState` holds `session` and `outputFile`.
+These are set once when the agent session is created (`agent-manager.ts` line 276).
+Consumers reach through `record.execution?.session` and `record.execution?.outputFile` in 12 distinct locations across 7 files.
+Convenience getters on `AgentRecord` eliminate the traversal and hide the `ExecutionState` structure.
+
+### `NotificationDeps` bag
+
+`NotificationManager` receives 4 fields via `NotificationDeps`: `sendMessage`, `agentActivity`, `markFinished`, `updateWidget`.
+Every method on the class uses every field.
+Per code-design convention (dependency width), a 4-field interface where every consumer uses every field is fine as a bag, but the architecture doc explicitly calls for plain parameters here.
+This is a mechanical change.
+
+## Design Overview
+
+### AgentActivityTracker changes
+
+Remove `_toolUses`, `_lifetimeUsage`, `onToolEnd`, `onUsageUpdate`, `toolUses` getter, and `lifetimeUsage` getter.
+Retain: `_activeTools`, `_toolKeySeq`, `_responseText`, `_session`, `_turnCount`, `_maxTurns`, and their associated transition methods and getters.
+
+`onToolStart` stays (tracks active tools for the widget spinner).
+A new `onToolDone(toolName)` method replaces `onToolEnd` — it removes the tool from `_activeTools` without incrementing any counter.
+This rename clarifies that the method only manages the active-tool display set.
+
+### UI observer changes
+
+The UI observer stops calling counter/accumulator methods:
+
+- `tool_execution_end` handler: calls `tracker.onToolDone(name)` (active-tool tracking only).
+- `message_end` handler: removed entirely (no more usage accumulation).
+  The `onUpdate?.()` call for usage re-render moves to the record observer path via the existing widget update flow.
+
+### AgentRecord convenience getters
+
+```typescript
+get session(): AgentSession | undefined {
+  return this.execution?.session;
+}
+
+get outputFile(): string | undefined {
+  return this.execution?.outputFile;
+}
+```
+
+Callers change from `record.execution?.session` to `record.session`.
+The `execution` field remains writable (set by `AgentManager`), but consumers no longer need to know about `ExecutionState`.
+
+### Consumer migration
+
+| File                       | Before                                             | After                                            |
+| -------------------------- | -------------------------------------------------- | ------------------------------------------------ |
+| `agent-widget.ts`          | `bg?.toolUses ?? a.toolUses`                       | `a.toolUses`                                     |
+| `agent-widget.ts`          | `getLifetimeTotal(bg?.lifetimeUsage)`              | `getLifetimeTotal(a.lifetimeUsage)`              |
+| `agent-widget.ts`          | `getSessionContextPercent(bg?.session)`            | `getSessionContextPercent(a.session)`            |
+| `conversation-viewer.ts`   | `this.activity?.toolUses ?? this.record.toolUses`  | `this.record.toolUses`                           |
+| `conversation-viewer.ts`   | `getLifetimeTotal(this.activity?.lifetimeUsage)`   | `getLifetimeTotal(this.record.lifetimeUsage)`    |
+| `conversation-viewer.ts`   | `getSessionContextPercent(this.activity?.session)` | `getSessionContextPercent(this.record.session)`  |
+| `notification.ts`          | `record.execution?.session`                        | `record.session`                                 |
+| `notification.ts`          | `record.execution?.outputFile`                     | `record.outputFile`                              |
+| `tools/get-result-tool.ts` | `record.execution?.session`                        | `record.session`                                 |
+| `tools/steer-tool.ts`      | `record.execution?.session`                        | `record.session`                                 |
+| `agent-menu.ts`            | `record.execution?.session`                        | `record.session`                                 |
+| `service-adapter.ts`       | `record.execution?.session`                        | `record.session`                                 |
+| `agent-manager.ts`         | `record.execution?.session`                        | `record.session` (in dispose paths)              |
+| `foreground-runner.ts`     | `fgState.toolUses`                                 | `record.toolUses` (in final result)              |
+| `foreground-runner.ts`     | `formatLifetimeTokens(fgState)`                    | `formatLifetimeTokens(record)` (in final result) |
+
+### NotificationManager refactoring
+
+Replace:
+
+```typescript
+export interface NotificationDeps { … }
+constructor(private deps: NotificationDeps) {}
+```
+
+With:
+
+```typescript
+constructor(
+  private sendMessage: NotificationDeps["sendMessage"],
+  private agentActivity: Map<string, AgentActivityTracker>,
+  private markFinished: (id: string) => void,
+  private updateWidget: () => void,
+) {}
+```
+
+Internal references change from `this.deps.sendMessage(…)` to `this.sendMessage(…)`.
+The `NotificationDeps` interface is removed.
+
+### Foreground runner streaming
+
+During foreground execution, `streamUpdate` reads `fgState.toolUses` and `formatLifetimeTokens(fgState)` for live spinner updates.
+After removing these from the tracker, `streamUpdate` must read from the record instead.
+The record is available only after `spawnAndWait` returns the record reference via `onSessionCreated`.
+Before that callback fires, tool uses and usage are both zero — the tracker never had meaningful data at that point either.
+`streamUpdate` will capture a `let recordRef: AgentRecord | undefined` and read `recordRef?.toolUses ?? 0` during the spinner phase.
+After `onSessionCreated`, `recordRef` is set and subsequent spinner ticks read live values from the record.
+
+## Module-Level Changes
+
+### Modified files
+
+1. `src/ui/agent-activity-tracker.ts` — Remove `_toolUses`, `_lifetimeUsage`, `onToolEnd`, `onUsageUpdate`, `toolUses` getter, `lifetimeUsage` getter.
+   Rename remaining tool-end logic to `onToolDone`.
+   Remove `addUsage` and `UsageDelta` imports.
+2. `src/ui/ui-observer.ts` — Call `tracker.onToolDone` instead of `tracker.onToolEnd`.
+   Remove `message_end` usage accumulation block.
+3. `src/agent-record.ts` — Add `get session()` and `get outputFile()` convenience getters.
+   Import `AgentSession` type for the return type.
+4. `src/notification.ts` — Remove `NotificationDeps` interface.
+   Change `NotificationManager` constructor to plain parameters.
+   Replace `this.deps.*` with `this.*`.
+   Change `record.execution?.session` → `record.session`, `record.execution?.outputFile` → `record.outputFile`.
+5. `src/ui/agent-widget.ts` — Read `a.toolUses`, `a.lifetimeUsage`, `a.session` instead of `bg?.toolUses ?? a.toolUses` etc.
+6. `src/ui/conversation-viewer.ts` — Read `this.record.toolUses`, `this.record.lifetimeUsage`, `this.record.session` instead of fallback pattern.
+7. `src/tools/get-result-tool.ts` — `record.execution?.session` → `record.session`.
+8. `src/tools/steer-tool.ts` — `record.execution?.session` → `record.session`.
+9. `src/ui/agent-menu.ts` — `record.execution?.session` → `record.session`.
+10. `src/service-adapter.ts` — `record.execution?.session` → `record.session`.
+11. `src/agent-manager.ts` — `record.execution?.session` → `record.session` in dispose paths.
+    Keep the `record.execution = { session, outputFile }` assignment unchanged (that's the write path).
+12. `src/tools/foreground-runner.ts` — Read `record.toolUses` and `formatLifetimeTokens(record)` for final result.
+    Capture `recordRef` for streaming phase.
+13. `src/tools/helpers.ts` — `buildDetails`: read `record.toolUses` and `record.lifetimeUsage` (already does); remove optional `activity` parameter's usage of `toolUses`/`lifetimeUsage` if present (verify).
+14. `src/index.ts` — Update `NotificationManager` construction from bag to plain parameters.
+15. `src/tools/background-spawner.ts` — `record?.execution?.outputFile` → `record?.outputFile`.
+
+### Test files modified
+
+1. `test/ui/agent-activity-tracker.test.ts` — Remove tests for `toolUses`, `lifetimeUsage`, `onToolEnd`, `onUsageUpdate`.
+   Add tests for `onToolDone` (active-tool removal without counting).
+2. `test/ui/ui-observer.test.ts` — Update `tool_execution_end` expectations (calls `onToolDone` not `onToolEnd`).
+   Remove `message_end` usage accumulation tests.
+3. `test/notification.test.ts` — Update `makeDeps()` factory to use plain parameters.
+   Or update `NotificationManager` construction call to match new signature.
+4. `test/agent-record.test.ts` — Add tests for `session` and `outputFile` getters.
+5. `test/conversation-viewer.test.ts` — Remove mock activity tracker usage for stats; tests use record stats directly.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+1. `AgentRecord.session` and `AgentRecord.outputFile` getters — straightforward getter tests on the record class.
+2. `AgentActivityTracker.onToolDone` — verifies active-tool removal without side effects on a counter.
+
+### Existing tests that become simpler
+
+1. `agent-activity-tracker.test.ts` — 4 test blocks for `toolUses`, `lifetimeUsage`, `onToolEnd`, `onUsageUpdate` can be removed.
+   The `onToolDone` replacement needs fewer assertions (no counter check).
+2. `ui-observer.test.ts` — The `message_end` usage accumulation tests can be removed.
+   The `tool_execution_end` test simplifies (verifies active-tool removal only).
+3. `notification.test.ts` — The `makeDeps()` helper changes shape but stays the same size.
+4. `conversation-viewer.test.ts` — Tests that mock `activity.toolUses` and `activity.lifetimeUsage` can simplify to reading from the record.
+
+### Existing tests that must stay
+
+1. `record-observer.test.ts` — All tests remain as-is.
+   The record observer is the sole source of `incrementToolUses` and `addUsage` calls now.
+2. `agent-record.test.ts` — All existing tests for `incrementToolUses`, `addUsage`, `incrementCompactions` remain.
+3. `notification.test.ts` — Pure helper tests (`escapeXml`, `getStatusLabel`, `formatTaskNotification`, `buildNotificationDetails`, `buildEventData`) remain unchanged.
+
+## TDD Order
+
+1. **Red→Green: `AgentRecord` convenience getters.**
+   Add tests for `record.session` and `record.outputFile` (returns `undefined` when no execution, delegates when set).
+   Implement the getters.
+   Commit: `feat: add session and outputFile convenience getters to AgentRecord (#144)`
+
+2. **Green→Green: Migrate callsites from `execution?.` to convenience getters.**
+   Update all 12 callsites across 7 files (`notification.ts`, `agent-widget.ts`, `agent-menu.ts`, `get-result-tool.ts`, `steer-tool.ts`, `service-adapter.ts`, `agent-manager.ts`, `background-spawner.ts`).
+   No test changes needed — existing tests pass.
+   Run `pnpm run check` to verify.
+   Commit: `refactor: use AgentRecord.session and .outputFile convenience getters (#144)`
+
+3. **Red→Green: Rename `onToolEnd` to `onToolDone` and remove counter.**
+   Update `agent-activity-tracker.test.ts`: remove `onToolEnd` counter tests, add `onToolDone` tests (active-tool removal only, no `toolUses` assertion).
+   Implement: rename method, remove `_toolUses++`.
+   Update `ui-observer.ts` to call `onToolDone`.
+   Update `ui-observer.test.ts` expectations.
+   Commit: `refactor: rename AgentActivityTracker.onToolEnd to onToolDone (#144)`
+
+4. **Red→Green: Remove `_toolUses` and `_lifetimeUsage` from tracker.**
+   Update `agent-activity-tracker.test.ts`: remove `toolUses` getter, `lifetimeUsage` getter, and `onUsageUpdate` test blocks.
+   Implement: remove `_toolUses`, `_lifetimeUsage`, `toolUses` getter, `lifetimeUsage` getter, `onUsageUpdate` method, `UsageDelta` type, `addUsage` import.
+   Update `ui-observer.ts`: remove `message_end` usage accumulation block.
+   Update `ui-observer.test.ts`: remove `message_end` usage tests.
+   Run `pnpm run check` to catch any remaining references.
+   Commit: `refactor: remove duplicate stats from AgentActivityTracker (#144)`
+
+5. **Green→Green: Migrate UI consumers to read stats from `AgentRecord`.**
+   Update `agent-widget.ts`: replace `bg?.toolUses ?? a.toolUses` → `a.toolUses`, `bg?.lifetimeUsage` → `a.lifetimeUsage`, `bg?.session` → `a.session`.
+   Update `conversation-viewer.ts`: replace `activity?.toolUses ?? record.toolUses` → `record.toolUses`, `activity?.lifetimeUsage` → `record.lifetimeUsage`, `activity?.session` → `record.session`.
+   Update `foreground-runner.ts`: read stats from record instead of tracker for final result.
+   Capture `recordRef` for streaming phase.
+   Update `conversation-viewer.test.ts` if any tests mock activity stats.
+   Commit: `refactor: read stats from AgentRecord in UI consumers (#144)`
+
+6. **Red→Green: Replace `NotificationDeps` with plain parameters.**
+   Update `notification.test.ts`: change `makeDeps()` → individual parameters in `NotificationManager` constructor calls.
+   Implement: remove `NotificationDeps` interface, change constructor to plain parameters, replace `this.deps.*` with `this.*`.
+   Update `index.ts`: change `NotificationManager` construction to pass individual arguments.
+   Commit: `refactor: dissolve NotificationDeps into plain constructor parameters (#144)`
+
+## Risks and Mitigations
+
+| Risk                                                                                              | Mitigation                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foreground streaming reads stale `recordRef` before `onSessionCreated` fires                      | Before `onSessionCreated`, both tracker and record have zero stats — behavior is unchanged.  Capture `recordRef` as `undefined` initially and guard with `??`.                                                                                              |
+| Widget reads `a.toolUses` but `a` is the snapshot from `listAgents()` — might be stale            | `listAgents()` returns live `AgentRecord` references (not copies), so `a.toolUses` reflects the latest record-observer increment.                                                                                                                           |
+| Removing `lifetimeUsage` from tracker breaks `formatLifetimeTokens(fgState)` in foreground runner | Step 5 explicitly migrates this callsite to `formatLifetimeTokens(record)`.  The TDD order places the removal (step 4) before the migration (step 5), but step 4's `pnpm run check` will catch the type error and both steps can be merged if needed.       |
+| `buildDetails` in `helpers.ts` accepts an `activity` parameter for `turnCount`/`maxTurns`         | `turnCount` and `maxTurns` remain on the tracker — only `toolUses` and `lifetimeUsage` are removed.  `buildDetails` reads `record.toolUses` and `record.lifetimeUsage` already; it reads `activity?.turnCount` and `activity?.maxTurns` which remain valid. |
+
+## Open Questions
+
+- None — the architecture doc prescribes the exact changes and the design is straightforward.

package/docs/plans/0148-split-agent-widget-rendering.md

@@ -0,0 +1,255 @@
+---
+issue: 148
+issue_title: "Split AgentWidget rendering from lifecycle (Phase 9, Step P)"
+---
+
+# Split AgentWidget rendering from lifecycle
+
+## Problem Statement
+
+`AgentWidget` (374 lines) mixes rendering, lifecycle management, spinner animation, state filtering, and status bar management in a single class.
+`renderWidget` alone is ~109 lines, and `renderFinishedLine` adds another ~40.
+The constructor takes 3 concrete collaborators (`AgentManager`, `Map<string, AgentActivityTracker>`, `AgentTypeRegistry`) with no interface extraction.
+Rendering logic cannot be unit-tested without instantiating the full widget with its lifecycle machinery.
+
+## Goals
+
+- Extract pure rendering functions from `AgentWidget` into `ui/widget-renderer.ts`.
+- Make `AgentWidget` a thin lifecycle/polling wrapper that delegates to pure render functions.
+- Enable direct unit testing of rendering logic with plain data — no widget lifecycle, no mocks for `setInterval`/`setWidget`/`requestRender`.
+
+## Non-Goals
+
+- Changing the visual output of the widget (this is a pure refactor).
+- Extracting the status bar logic into a separate module (could follow up).
+- Narrowing the `AgentManager` dependency to an interface (tracked separately in the architecture doc).
+- Injecting `truncateToWidth` (tracked as #147, Step O — an independent track).
+
+## Background
+
+### Dependency: #144 (Step L) — Consolidate observation model
+
+Issue #144 is **closed/implemented**.
+The renderer now reads stats (`toolUses`, `lifetimeUsage`, `compactionCount`) from `AgentRecord` and live UI state (`activeTools`, `responseText`, `turnCount`, `maxTurns`) from `AgentActivityTracker`.
+No dual-counting fallback exists.
+
+### Existing pure helpers
+
+`ui/display.ts` already contains stateless formatting functions (`formatMs`, `formatTurns`, `formatSessionTokens`, `describeActivity`, `getDisplayName`, `getPromptModeLabel`, `SPINNER`, `ERROR_STATUSES`, `Theme`).
+The new `widget-renderer.ts` will consume these — it does not duplicate them.
+
+### Rendering data flow
+
+The widget's `renderWidget` currently:
+
+1. Calls `this.manager.listAgents()` to get `AgentRecord[]`.
+2. Categorizes into running/queued/finished.
+3. Filters finished agents via `this.shouldShowFinished()`.
+4. Looks up `this.agentActivity.get(a.id)` for live stats.
+5. Calls `this.registry` for display names.
+6. Reads `this.widgetFrame` for spinner animation.
+7. Assembles tree-style lines with overflow logic.
+
+Steps 3–7 are pure given the right inputs.
+Steps 1–2 are also pure categorization.
+
+## Design Overview
+
+### Separation of concerns
+
+The rendering extraction splits the widget into two layers:
+
+1. **`widget-renderer.ts`** — Pure functions that accept data and return `string[]`.
+   No `this`, no timers, no SDK types, no side effects.
+2. **`agent-widget.ts`** — Thin lifecycle wrapper that owns timers, UICtx, finished-turn aging, and calls the renderer with live data.
+
+### Renderer input shape
+
+Rather than passing the full `AgentRecord` class (which carries mutation methods and phase collaborators), the renderer receives a plain data slice:
+
+```typescript
+/** Minimal agent snapshot for rendering — no class methods, no mutation surface. */
+export interface WidgetAgent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly status: string;
+  readonly description: string;
+  readonly toolUses: number;
+  readonly startedAt: number;
+  readonly completedAt?: number;
+  readonly error?: string;
+  readonly lifetimeUsage?: Readonly<LifetimeUsage>;
+  readonly compactionCount: number;
+}
+```
+
+This is structurally compatible with `AgentRecord` (the class satisfies it), so no mapping code is needed at the call site — `listAgents()` returns `AgentRecord[]` which satisfies `WidgetAgent[]`.
+
+### Renderer input for activity
+
+Activity state is read from `AgentActivityTracker`.
+The renderer needs a read-only view per agent:
+
+```typescript
+/** Read-only activity snapshot for widget rendering. */
+export interface WidgetActivity {
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+  readonly turnCount: number;
+  readonly maxTurns?: number;
+  readonly session?: SessionLike;
+}
+```
+
+`AgentActivityTracker` already satisfies this structurally (it exposes these as getters).
+
+### Agent config lookup
+
+The renderer needs `getDisplayName` and `getPromptModeLabel`, which take a `SubagentType` and an `AgentConfigLookup`.
+The renderer accepts `AgentConfigLookup` (the existing interface from `agent-types.ts`) — not the concrete `AgentTypeRegistry` class.
+
+### Renderer API
+
+```typescript
+/** Pure rendering of the widget body. Returns lines to display. */
+export function renderWidgetLines(params: {
+  agents: readonly WidgetAgent[];
+  activityMap: ReadonlyMap<string, WidgetActivity>;
+  registry: AgentConfigLookup;
+  spinnerFrame: number;
+  terminalWidth: number;
+  shouldShowFinished: (agentId: string, status: string) => boolean;
+}): string[];
+
+/** Pure rendering of a single finished agent line (no tree connector prefix). */
+export function renderFinishedLine(
+  agent: WidgetAgent,
+  activity: WidgetActivity | undefined,
+  registry: AgentConfigLookup,
+  theme: Theme,
+): string;
+
+/** Pure rendering of a single running agent (header + activity lines, no tree connector prefix). */
+export function renderRunningLines(
+  agent: WidgetAgent,
+  activity: WidgetActivity | undefined,
+  registry: AgentConfigLookup,
+  spinnerFrame: number,
+  theme: Theme,
+): [header: string, activity: string];
+```
+
+The top-level `renderWidgetLines` encapsulates the full categorization, overflow logic, and tree-connector fixup.
+The per-agent functions are exported for fine-grained testing.
+
+The `shouldShowFinished` callback is injected rather than re-implementing the aging logic inside the renderer, keeping the renderer pure and the aging state in the widget.
+
+### Call site in AgentWidget
+
+```typescript
+// Inside renderWidget(tui, theme):
+const w = tui.terminal.columns;
+return renderWidgetLines({
+  agents: this.manager.listAgents(),
+  activityMap: this.agentActivity,
+  registry: this.registry,
+  spinnerFrame: this.widgetFrame,
+  terminalWidth: w,
+  shouldShowFinished: (id, status) => this.shouldShowFinished(id, status),
+});
+```
+
+The widget's `renderWidget` method shrinks to ~5 lines.
+
+### Tell-Don't-Ask verification
+
+The renderer receives pre-collected data and returns formatted strings.
+It does not reach through collaborators — it reads flat fields from `WidgetAgent` and `WidgetActivity`.
+The widget tells the renderer "render this data"; the renderer returns lines.
+No Law of Demeter violations.
+
+## Module-Level Changes
+
+### New file: `src/ui/widget-renderer.ts`
+
+- `WidgetAgent` interface (structural subset of `AgentRecord`).
+- `WidgetActivity` interface (structural subset of `AgentActivityTracker`).
+- `renderWidgetLines()` — top-level rendering with categorization, overflow, tree connectors.
+- `renderFinishedLine()` — single finished-agent line.
+- `renderRunningLines()` — single running-agent header + activity pair.
+- Imports from `display.ts` (`SPINNER`, `ERROR_STATUSES`, `formatMs`, `formatTurns`, `formatSessionTokens`, `describeActivity`, `getDisplayName`, `getPromptModeLabel`, `Theme`), from `usage.ts` (`getLifetimeTotal`, `getSessionContextPercent`, `LifetimeUsage`, `SessionLike`), and from `@earendil-works/pi-tui` (`truncateToWidth`).
+
+### Modified: `src/ui/agent-widget.ts`
+
+- Remove `renderWidget()` method body — replace with call to `renderWidgetLines()`.
+- Remove `renderFinishedLine()` method entirely.
+- Remove direct imports of display helpers and usage helpers that are now only consumed by `widget-renderer.ts`.
+- Keep: constructor, `setUICtx`, `onTurnStart`, `ensureTimer`, `shouldShowFinished`, `markFinished`, `update`, `dispose`, `UICtx` type, `MAX_WIDGET_LINES`.
+- The inline type on `renderFinishedLine`'s parameter `a` is replaced by the `WidgetAgent` import.
+
+### New file: `test/widget-renderer.test.ts`
+
+- Unit tests for `renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`.
+- Uses plain data objects (no mocks for `AgentManager`, `setInterval`, or SDK).
+- Stub `Theme` matching the pattern in `test/renderer.test.ts`.
+
+### No changes to
+
+- `src/index.ts` — the widget is constructed the same way; renderer is internal to the widget module.
+- `src/ui/display.ts` — unchanged; consumed by the new renderer.
+- `src/usage.ts` — unchanged.
+
+## Test Impact Analysis
+
+1. The extraction enables direct unit testing of widget rendering that was previously impossible — testing `renderWidget` required constructing a full `AgentWidget` with mocked `AgentManager`, fake timers, and a stubbed UICtx.
+   The new tests cover: finished-agent line formatting (all status variants), running-agent header/activity rendering, overflow logic, tree-connector fixup, empty-state handling, and `shouldShowFinished` filtering.
+2. No existing tests become redundant — there are currently **no** unit tests for `AgentWidget` rendering.
+   The existing `display.test.ts` tests lower-level formatters and remains as-is.
+3. `renderer.test.ts` tests the notification renderer — unrelated, stays as-is.
+
+## TDD Order
+
+1. **Red → Green:** Test `renderFinishedLine` for a completed agent (success icon, stats, duration).
+   Commit: `test: add renderFinishedLine tests for completed status`
+
+2. **Red → Green:** Test `renderFinishedLine` for error/aborted/steered/stopped statuses (icon and status text variations).
+   Commit: `test: renderFinishedLine error and terminal status variants`
+
+3. **Red → Green:** Test `renderRunningLines` (spinner frame, stats, activity description, token display).
+   Commit: `test: add renderRunningLines tests`
+
+4. **Red → Green:** Test `renderWidgetLines` — basic case with one running agent (heading, tree connectors).
+   Commit: `test: renderWidgetLines single running agent`
+
+5. **Red → Green:** Test `renderWidgetLines` — mixed running + finished + queued, verifying categorization and ordering.
+   Commit: `test: renderWidgetLines mixed agent states`
+
+6. **Red → Green:** Test `renderWidgetLines` — overflow cap with many agents, verifying the priority (running > queued > finished) and overflow summary line.
+   Commit: `test: renderWidgetLines overflow behavior`
+
+7. **Red → Green:** Test `renderWidgetLines` — empty state returns `[]`; finished-only state uses dim heading.
+   Commit: `test: renderWidgetLines empty and finished-only states`
+
+8. **Green → Refactor:** Extract `renderFinishedLine`, `renderRunningLines`, and `renderWidgetLines` into `src/ui/widget-renderer.ts`.
+   All tests pass against the extracted module.
+   Commit: `refactor: extract widget rendering into widget-renderer`
+
+9. **Green → Refactor:** Wire `AgentWidget.renderWidget()` to delegate to `renderWidgetLines()`.
+   Remove the inlined rendering logic from `agent-widget.ts`.
+   Remove unused imports.
+   Commit: `refactor: AgentWidget delegates rendering to widget-renderer`
+
+10. **Verify:** Run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
+    Commit: none (verification only).
+
+## Risks and Mitigations
+
+| Risk                                                                                                           | Mitigation                                                                                                                                                                |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Structural compatibility between `AgentRecord` and `WidgetAgent` could drift if `AgentRecord` renames a field. | TypeScript's structural checking catches this at the call site in `agent-widget.ts` — `listAgents()` returns `AgentRecord[]` which must satisfy `readonly WidgetAgent[]`. |
+| `truncateToWidth` is an external dependency (`@earendil-works/pi-tui`) in the renderer.                        | Step O (#147) will inject it; for now, the renderer imports it directly, matching the current widget behavior.                                                            |
+| Overflow logic is complex and hand-tested — extraction could introduce subtle line-count bugs.                 | TDD steps 4–7 exercise overflow edge cases before the extraction step. The extraction is a mechanical move with tests already passing.                                    |
+
+## Open Questions
+
+- None — the design follows the architecture doc's Step P specification and the dependency (#144) is already implemented.