@gotgenes/pi-subagents 16.5.0 → 16.6.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [16.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.5.0...pi-subagents-v16.6.0) (2026-06-17)
+
+
+### Features
+
+* read widget activity off subagent records ([#421](https://github.com/gotgenes/pi-packages/issues/421)) ([df09e03](https://github.com/gotgenes/pi-packages/commit/df09e03d122c391212507c4c5d8436cd4a0561ba))
+
 ## [16.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.4.0...pi-subagents-v16.5.0) (2026-06-17)
 
 

package/docs/architecture/architecture.md

@@ -953,16 +953,18 @@ Step 8 is the user-driven UI reconsideration the disentangled core finally makes
 The deeper target in the [first-principles refinement](#first-principles-refinement-and-the-deeper-target) — metrics as a pure observer projection rather than mutable fields — is deliberately **not** forced here.
 Folding the live activity onto the record (the single owner of run state, consistent with Phase 17's `SubagentState`) removes the duplication without inventing the asynchronous-observation seam the `improvement-discovery` skill warns is essential, not structural.
 
-1. **Fold run metrics and live activity onto the core record (pure addition).**
+1. **✅ Fold run metrics and live activity onto the core record (pure addition) — complete (v16.5.0).**
    ([#420]) Target: `lifecycle/subagent-state.ts`, `observation/record-observer.ts`, `lifecycle/subagent.ts`.
    Extend the single owned run-state value object with `turnCount`, active tools, and response text; have the already-subscribed `record-observer` handle `turn_end`, `tool_execution_start`, `message_start`, `message_update`; expose read-only `turnCount`/`maxTurns`/`activeTools`/`responseText` getters on `Subagent`.
    `AgentActivityTracker` still exists; nothing reads the new getters yet (tidy-first).
    Smell: Category C. Outcome: `Subagent` is the single home for all run state; getters available for migration.
-2. **Migrate every activity reader to the record getters.**
+   Landed: `SubagentState` owns `turnCount`/`activeTools`/`responseText` plus their transition methods; `record-observer` populates them on a single subscription; `Subagent` exposes the four read-only getters; +27 tests (1031 → 1058).
+2. **✅ Migrate every activity reader to the record getters — complete.**
    ([#421]) Target: `ui/widget-renderer.ts`, `ui/conversation-viewer.ts`, `ui/agent-menu.ts`, `tools/foreground-runner.ts`, `observation/notification.ts`.
    Switch each reader from `AgentActivityTracker` to the record getters added in Step 1 (widget-renderer reads activity off `listAgents()`; viewer/menu drop the `activity` param; notification reads `turnCount`/`maxTurns` off the record).
    Smell: Category C (Law of Demeter).
    Outcome: no consumer references `AgentActivityTracker`.
+   Landed: `WidgetAgent` folds the live-activity fields and a `contextPercent` projection; `AgentWidget` projects records; `ConversationViewer`, `AgentsMenuHandler`, `buildDetails`, and `buildNotificationDetails` read off the record; `NotificationSystem.cleanupCompleted` removed; `SubagentEventsObserver` returns early on consumed results; +8 tests (1058 → 1066).
 3. **Delete `AgentActivityTracker` and `ui-observer`; drop the activity map from the runtime and spawn tools.**
    ([#422]) Target: `ui/agent-activity-tracker.ts` (delete), `ui/ui-observer.ts` (delete), `runtime.ts`, `tools/foreground-runner.ts`, `tools/background-spawner.ts`.
    The spawn tools stop constructing trackers, subscribing, and populating maps; `SubagentRuntime.agentActivity` is removed.
@@ -1006,8 +1008,8 @@ Folding the live activity onto the record (the single owner of run state, consis
 
 ```mermaid
 flowchart TB
-    S1["1 — Fold metrics + activity onto record (#420)"]
-    S2["2 — Migrate readers to record getters (#421)"]
+    S1["1 — Fold metrics + activity onto record (#420) ✅"]
+    S2["2 — Migrate readers to record getters (#421) ✅"]
     S3["3 — Delete tracker + ui-observer, drop activity map (#422)"]
     S4["4 — Widget self-drives on events (#423)"]
     S5["5 — Drop widget dep from subagent tool (#424)"]
@@ -1058,7 +1060,7 @@ Detailed records are preserved in per-phase history files:
 | 15    | Domain model evolution                              | Complete            | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
 | 16    | Invert dependencies (extensions on a minimal core)  | Complete            | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
 | 17    | Core consolidation                                  | Complete            | [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md)             |
-| 18    | Reconsider UI (first principles)                    | Proposed            | this document, [Phase 18](#phase-18-reconsider-ui-from-first-principles)             |
+| 18    | Reconsider UI (first principles)                    | In progress         | this document, [Phase 18](#phase-18-reconsider-ui-from-first-principles)             |
 
 ### Structural refactoring issues
 

package/docs/plans/0421-migrate-activity-readers-to-record-getters.md

@@ -0,0 +1,309 @@
+---
+issue: 421
+issue_title: "pi-subagents: migrate activity-tracker readers to the record getters"
+---
+
+# Migrate activity-tracker readers to the record getters
+
+## Problem Statement
+
+Phase 18 Step 1 ([#420]) folded the live-activity fields (`turnCount`, `activeTools`, `responseText`, `maxTurns`) onto the single owned run-state value object and exposed them as read-only getters on `Subagent`, but nothing reads them yet.
+Five consumers still reach into a separate UI `AgentActivityTracker` for data the record now exposes directly — a Law-of-Demeter coupling that keeps the activity tier entangled with the core.
+This step switches each reader from the tracker to the record getters so that no reader reads activity off `AgentActivityTracker`, unblocking the tracker's deletion in Step 3 ([#422]).
+
+This is Phase 18 Step 2 of the architecture roadmap (`docs/architecture/architecture.md`).
+It is a reader migration: the producer plumbing that still constructs trackers, subscribes `ui-observer`, and populates the runtime activity map (`foreground-runner`, `background-spawner`, `runtime.ts`, `ui-observer.ts`) is left in place and removed in Step 3.
+The reader-held map dependencies in `notification`, `agent-widget`, and `agent-menu` — files Step 3 does not touch — are removed here.
+
+## Goals
+
+- Switch `widget-renderer` to read live activity off the `Subagent` records returned by `listAgents()` rather than a parallel `activityMap`, folding the `WidgetActivity` interface into `WidgetAgent`.
+- Drop the `activity` constructor param from `ConversationViewer`; read `activeTools` / `responseText` off `this.record`.
+- Drop the `AgentActivityReader` dependency from `AgentsMenuHandler`.
+- Migrate `runForeground` and `buildDetails` to read streaming state (`turnCount`, `maxTurns`, `activeTools`, `responseText`) off the `Subagent` they already hold.
+- Migrate `buildNotificationDetails` to read `turnCount` / `maxTurns` off the record, and drop the `agentActivity` map dependency (and the now-vestigial `cleanupCompleted` method) from `NotificationManager`.
+- Project each `Subagent` into a pure-data `WidgetAgent` snapshot inside `AgentWidget` (with a `contextPercent` field), keeping `widget-renderer` a pure function of plain data.
+
+This change is **not breaking**.
+The published service surface (`src/service/service.ts`) exposes `SubagentRecord` / `SubagentStatus`, neither of which changes.
+There is one accepted observable behavior change in the widget (below), but no API, config, or default changes on upgrade without a user edit.
+
+### Accepted behavior change
+
+Today the widget shows **no** turn count on finished-agent lines because the activity tracker is deleted on completion (foreground deletes it after `spawnAndWait`; `NotificationManager.sendCompletion` deletes it for background agents).
+The record's `turnCount` getter persists, so once `widget-renderer` reads off `listAgents()` records, finished lines will show `⟳N`.
+This is **accepted** (confirmed with the operator): the deletion-on-completion behavior was a UI-state artifact, and showing the turn count consistently is the more correct outcome.
+Preserving the old behavior would require the widget to track which finished agents were "cleaned up" — reintroducing exactly the coupling this phase removes.
+
+## Non-Goals
+
+- Deleting `AgentActivityTracker` / `ui-observer`, or removing the producer plumbing in `foreground-runner` / `background-spawner` / `runtime.ts` that still constructs trackers, subscribes, and populates the activity map — Step 3 ([#422]).
+- Dropping the `widget` and `agentActivity` constructor params from `AgentTool` — Step 5 ([#424]).
+- Making the widget self-drive its timer from lifecycle events instead of spawn-tool calls — Step 4 ([#423]).
+- Reconciling the public event contract (`SUBAGENT_EVENTS.ACTIVITY`) — Step 6 ([#425]).
+- Changing `SubagentState`, `record-observer`, or the getters themselves — landed in Step 1 ([#420]).
+
+## Background
+
+Relevant modules and how they relate:
+
+- `src/lifecycle/subagent.ts` — exposes the four read-only getters added in Step 1: `turnCount` and `activeTools` and `responseText` delegate to the owned `SubagentState`; `maxTurns` returns `this.execution.maxTurns`.
+  Also exposes `getContextPercent(): number | null` (delegates to `subagentSession.getContextPercent()`), the live context-window utilization.
+- `src/ui/widget-renderer.ts` — pure rendering functions.
+  `renderFinishedLine` / `renderRunningLines` take a `WidgetAgent` plus a `WidgetActivity | undefined`; `renderWidgetLines` takes an `activityMap: ReadonlyMap<string, WidgetActivity>`.
+  `renderRunningLines` computes the context percent via `activity?.session ? getSessionContextPercent(activity.session) : null` — a reach into session stats from a module documented as taking no SDK types.
+- `src/ui/agent-widget.ts` — `AgentWidget` holds the `agentActivity` map and passes `manager.listAgents()` (Subagents, structurally accepted as `WidgetAgent`) plus the map to `renderWidgetLines`.
+- `src/ui/conversation-viewer.ts` — `ConversationViewer` takes an `activity: AgentActivityTracker | undefined`; reads `activity.activeTools` / `activity.responseText` in `buildContentLines` for the running streaming indicator.
+- `src/ui/agent-menu.ts` — defines `AgentActivityReader` (`get(id): AgentActivityTracker | undefined`), takes it as a constructor param, and reads `this.agentActivity.get(record.id)` in `viewAgentConversation` to pass to `ConversationViewer`.
+- `src/tools/foreground-runner.ts` — constructs `fgState = new AgentActivityTracker(...)`, subscribes `ui-observer`, populates the activity map, and reads `fgState.turnCount` / `fgState.maxTurns` / `fgState.activeTools` / `fgState.responseText` in `streamUpdate`; passes `fgState` to `buildDetails`.
+- `src/tools/helpers.ts` — `buildDetails(base, record, activity?, overrides?)` reads `activity?.turnCount` and `activity?.maxTurns`.
+  Two call sites: `runForeground` (passes `fgState`) and `AgentTool` resume (no activity arg).
+- `src/observation/notification.ts` — `buildNotificationDetails(record, resultMaxLen, activity?)` reads `activity?.turnCount` / `activity?.maxTurns`.
+  `NotificationManager` holds the `agentActivity` map and deletes from it in `sendCompletion` and `cleanupCompleted`.
+- `src/observation/subagent-events-observer.ts` — `onSubagentCompleted` calls `notifications.cleanupCompleted(record.id)` when `record.notification?.resultConsumed`, else `notifications.sendCompletion(record)`.
+- `src/index.ts` — constructs `NotificationManager`, `AgentWidget`, and `AgentsMenuHandler`, each currently passed `runtime.agentActivity`.
+
+AGENTS.md / code-design constraints that apply:
+
+- `widget-renderer.ts` is a pure rendering module ("stateless: they receive data and return formatted strings.
+  No timers, no SDK types, no side effects").
+  The migration keeps it pure and **narrows** it: the precomputed `contextPercent` field lets it drop the `SessionLike` / `getSessionContextPercent` imports, removing the session reach-through.
+- `AgentWidget` is the adapter between the live manager/records and the pure renderer; the explicit `Subagent` → `WidgetAgent` projection belongs there (DIP, narrow data boundary).
+- `getSessionContextPercent` and `SessionLike` stay in `usage.ts` — still used by `subagent-session.ts` and `getSessionTokens`, so removing the widget-renderer import creates no dead code.
+
+## Design Overview
+
+### `WidgetAgent` absorbs the activity fields (widget-renderer)
+
+`WidgetActivity` is removed; its fields move onto `WidgetAgent` as plain data, plus a precomputed context percent:
+
+```typescript
+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;
+	// Folded-in live activity (was WidgetActivity)
+	readonly turnCount: number;
+	readonly maxTurns?: number;
+	readonly activeTools: ReadonlyMap<string, string>;
+	readonly responseText: string;
+	readonly contextPercent: number | null;
+}
+```
+
+`renderFinishedLine(agent, registry, theme)` and `renderRunningLines(agent, registry, spinnerFrame, theme)` drop the `WidgetActivity | undefined` parameter and read `agent.turnCount` / `agent.maxTurns` / `agent.activeTools` / `agent.responseText` directly.
+`renderRunningLines` uses `agent.contextPercent` in place of `activity?.session ? getSessionContextPercent(activity.session) : null`.
+`renderWidgetLines` and `buildSections` drop the `activityMap` parameter.
+Because every `WidgetAgent` now carries activity, the old "no activity provided → omit turn count / show `thinking…`" branch is gone — `describeActivity(emptyMap, "")` already returns the `thinking…` string for an idle running agent, so the running-line text is preserved.
+
+### `AgentWidget` projects records into snapshots
+
+`AgentWidget` drops its `agentActivity` constructor param and field.
+`renderWidget` maps each record through a local projection before handing the array to the pure renderer:
+
+```typescript
+private toWidgetAgent(record: Subagent): WidgetAgent {
+	return {
+		id: record.id,
+		type: record.type,
+		status: record.status,
+		description: record.description,
+		toolUses: record.toolUses,
+		startedAt: record.startedAt,
+		completedAt: record.completedAt,
+		error: record.error,
+		lifetimeUsage: record.lifetimeUsage,
+		compactionCount: record.compactionCount,
+		turnCount: record.turnCount,
+		maxTurns: record.maxTurns,
+		activeTools: record.activeTools,
+		responseText: record.responseText,
+		contextPercent: record.getContextPercent(),
+	};
+}
+```
+
+`renderWidget` then calls `renderWidgetLines({ agents: this.manager.listAgents().map(r => this.toWidgetAgent(r)), registry, … })` with no `activityMap`.
+`assembleWidgetState` keeps consuming raw records via its `AgentSummary` shape (id / status / completedAt) — unchanged.
+This makes the snapshot boundary explicit: the renderer depends only on plain data; `AgentWidget` owns the projection (Tell-Don't-Ask — it asks each record once and hands forward a value).
+
+### `ConversationViewer` reads off the record
+
+The `activity` constructor param and field are removed.
+`buildContentLines` reads the streaming indicator inputs off the record it already holds:
+
+```typescript
+if (this.record.status === "running") {
+	lines.push(...formatStreamingIndicator(
+		this.record.activeTools,
+		this.record.responseText,
+		width,
+		th,
+	));
+}
+```
+
+The `&& this.activity` guard is dropped — a running record always exposes `activeTools` / `responseText` (empty / `""` when idle), and `describeActivity` renders the idle case as `thinking…`, matching the prior no-tracker fallback.
+
+### `AgentsMenuHandler` drops the reader
+
+The `AgentActivityReader` interface and the `agentActivity` constructor param are removed.
+`viewAgentConversation` no longer looks up a tracker; it constructs `ConversationViewer` without an `activity` field.
+
+### `buildDetails` / `runForeground` read off the record
+
+`buildDetails` drops its `activity?: AgentActivityTracker` parameter; the structural `record` param gains `turnCount?: number` and `maxTurns?: number`, and the body reads `record.turnCount` / `record.maxTurns`:
+
+```typescript
+export function buildDetails(
+	base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
+	record: {
+		toolUses: number; startedAt: number; completedAt?: number; status: string;
+		error?: string; id?: string; lifetimeUsage: LifetimeUsage;
+		turnCount?: number; maxTurns?: number;
+	},
+	overrides?: Partial<AgentDetails>,
+): AgentDetails { … turnCount: record.turnCount, maxTurns: record.maxTurns … }
+```
+
+`Subagent` satisfies this structurally (the getters supply `turnCount` / `maxTurns`).
+In `runForeground`, `streamUpdate` reads `recordRef?.turnCount ?? 1`, `recordRef?.activeTools ?? new Map()`, `recordRef?.responseText ?? ""`, and `execution.effectiveMaxTurns` for `maxTurns` (the runner already holds this constant; `recordRef` is undefined until `onSessionCreated`).
+The final `buildDetails(presentation.detailBase, record, fgState, { tokens })` becomes `buildDetails(presentation.detailBase, record, { tokens })`.
+The `fgState` tracker, its `subscribeUIObserver` subscription, and the `agentActivity.set` / `delete` calls remain (producer plumbing removed in Step 3) but are no longer read.
+
+### `buildNotificationDetails` / `NotificationManager`
+
+`buildNotificationDetails(record, resultMaxLen)` drops the `activity?` param and reads `record.turnCount` / `record.maxTurns`.
+`NotificationManager` drops the `agentActivity` constructor param and field; `sendCompletion` keeps only the nudge scheduling.
+`cleanupCompleted` only ever deleted a map entry, so it becomes vestigial and is **removed** from both `NotificationSystem` and `NotificationManager`.
+`SubagentEventsObserver.onSubagentCompleted` updates its `resultConsumed` branch to simply `return` (skip the nudge) instead of calling `cleanupCompleted`.
+
+### Consumer call-site check (index.ts)
+
+```typescript
+const notifications = new NotificationManager((msg, opts) => pi.sendMessage(msg, opts));
+const widget = new AgentWidget(manager, registry);
+const agentsMenu = new AgentsMenuHandler(manager, registry, settings, new FsAgentFileOps(), …);
+```
+
+All three constructions drop the `runtime.agentActivity` argument.
+`runtime.agentActivity` itself stays (still written by the spawn tools; removed in Step 3).
+
+## Module-Level Changes
+
+- `src/ui/widget-renderer.ts` — remove the `WidgetActivity` interface; fold its fields plus `contextPercent` into `WidgetAgent`; drop the `WidgetActivity | undefined` param from `renderFinishedLine` / `renderRunningLines`; drop `activityMap` from `buildSections` / `renderWidgetLines`; remove the `SessionLike` and `getSessionContextPercent` imports (keep `getLifetimeTotal`).
+- `src/ui/agent-widget.ts` — drop the `agentActivity` constructor param and field; add the `toWidgetAgent` projection; map `listAgents()` through it in `renderWidget`; drop the `AgentActivityTracker` import.
+- `src/ui/conversation-viewer.ts` — drop the `activity` field and `ConversationViewerOptions.activity`; read `activeTools` / `responseText` off `this.record`; drop the `AgentActivityTracker` import.
+- `src/ui/agent-menu.ts` — remove the `AgentActivityReader` interface and the `agentActivity` constructor param; drop the tracker lookup in `viewAgentConversation`; drop the `AgentActivityTracker` import.
+- `src/tools/helpers.ts` — `buildDetails` drops the `activity?` param and reads `record.turnCount` / `record.maxTurns` (param type gains the two optional fields); drop the `AgentActivityTracker` import.
+- `src/tools/foreground-runner.ts` — `streamUpdate` and the final `buildDetails` call read off `recordRef` / `record`; the `fgState` construction, `subscribeUIObserver`, and map writes stay (Step 3).
+- `src/observation/notification.ts` — `buildNotificationDetails` drops the `activity?` param and reads off the record; `NotificationManager` drops the `agentActivity` param/field and the `delete` calls; remove `cleanupCompleted` from `NotificationSystem` and the class; drop the `AgentActivityTracker` import.
+- `src/observation/subagent-events-observer.ts` — `onSubagentCompleted` `resultConsumed` branch returns without calling `cleanupCompleted`.
+- `src/index.ts` — drop `runtime.agentActivity` from the `NotificationManager`, `AgentWidget`, and `AgentsMenuHandler` constructions.
+- `.pi/skills/package-pi-subagents/SKILL.md` — update the module-dependency-flow line `widget ─polls─→ AgentActivityTracker map` to reflect that the widget now polls `listAgents()` records.
+- `docs/architecture/architecture.md` — add a `Landed:` line to the Phase 18 Step 2 entry during implementation (the entry text already describes the work).
+
+Test files (see TDD Order for which step each lands in):
+
+- `test/helpers/make-subagent.ts` — add `turnCount` / `activeTools` / `responseText` / `maxTurns` shorthands to `createTestSubagent` so reader tests can seed activity on records.
+- `test/widget-renderer.test.ts` — remove `WidgetActivity` / `makeActivity`; fold activity defaults into `makeAgent` (`turnCount`, `maxTurns`, `activeTools`, `responseText`, `contextPercent`); drop the `activity` arg from render calls and `activityMap` from `renderWidgetLines` calls; update the former "omit turn count when no activity" cases to assert the turn count now renders; convert the session-stats context test to a `contextPercent` field.
+- `test/ui/agent-widget.test.ts` — drop the `agentActivity` arg from `new AgentWidget(...)`; add a projection test asserting `renderWidget` reads activity off records.
+- `test/conversation-viewer.test.ts` — drop `activity` from `TestViewerOptions` / `createTestViewer`; seed the running-indicator test's `activeTools` / `responseText` via `createTestSubagent`; drop the `AgentActivityTracker` import.
+- `test/ui/agent-menu.test.ts` — drop the `agentActivity` arg from `new AgentsMenuHandler(...)`.
+- `test/tools/helpers.test.ts` — drop the `activity` arg from `buildDetails` calls; seed `turnCount` / `maxTurns` via `createTestSubagent`; drop the `AgentActivityTracker` import.
+- `test/tools/foreground-runner.test.ts` — adjust any `details.turnCount` assertions to the record's value (turn count `1` default matches the prior tracker default, so most cases are unchanged); the activity-map registration test stays (producer plumbing remains).
+- `test/observation/notification.test.ts` — drop `agentActivity` from `makeArgs` and `new NotificationManager(...)`; drop the `activity` arg from `buildNotificationDetails` calls and seed `turnCount` / `maxTurns` via `createTestSubagent`; remove the two map-cleanup assertions and the `cleanupCompleted` test.
+- `test/observation/subagent-events-observer.test.ts` — update any assertion that `cleanupCompleted` is called on `resultConsumed` to assert no nudge is sent instead.
+
+`test/runtime.test.ts` and `test/helpers/make-deps.ts` keep their `AgentActivityTracker` map usage — the runtime map and the `AgentTool` `agentActivity` access survive this step (removed in Steps 3 / 5).
+Completed historical plans under `docs/plans/` are point-in-time records and are not edited.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled.**
+   `agent-widget.test.ts` can now assert the projection directly — that `renderWidget` surfaces a record's `turnCount` / `activeTools` / `contextPercent` without any external map — because activity lives on the record the manager stub returns.
+   `widget-renderer.test.ts` tests get simpler: a single `makeAgent` carries everything, removing the two-object (`WidgetAgent` + `WidgetActivity`) arrangement.
+2. **Tests that become redundant / simplified.**
+   The `widget-renderer` "omits turn count when no activity provided" cases lose their premise (there is no activity-absent path); they convert to asserting the turn count renders.
+   The `notification` "sendCompletion cleans up activity" and "cleanupCompleted removes activity" cases lose their subject (the map is gone) and are removed.
+   `ui-observer.test.ts` and `agent-activity-tracker.test.ts` stay — they pin the producer behavior still wired until Step 3.
+3. **Tests that must stay as-is.**
+   `foreground-runner.test.ts`'s activity-map registration test (the tracker is still constructed and registered), and `runtime.test.ts`'s `agentActivity` map presence test, genuinely exercise the producer plumbing this step does not remove.
+
+## Invariants at risk
+
+- **Step 1 ([#420]) outcome — `Subagent` is the single home for run state; getters available for migration.**
+  This step is the consumer of that outcome; the getters' parity with the old tracker (turn count starts at `1`, `name_seq` active-tool keying, reset-then-append response text) is what makes the swap behavior-preserving for running agents.
+  Pinned by the existing `subagent-state.test.ts` / `record-observer.test.ts` cases from Step 1 plus the reader tests migrated here.
+- **`widget-renderer` purity — pure functions, plain data, no SDK types** (established when the renderer was split out, plan 0148).
+  The migration preserves and strengthens it: the `contextPercent` field removes the `getSessionContextPercent(session)` reach-through, so the renderer no longer touches session stats.
+  Pinned by `widget-renderer.test.ts` constructing plain `WidgetAgent` objects (no class instances).
+- **`NotificationManager` construction graph stays a cycle-free DAG with no widget dependency** (index.ts comment).
+  Dropping the `agentActivity` map narrows its deps further; no new dependency is added.
+
+No earlier phase step's documented `Outcome:` is regressed — the producer plumbing Step 1's tidy-first overlap left in place is untouched here.
+
+## TDD Order
+
+1. **Preparatory: seed activity on test records.**
+   Surface: `test/helpers/make-subagent.ts` (+ a focused assertion in `test/helpers/make-deps.test.ts` or `make-subagent` coverage if one exists).
+   Add `turnCount` / `activeTools` / `responseText` / `maxTurns` shorthands to `createTestSubagent` (drive `state.incrementTurnCount` / `addActiveTool` / `appendResponseText`; thread `maxTurns` into `makeStubExecution`).
+   Pure test-helper addition — no production change; makes the reader-migration steps easy ("make the change that makes the change easy").
+   Commit: `test: seed live-activity on createTestSubagent (#421)`.
+2. **Migrate the widget reader.**
+   Surface: `test/widget-renderer.test.ts`, `test/ui/agent-widget.test.ts`.
+   Red→green: update `makeAgent` to carry activity, drop the `activity` arg / `activityMap`, assert finished lines now render the turn count, assert the `AgentWidget` projection.
+   Implement the `WidgetAgent` fold + `contextPercent`, the render-signature changes, and the `AgentWidget.toWidgetAgent` projection; update the `new AgentWidget(...)` call in `index.ts` and the SKILL.md flow line.
+   This step lands the accepted behavior change (finished-agent turn count), so the commit is `feat:`, not `refactor:`.
+   Run `pnpm run check` after this commit — `renderWidgetLines` is the shared signature changed.
+   Commit: `feat: read widget activity off subagent records (#421)`.
+3. **Migrate the conversation viewer and `/agents` menu.**
+   Surface: `test/conversation-viewer.test.ts`, `test/ui/agent-menu.test.ts`.
+   Red→green: drop `activity` from the viewer factory and seed the running-indicator inputs on the record; drop the `agentActivity` arg from the menu handler construction.
+   Implement: drop `ConversationViewer.activity`; read off `this.record`; remove `AgentActivityReader` and the `viewAgentConversation` lookup; update the `new AgentsMenuHandler(...)` call in `index.ts`.
+   The viewer constructor signature and the menu constructor signature both change with their sole call sites in the same commit.
+   Commit: `refactor: read conversation-viewer activity off the record (#421)`.
+4. **Migrate `buildDetails` and the foreground runner.**
+   Surface: `test/tools/helpers.test.ts`, `test/tools/foreground-runner.test.ts`.
+   Red→green: drop the `activity` arg from `buildDetails` calls and seed `turnCount` / `maxTurns` on the record; confirm the foreground `details` still report the record's turn count.
+   Implement: `buildDetails` param/body change (both call sites — `runForeground` and the `AgentTool` resume path — compile in the same commit), and `runForeground`'s `streamUpdate` / final `buildDetails` reads.
+   Commit: `refactor: build agent details from the record, not the tracker (#421)`.
+5. **Migrate notifications and drop the activity map there.**
+   Surface: `test/observation/notification.test.ts`, `test/observation/subagent-events-observer.test.ts`.
+   Red→green: drop `agentActivity` from the notification fixtures and the `activity` arg from `buildNotificationDetails`; remove the map-cleanup and `cleanupCompleted` cases; assert the observer's `resultConsumed` branch sends no nudge.
+   Implement: `buildNotificationDetails` reads off the record; `NotificationManager` drops the map param/field and `cleanupCompleted`; `NotificationSystem` drops `cleanupCompleted`; `SubagentEventsObserver` returns in the `resultConsumed` branch; update the `new NotificationManager(...)` call in `index.ts`.
+   Run `pnpm run check` after this commit — `NotificationSystem` is a shared interface and `index.ts` is its construction site.
+   Commit: `refactor: build notification details from the record (#421)`.
+
+After Step 5, no reader reads activity off `AgentActivityTracker`; the tracker, `ui-observer`, and the runtime map remain only as inert producer plumbing for Step 3 ([#422]).
+
+## Risks and Mitigations
+
+- **Risk: the running-line idle text changes.**
+  Once `activeTools` / `responseText` always come off the record, an idle running agent renders via `describeActivity(new Map(), "")` instead of the old no-tracker `thinking…` fallback.
+  Mitigation: `describeActivity` already returns `thinking…` for an empty map and blank text, so the output is preserved; the migrated `widget-renderer` test pins it.
+- **Risk: transient background-tracker map leak between Steps 2 and 3.**
+  `NotificationManager` no longer deletes finished agents' trackers from the runtime map, and background agents are no longer cleaned up by anyone until the map is removed.
+  Mitigation: after this step the map is write-only and read by nobody, so the leak is inert and short-lived; Step 3 ([#422]) removes the map entirely.
+- **Risk: `streamUpdate` runs before `recordRef` is set (foreground).**
+  The initial `streamUpdate()` and the first spinner ticks fire before `onSessionCreated` assigns `recordRef`.
+  Mitigation: read with defaults that match the tracker's initial values (`turnCount ?? 1`, empty `activeTools`, `"" `responseText, `execution.effectiveMaxTurns` for `maxTurns`).
+- **Risk: removing `cleanupCompleted` changes the observer's consumed-result path.**
+  Mitigation: the method only deleted a map entry; the observer's intent (skip the nudge when the result was already consumed) is preserved by an early `return`, pinned by the updated observer test.
+
+## Open Questions
+
+- Whether the `NotificationSystem` interface should be narrowed further (e.g. to a two-method completion notifier) now that `cleanupCompleted` is gone is deferred — it is orthogonal to this step and best judged once Steps 3–5 settle the surrounding wiring.
+
+[#420]: https://github.com/gotgenes/pi-packages/issues/420
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424
+[#425]: https://github.com/gotgenes/pi-packages/issues/425

package/docs/retro/0420-fold-run-metrics-live-activity-onto-record.md

@@ -43,3 +43,48 @@ Full suite green; type check and lint clean; zero dead code.
 - WARN finding: `package-pi-subagents` SKILL.md `Observation` domain row description ("Session-event stats") is now slightly incomplete for `record-observer` (it also accumulates live-activity fields).
   Intentionally deferred per the planning-stage decision — no symbol removed, and the description will be updated in Step 2 ([#421]) when the observer's role is fully defined after the reader migration.
 - Pre-completion reviewer verdict: **WARN** (one non-blocking finding, deferred per retro).
+
+## Stage: Final Retrospective (2026-06-17T17:40:39Z)
+
+### Session summary
+
+Shipped Phase 18 Step 1 across planning, TDD (3 red→green→commit cycles, +27 tests), and release (`pi-subagents` v16.5.0).
+The code work was clean and rework-free; all friction was in markdown-lint surfacing late — two separate doc-lint failures (one pre-existing, one introduced) escaped the baseline and post-TDD gates and were caught only by the pre-completion reviewer and the ship-stage lint, each requiring a fix commit.
+
+### Observations
+
+#### What went well
+
+- The `pre-completion-reviewer` safety net earned its keep: it caught the pre-existing `MD051` broken-fragment links in `phase-17-core-consolidation.md` (introduced earlier by `e4d92535`, unrelated to this issue) before the push, returning FAIL on the first run.
+  Without it the broken links would have shipped.
+- TDD execution was textbook: each of the 3 steps followed red→green→commit with no rework to production code, the `maxTurns`-via-`execution` delegation decision from planning held, and the "vacuously-passing" observer tests (verified in the retro) correctly converted to real assertions once the observer was implemented.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (gate-caught, at ship) — wrote a second `[#421]:` link-reference definition into the retro file when appending the TDD stage entry via `Write` full-content, tripping `MD053` (duplicate definition).
+  The `markdown-conventions` skill states this rule verbatim ("Link reference definitions are file-scoped … a duplicate trips MD053").
+  Impact: one fix commit at ship time (`80d4d050`), caught by the root `pnpm run lint` pre-push gate rather than during TDD (no lint runs after stage-notes writing).
+- `missing-context` (self-identified during ship investigation) — the TDD green-baseline lint was run package-scoped (`pnpm --filter @gotgenes/pi-subagents run lint`), which **silently passes** on `MD051` cross-file fragment failures.
+  Verified empirically: package `lint:md` (`rumdl check *.md docs/**/*.md`) returns "No issues" on the broken fragment, while root `rumdl check .` exits 1 on it — the cross-file fragment target (`../architecture.md`) is only resolved on a repo-root tree walk.
+  Impact: the pre-existing `MD051` failure slipped past the baseline gate (whose job is to catch exactly that) and surfaced mid-TDD via the reviewer, costing a fix commit (`86ed0c81`) and a reviewer FAIL/re-dispatch cycle.
+
+#### What caused friction (user side)
+
+- None.
+  The session ran end-to-end without user correction; the operator-authored, roadmap-aligned issue meant no clarification was needed.
+
+### Diagnostic details
+
+- **Model-performance correlation** — two `pre-completion-reviewer` subagent dispatches ran on the agent's configured reviewer model and performed judgment-heavy review work (acceptance criteria, design review, cross-step invariants); appropriate match.
+  No high-cost model was spent on mechanical work and no reasoning-weak model on judgment work.
+- **Feedback-loop gap analysis** — the lint feedback loop fired at the wrong scope and the wrong time: package-scoped at baseline (missed `MD051`), and absent after retro stage-notes writing (missed `MD053` until ship).
+  `pnpm run check` and `pnpm run test` were run incrementally per step and caught everything they should; only the markdown-lint loop was misconfigured.
+- **Escalation-delay / unused-tool** — no `rabbit-hole` friction; no lens-2 or lens-3 findings.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — "Verify green baseline" step 2 and "After the last TDD step" step 3 now specify `pnpm run lint` runs **from the repo root**, with a one-clause rationale that package-scoped lint silently passes on `MD051` cross-file fragments and cross-package issues (Proposal 1).
+2. Proposal 2 (an `MD053` duplicate-link-definition reminder in the retro-writing prompts) was declined — the rule already exists verbatim in the `markdown-conventions` skill, so a prompt clause would duplicate it.
+3. Follow-up (post-retro): `#420` completed Phase 18 Step 1 but the roadmap Steps section was not marked done until the operator noticed.
+   Added a roadmap-step-status check so this is caught going forward: a WARN bullet in `pre-completion-reviewer.md` §2c (backstop), and a proactive step in `.pi/prompts/tdd-plan.md` step 7 and `.pi/prompts/build-plan.md` "After the last step" — mark the completed roadmap step done (`✅`/`Landed:`) and update the phase status row.
+   Also marked Step 1 complete in `architecture.md` (Steps list, dependency diagram node, phase table row → "In progress").

package/docs/retro/0421-migrate-activity-readers-to-record-getters.md

@@ -0,0 +1,56 @@
+---
+issue: 421
+issue_title: "pi-subagents: migrate activity-tracker readers to the record getters"
+---
+
+# Retro: #421 — Migrate activity-tracker readers to the record getters
+
+## Stage: Planning (2026-06-17T00:00:00Z)
+
+### Session summary
+
+Produced a 5-step TDD plan for Phase 18 Step 2 — migrating the five activity readers (`widget-renderer`, `conversation-viewer`, `agent-menu`, `foreground-runner`, `notification`) off `AgentActivityTracker` and onto the `Subagent` getters added in Step 1 ([#420]).
+The plan files at `packages/pi-subagents/docs/plans/0421-migrate-activity-readers-to-record-getters.md`.
+
+### Observations
+
+- **Two design forks surfaced and were resolved with the operator** via `ask_user`. (1) Finished agents currently show **no** turn count because the tracker is deleted on completion; reading off the record (which persists `turnCount`) makes finished lines show `⟳N`.
+  Operator accepted this as the more-correct behavior — so the widget step is `feat:`, not `refactor:`. (2) How `WidgetAgent` exposes context percent: chose a precomputed `contextPercent` **field** + a `Subagent` → `WidgetAgent` projection in `AgentWidget` (over a `getContextPercent()` method on the snapshot), honoring the renderer's pure-data contract and dropping its `getSessionContextPercent(session)` reach-through.
+  Operator's steer: "no sacred cows, especially in the UI — make the change that makes the change easy, then make the easy change."
+- **Scope boundary with Step 3 ([#422]).**
+  The producer plumbing (`foreground-runner` / `background-spawner` constructing trackers, `subscribeUIObserver`, the `runtime.agentActivity` map) stays — it is removed in Step 3.
+  But the reader-held map deps in `notification`, `agent-widget`, and `agent-menu` are removed **here**, because Step 3's target list does not include those files.
+  This means `cleanupCompleted` (which only deleted a map entry) becomes vestigial and is removed from `NotificationSystem`, rippling to `SubagentEventsObserver`.
+- **Transient map leak between Steps 2 and 3** is noted as an accepted risk: after this step the runtime map is write-only and read by nobody, so it is inert until Step 3 deletes it.
+- **Prep step (tidy-first):** Step 1 adds `turnCount` / `activeTools` / `responseText` / `maxTurns` shorthands to `createTestSubagent` so the reader-migration tests can seed activity on records.
+- **Living-doc updates identified:** `.pi/skills/package-pi-subagents/SKILL.md` line 56 (`widget ─polls─→ AgentActivityTracker map`) and the architecture roadmap's Phase 18 Step 2 `Landed:` line.
+  Completed historical plans under `docs/plans/` are point-in-time records and are not edited.
+- **Shared-signature commits** flagged for `pnpm run check`: the widget step (`renderWidgetLines`) and the notification step (`NotificationSystem` + `index.ts` construction).
+  Both `buildDetails` call sites and both viewer/menu constructor call sites must land in the same commit as their signature changes.
+
+[#420]: https://github.com/gotgenes/pi-packages/issues/420
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+
+## Stage: Implementation — TDD (2026-06-17T17:00:00Z)
+
+### Session summary
+
+All 5 TDD cycles completed in one session.
+The five activity readers (`widget-renderer`, `conversation-viewer`, `agent-menu`, `foreground-runner`, `notification`) were migrated off `AgentActivityTracker` and onto the `Subagent` record getters added in Phase 18 Step 1.
+Test count went from 1058 to 1066 (+8).
+
+### Observations
+
+- **Step 2 (widget)** introduced the `WidgetAgent` → activity-field fold and the `AgentWidget.toWidgetAgent` projection.
+  The accepted behavior change (finished agents now show `⟳N` from the persisted record) landed as `feat:` as planned.
+  `renderWidgetLines` drops `activityMap`; renderer is now a pure function of plain data with no SDK-type reach.
+- **Step 3 (viewer + menu)** was straightforward once `ConversationViewer` dropped `activity?: AgentActivityTracker`; the streaming indicator now reads `this.record.activeTools` / `this.record.responseText` directly.
+  `AgentActivityReader` interface removed; `AgentsMenuHandler` constructor lost one parameter.
+- **Step 4 (buildDetails + foreground runner)** required care around the pre-`onSessionCreated` phase: `streamUpdate` falls back to `recordRef?.turnCount ?? 1`, `execution.effectiveMaxTurns`, empty `Map()`, and `""` before the record reference is assigned.
+  The `AgentTool` resume call site (`buildDetails(base, record)`) was already correct and needed no change.
+- **Step 5 (notifications)** removed `NotificationSystem.cleanupCompleted` entirely (it only deleted a map entry).
+  `SubagentEventsObserver.onSubagentCompleted` now returns early on `resultConsumed` rather than calling the removed method.
+  The `NotificationManager` constructor drops the `agentActivity: Map` argument; `index.ts` needed one arg removed.
+- **Post-commit SKILL.md fix**: the pre-completion reviewer (WARN) flagged that `subagent-events-observer.ts` was missing from the Observation domain table; fixed in a follow-up `docs:` commit.
+- **Pre-completion reviewer**: WARN (non-blocking).
+  Reviewer warning: SKILL.md Observation domain table listed 4 modules and omitted `subagent-events-observer.ts`; corrected before writing these notes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.5.0",
+  "version": "16.6.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -62,7 +62,6 @@ export default function (pi: ExtensionAPI) {
   // widget dependency — keeping the construction graph a cycle-free DAG.
   const notifications = new NotificationManager(
     (msg, opts) => pi.sendMessage(msg, opts),
-    runtime.agentActivity,
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -130,7 +129,7 @@ export default function (pi: ExtensionAPI) {
 
   // Live widget: constructed after the manager (it polls listAgents()) and
   // injected directly into its consumers — no post-construction field write.
-  const widget = new AgentWidget(manager, runtime.agentActivity, registry);
+  const widget = new AgentWidget(manager, registry);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
   const toolStart = new ToolStartHandler(widget);
@@ -157,7 +156,6 @@ export default function (pi: ExtensionAPI) {
   const agentsMenu = new AgentsMenuHandler(
     manager,
     registry,
-    runtime.agentActivity,
     settings,
     new FsAgentFileOps(),
     join(getAgentDir(), "agents"),

package/src/observation/notification.ts

@@ -1,7 +1,6 @@
 import { debugLog } from "#src/debug";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { Subagent } from "#src/types";
-import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
 /** Details attached to custom notification messages for visual rendering. */
 export interface NotificationDetails {
@@ -77,7 +76,6 @@ export function formatTaskNotification(record: Subagent, resultMaxLen: number):
 export function buildNotificationDetails(
   record: Subagent,
   resultMaxLen: number,
-  activity?: AgentActivityTracker,
 ): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
@@ -86,8 +84,8 @@ export function buildNotificationDetails(
     description: record.description,
     status: record.status,
     toolUses: record.toolUses,
-    turnCount: activity?.turnCount ?? 0,
-    maxTurns: activity?.maxTurns,
+    turnCount: record.turnCount,
+    maxTurns: record.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
     outputFile: record.outputFile,
@@ -127,7 +125,6 @@ export function buildEventData(record: Subagent) {
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
   sendCompletion: (record: Subagent) => void;
-  cleanupCompleted: (id: string) => void;
   dispose: () => void;
 }
 
@@ -141,7 +138,6 @@ export class NotificationManager implements NotificationSystem {
       msg: { customType: string; content: string; display: boolean; details?: unknown },
       opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
     ) => void,
-    private agentActivity: Map<string, AgentActivityTracker>,
   ) {}
 
   cancelNudge(key: string): void {
@@ -153,14 +149,9 @@ export class NotificationManager implements NotificationSystem {
   }
 
   sendCompletion(record: Subagent): void {
-    this.agentActivity.delete(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
   }
 
-  cleanupCompleted(id: string): void {
-    this.agentActivity.delete(id);
-  }
-
   dispose(): void {
     for (const timer of this.pendingNudges.values()) clearTimeout(timer);
     this.pendingNudges.clear();
@@ -193,7 +184,7 @@ export class NotificationManager implements NotificationSystem {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, this.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );

package/src/observation/subagent-events-observer.ts

@@ -65,10 +65,7 @@ export class SubagentEventsObserver implements SubagentManagerObserver {
 		});
 
 		// Skip notification if result was already consumed via get_subagent_result.
-		if (record.notification?.resultConsumed) {
-			this.notifications.cleanupCompleted(record.id);
-			return;
-		}
+		if (record.notification?.resultConsumed) return;
 
 		this.notifications.sendCompletion(record);
 	}

package/src/tools/foreground-runner.ts

@@ -70,11 +70,15 @@ export async function runForeground(
       ...presentation.detailBase,
       toolUses,
       tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
-      turnCount: fgState.turnCount,
-      maxTurns: fgState.maxTurns,
+      // Read activity off the record; fall back to safe defaults before onSessionCreated fires
+      turnCount: recordRef?.turnCount ?? 1,
+      maxTurns: recordRef?.maxTurns ?? execution.effectiveMaxTurns,
       durationMs: Date.now() - startedAt,
       status: "running",
-      activity: describeActivity(fgState.activeTools, fgState.responseText),
+      activity: describeActivity(
+        recordRef?.activeTools ?? new Map(),
+        recordRef?.responseText ?? "",
+      ),
       spinnerFrame: spinnerFrame % SPINNER.length,
     };
     onUpdate?.({
@@ -136,7 +140,7 @@ export async function runForeground(
   }
 
   const tokenText = formatLifetimeTokens(record);
-  const details = buildDetails(presentation.detailBase, record, fgState, { tokens: tokenText });
+  const details = buildDetails(presentation.detailBase, record, { tokens: tokenText });
 
   const fallbackNote = identity.fellBack
     ? `Note: Unknown agent type "${identity.rawType}" — using general-purpose.\n\n`

package/src/tools/helpers.ts

@@ -1,6 +1,5 @@
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import { getLifetimeTotal, type LifetimeUsage } from "#src/lifecycle/usage";
-import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { type AgentDetails, formatTokens } from "#src/ui/display";
 
 /** Parenthetical status note for completed agent result text. */
@@ -28,16 +27,18 @@ export function buildDetails(
     error?: string;
     id?: string;
     lifetimeUsage: LifetimeUsage;
+    /** Live-activity counters — exposed as getters on Subagent (Phase 18 Step 2). */
+    turnCount?: number;
+    maxTurns?: number;
   },
-  activity?: AgentActivityTracker,
   overrides?: Partial<AgentDetails>,
 ): AgentDetails {
   return {
     ...base,
     toolUses: record.toolUses,
     tokens: formatLifetimeTokens(record),
-    turnCount: activity?.turnCount,
-    maxTurns: activity?.maxTurns,
+    turnCount: record.turnCount,
+    maxTurns: record.maxTurns,
     durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
     status: record.status as AgentDetails["status"],
     agentId: record.id,

package/src/ui/agent-menu.ts

@@ -5,7 +5,6 @@ import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { type ModelRegistry, resolveModel } from "#src/session/model-resolver";
 import { getModelLabelFromConfig } from "#src/tools/helpers";
 import type { AgentConfig, Subagent } from "#src/types";
-import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { AgentConfigEditor } from "#src/ui/agent-config-editor";
 import { AgentCreationWizard } from "#src/ui/agent-creation-wizard";
 import type { AgentFileOps } from "#src/ui/agent-file-ops";
@@ -36,14 +35,6 @@ export interface AgentMenuSettings {
   applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
 }
 
-/**
- * Read-only interface for the agent-menu's agentActivity access.
- * Only the conversation viewer needs to read a tracker by agent ID.
- */
-export interface AgentActivityReader {
-  get(id: string): AgentActivityTracker | undefined;
-}
-
 // ---- Narrow UI context types ----
 
 /** Narrow UI interface — only the ctx.ui methods menu handlers actually call. */
@@ -70,7 +61,6 @@ export class AgentsMenuHandler {
   constructor(
     private readonly manager: AgentMenuManager,
     private readonly registry: AgentTypeRegistry,
-    private readonly agentActivity: AgentActivityReader,
     private readonly settings: AgentMenuSettings,
     fileOps: AgentFileOps,
     personalAgentsDir: string,
@@ -263,14 +253,12 @@ export class AgentsMenuHandler {
     const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import(
       "./conversation-viewer"
     );
-    const activity = this.agentActivity.get(record.id);
 
     await ui.custom<undefined>(
       (tui: any, theme: any, _keybindings: any, done: any) => {
         return new ConversationViewer({
           tui,
           record,
-          activity,
           theme,
           done,
           registry: this.registry,

package/src/ui/agent-widget.ts

@@ -7,10 +7,10 @@
  */
 
 import { AgentTypeRegistry } from "#src/config/agent-types";
+import type { Subagent } from "#src/lifecycle/subagent";
 import type { SubagentManager } from "#src/lifecycle/subagent-manager";
-import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { ERROR_STATUSES, type Theme } from "#src/ui/display";
-import { renderWidgetLines } from "#src/ui/widget-renderer";
+import { renderWidgetLines, type WidgetAgent } from "#src/ui/widget-renderer";
 
 // ---- Types ----
 
@@ -79,7 +79,6 @@ export class AgentWidget {
 
   constructor(
     private manager: SubagentManager,
-    private agentActivity: Map<string, AgentActivityTracker>,
     private registry: AgentTypeRegistry,
   ) {}
 
@@ -129,11 +128,31 @@ export class AgentWidget {
     }
   }
 
+  /** Project a live Subagent record onto a pure-data WidgetAgent snapshot. */
+  private toWidgetAgent(record: Subagent): WidgetAgent {
+    return {
+      id: record.id,
+      type: record.type,
+      status: record.status,
+      description: record.description,
+      toolUses: record.toolUses,
+      startedAt: record.startedAt,
+      completedAt: record.completedAt,
+      error: record.error,
+      lifetimeUsage: record.lifetimeUsage,
+      compactionCount: record.compactionCount,
+      turnCount: record.turnCount,
+      maxTurns: record.maxTurns,
+      activeTools: record.activeTools,
+      responseText: record.responseText,
+      contextPercent: record.getContextPercent(),
+    };
+  }
+
   /** Delegate rendering to the pure widget-renderer module. */
   private renderWidget(tui: any, theme: Theme): string[] {
     return renderWidgetLines({
-      agents: this.manager.listAgents(),
-      activityMap: this.agentActivity,
+      agents: this.manager.listAgents().map(r => this.toWidgetAgent(r)),
       registry: this.registry,
       spinnerFrame: this.widgetFrame,
       terminalWidth: tui.terminal.columns,

package/src/ui/conversation-viewer.ts

@@ -9,7 +9,6 @@ import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth } f
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { Subagent } from "#src/types";
-import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { buildInvocationTags, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "#src/ui/display";
 import { formatMessage, formatStreamingIndicator } from "#src/ui/message-formatters";
 
@@ -24,7 +23,6 @@ export const VIEWPORT_HEIGHT_PCT = 70;
 export interface ConversationViewerOptions {
   tui: TUI;
   record: Subagent;
-  activity: AgentActivityTracker | undefined;
   theme: Theme;
   done: (result: undefined) => void;
   registry: AgentConfigLookup;
@@ -40,7 +38,6 @@ export class ConversationViewer implements Component {
 
   private tui: TUI;
   private record: Subagent;
-  private activity: AgentActivityTracker | undefined;
   private theme: Theme;
   private done: (result: undefined) => void;
   private registry: AgentConfigLookup;
@@ -49,7 +46,6 @@ export class ConversationViewer implements Component {
   constructor({
     tui,
     record,
-    activity,
     theme,
     done,
     registry,
@@ -57,7 +53,6 @@ export class ConversationViewer implements Component {
   }: ConversationViewerOptions) {
     this.tui = tui;
     this.record = record;
-    this.activity = activity;
     this.theme = theme;
     this.done = done;
     this.registry = registry;
@@ -231,11 +226,11 @@ export class ConversationViewer implements Component {
       needsSeparator = true;
     }
 
-    // Streaming indicator for running agents
-    if (this.record.status === "running" && this.activity) {
+    // Streaming indicator for running agents — read activity off the record
+    if (this.record.status === "running") {
       lines.push(...formatStreamingIndicator(
-        this.activity.activeTools,
-        this.activity.responseText,
+        this.record.activeTools,
+        this.record.responseText,
         width,
         th,
       ));

package/src/ui/widget-renderer.ts

@@ -7,8 +7,8 @@
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import type { LifetimeUsage, SessionLike } from "#src/lifecycle/usage";
-import { getLifetimeTotal, getSessionContextPercent } from "#src/lifecycle/usage";
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { SubagentType } from "#src/types";
 import {
 	describeActivity,
@@ -35,15 +35,13 @@ export interface WidgetAgent {
 	readonly error?: string;
 	readonly lifetimeUsage?: Readonly<LifetimeUsage>;
 	readonly compactionCount: number;
-}
-
-/** Read-only activity snapshot for widget rendering. */
-export interface WidgetActivity {
-	readonly activeTools: ReadonlyMap<string, string>;
-	readonly responseText: string;
+	// Live activity (folded from the former WidgetActivity — precomputed by AgentWidget)
 	readonly turnCount: number;
 	readonly maxTurns?: number;
-	readonly session?: SessionLike;
+	readonly activeTools: ReadonlyMap<string, string>;
+	readonly responseText: string;
+	/** Context-window utilisation (0–100), or null when unavailable. */
+	readonly contextPercent: number | null;
 }
 
 // ── Per-agent rendering ──────────────────────────────────────────────────────
@@ -51,7 +49,6 @@ export interface WidgetActivity {
 /** Render a single finished agent line (no tree connector prefix). */
 export function renderFinishedLine(
 	agent: WidgetAgent,
-	activity: WidgetActivity | undefined,
 	registry: AgentConfigLookup,
 	theme: Theme,
 ): string {
@@ -81,7 +78,7 @@ export function renderFinishedLine(
 	}
 
 	const parts: string[] = [];
-	if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
+	parts.push(formatTurns(agent.turnCount, agent.maxTurns));
 	if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool use${agent.toolUses === 1 ? "" : "s"}`);
 	parts.push(duration);
 
@@ -92,7 +89,6 @@ export function renderFinishedLine(
 /** Render a single running agent as header + activity line pair (no tree connector prefix). */
 export function renderRunningLines(
 	agent: WidgetAgent,
-	activity: WidgetActivity | undefined,
 	registry: AgentConfigLookup,
 	spinnerFrame: number,
 	theme: Theme,
@@ -103,18 +99,17 @@ export function renderRunningLines(
 	const elapsed = formatMs(Date.now() - agent.startedAt);
 
 	const tokens = getLifetimeTotal(agent.lifetimeUsage);
-	const contextPercent = activity?.session ? getSessionContextPercent(activity.session) : null;
-	const tokenText = tokens > 0 ? formatSessionTokens(tokens, contextPercent, theme, agent.compactionCount) : "";
+	const tokenText = tokens > 0 ? formatSessionTokens(tokens, agent.contextPercent, theme, agent.compactionCount) : "";
 
 	const parts: string[] = [];
-	if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
+	parts.push(formatTurns(agent.turnCount, agent.maxTurns));
 	if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool use${agent.toolUses === 1 ? "" : "s"}`);
 	if (tokenText) parts.push(tokenText);
 	parts.push(elapsed);
 	const statsText = parts.join(" · ");
 
 	const frame = SPINNER[spinnerFrame % SPINNER.length];
-	const activityText = activity ? describeActivity(activity.activeTools, activity.responseText) : "thinking\u2026";
+	const activityText = describeActivity(agent.activeTools, agent.responseText);
 
 	const header = `${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", agent.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`;
 	const activityLine = theme.fg("dim", `  \u23BF  ${activityText}`);
@@ -157,7 +152,6 @@ interface WidgetSections {
 /** Render each agent bucket into pre-formatted lines with ├─ tree connectors. */
 function buildSections(
 	categories: AgentCategories,
-	activityMap: ReadonlyMap<string, WidgetActivity>,
 	registry: AgentConfigLookup,
 	spinnerFrame: number,
 	theme: Theme,
@@ -165,12 +159,12 @@ function buildSections(
 ): WidgetSections {
 	const finishedLines: string[] = [];
 	for (const a of categories.finished) {
-		finishedLines.push(truncate(theme.fg("dim", "\u251C\u2500") + " " + renderFinishedLine(a, activityMap.get(a.id), registry, theme)));
+		finishedLines.push(truncate(theme.fg("dim", "\u251C\u2500") + " " + renderFinishedLine(a, registry, theme)));
 	}
 
 	const runningLines: [string, string][] = [];
 	for (const a of categories.running) {
-		const [header, act] = renderRunningLines(a, activityMap.get(a.id), registry, spinnerFrame, theme);
+		const [header, act] = renderRunningLines(a, registry, spinnerFrame, theme);
 		runningLines.push([
 			truncate(theme.fg("dim", "\u251C\u2500") + ` ${header}`),
 			truncate(theme.fg("dim", "\u2502  ") + act),
@@ -259,14 +253,13 @@ function assembleOverflow(
 /** 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;
 	theme: Theme;
 	shouldShowFinished: (agentId: string, status: string) => boolean;
 }): string[] {
-	const { agents, activityMap, registry, spinnerFrame, terminalWidth, theme, shouldShowFinished } = params;
+	const { agents, registry, spinnerFrame, terminalWidth, theme, shouldShowFinished } = params;
 
 	const { running, queued, finished } = categorizeAgents(agents, shouldShowFinished);
 
@@ -281,7 +274,6 @@ export function renderWidgetLines(params: {
 
 	const { finishedLines, runningLines, queuedLine } = buildSections(
 		{ running, queued, finished },
-		activityMap,
 		registry,
 		spinnerFrame,
 		theme,