@gotgenes/pi-subagents 6.6.0 → 6.7.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.6.0...pi-subagents-v6.7.0) (2026-05-21)
+
+
+### Features
+
+* add AgentActivityTracker class ([#110](https://github.com/gotgenes/pi-packages/issues/110)) ([151308a](https://github.com/gotgenes/pi-packages/commit/151308ad3da569d72e40495bece502281dc302a8))
+
+
+### Documentation
+
+* plan AgentActivityTracker class ([#110](https://github.com/gotgenes/pi-packages/issues/110)) ([8f5e56b](https://github.com/gotgenes/pi-packages/commit/8f5e56ba0a29730e060bac4658bb4953ce36d4a9))
+* **retro:** add retro notes for issue [#118](https://github.com/gotgenes/pi-packages/issues/118) ([1959e52](https://github.com/gotgenes/pi-packages/commit/1959e52d8b150bbc90da72edd93dc6f2ec315e22))
+* update architecture doc — mark A3 done, fix Map type ([#110](https://github.com/gotgenes/pi-packages/issues/110)) ([463e997](https://github.com/gotgenes/pi-packages/commit/463e9974db21df17f4b2578825f3c67bc1e90b29))
+
 ## [6.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.5.0...pi-subagents-v6.6.0) (2026-05-21)
 
 

package/docs/architecture/architecture.md

@@ -82,7 +82,7 @@ Record statistics (tool uses, token usage, compaction counts) are updated by `re
 UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
 Neither observer wraps or forwards the other — both subscribe directly to the session.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivity>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes directly to `AgentSession` objects.
+The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes directly to `AgentSession` objects.
 
 Cross-extension consumers use the typed `SubagentsService` API published via `Symbol.for("@gotgenes/pi-subagents:service")` on `globalThis`.
 
@@ -381,7 +381,7 @@ Each step is sequenced so it makes the next step easier.
 | -------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ~~Global mutable state~~   | ~~`agent-types.ts`~~                     | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                 |
 | Closure bag as class       | `createNotificationSystem()`             | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                       |
-| Mutable state bag          | `AgentActivity` (7 fields)               | Written by `ui-observer.ts`, read by widget, notification, agent-tool                                                                                                     |
+| ~~Mutable state bag~~      | ~~`AgentActivity` (7 fields)~~           | **Fixed #110**: `AgentActivityTracker` class; `ui-observer.ts` calls transition methods; widget, notification, agent-tool use read-only accessors                         |
 | ~~Settings relay~~         | ~~`AgentMenuDeps` (13 fields)~~          | **Fixed #109**: `SettingsManager` class; 6 callback fields collapsed to `settings: SettingsManager`; `AgentMenuDeps` now 8 fields                                         |
 | Post-construction mutation | `AgentRecord` non-transition state       | `session`, `outputFile`, `worktree`, `promise` written by external code after construction                                                                                |
 | Fire-and-forget callbacks  | `AgentManagerOptions`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
@@ -422,11 +422,12 @@ Each owns the full consequence chain: normalize → set in memory → notify cal
 
 Impact: eliminates LoD / Tell-Don't-Ask violation in `showSettings`; menu no longer coordinates between settings and manager.
 
-#### A3. `AgentActivityTracker` class (#110)
+#### ~~A3. `AgentActivityTracker` class (#110)~~ — **Done**
 
-Wrap the 7-field mutable `AgentActivity` interface with transition methods (`onToolStart()`, `onToolEnd()`, `onMessageUpdate()`, `onTurnEnd()`).
-`ui-observer.ts` calls tracker methods instead of writing raw fields.
-The notification system, widget, and agent-tool receive a proper collaborator instead of reaching into a shared `Map<string, AgentActivity>`.
+Wrapped the 7-field mutable `AgentActivity` interface in an `AgentActivityTracker` class (`src/ui/agent-activity-tracker.ts`).
+`ui-observer.ts` calls transition methods (`onToolStart`, `onToolEnd`, `onMessageStart`, `onMessageUpdate`, `onTurnEnd`, `onUsageUpdate`, `setSession`).
+The notification system, widget, conversation viewer, and agent-tool use read-only accessors.
+The shared map on `SubagentRuntime` is now `Map<string, AgentActivityTracker>`.
 
 Impact: eliminates output-argument writes in `ui-observer.ts`, makes the mutation contract explicit.
 
@@ -489,7 +490,7 @@ The 654-line file splits along a natural seam.
 | ------------------------------------------ | ---------------------------------------------------------------------------- | ------- |
 | Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                 | **0** ✓ |
 | Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**) | 0       |
-| Externally-mutated state bags              | 2 (`AgentActivity`, `AgentRecord` non-transition fields)                     | 0       |
+| Externally-mutated state bags              | ~~2~~ 1 (`AgentRecord` non-transition fields; `AgentActivity` **fixed #110**)| 0       |
 | `AgentManagerOptions` fields               | 8                                                                            | 5       |
 | `AgentToolDeps` fields                     | ~~9~~ **7** (−6 registry #108, −1 settings #109 → +1 settings obj)           | ~5      |
 | `AgentMenuDeps` fields                     | ~~13~~ **8** (−6 settings #109 collapsed to 1; −1 registry #108)             | ~6 ✓    |

package/docs/plans/0110-agent-activity-tracker.md

@@ -0,0 +1,297 @@
+---
+issue: 110
+issue_title: "refactor(pi-subagents): wrap AgentActivity in AgentActivityTracker class"
+---
+
+# Wrap AgentActivity in AgentActivityTracker class
+
+## Problem Statement
+
+`AgentActivity` is a 7-field mutable interface (`activeTools`, `toolUses`, `responseText`, `session`, `turnCount`, `maxTurns`, `lifetimeUsage`) shared across 4 modules.
+`ui-observer.ts` writes raw fields on it (output arguments), the widget and conversation viewer read them, and the agent-tool creates empty instances and stuffs them into a shared `Map`.
+The mutation contract is implicit — callers know which fields to set by convention, not by API.
+
+This is Phase 7, Step A3 in the architecture doc.
+
+## Goals
+
+- Wrap `AgentActivity` in an `AgentActivityTracker` class with explicit transition methods.
+- Replace the output-argument writes in `ui-observer.ts` with tracker method calls.
+- Expose read-only accessors for the state the widget, notification system, conversation viewer, and agent-tool need.
+- Change the shared `Map<string, AgentActivity>` on `SubagentRuntime` to `Map<string, AgentActivityTracker>`.
+- Preserve all existing behavior — this is a pure encapsulation refactor.
+
+## Non-Goals
+
+- Splitting `AgentRecord` lifecycle state (#111) — deferred to Step B.
+- Replacing `AgentManager` callbacks with an observer (#112) — deferred to Step C.
+- Narrowing `AgentToolDeps` or `AgentMenuDeps` further (#114) — deferred to Step D2.
+- Changing `createNotificationSystem` from closure to class (#116) — deferred to Step E2.
+
+## Background
+
+### Who writes AgentActivity today
+
+`ui-observer.ts` (`subscribeUIObserver`) is the sole writer.
+It subscribes to session events and mutates the state object directly:
+
+- `state.activeTools.set(...)` / `state.activeTools.delete(...)` on tool start/end
+- `state.toolUses++` on tool end
+- `state.responseText = ""` on message start, `state.responseText += delta` on message update
+- `state.turnCount++` on turn end
+- `addUsage(state.lifetimeUsage, ...)` on message end with assistant usage
+
+The agent-tool also writes `session` after session creation (`fgState.session = session`, `bgState.session = session`).
+
+### Who reads AgentActivity today
+
+| Consumer                                       | Fields read                                                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `agent-widget.ts` (widget render)              | `activeTools`, `responseText`, `toolUses`, `turnCount`, `maxTurns`, `lifetimeUsage`, `session` |
+| `conversation-viewer.ts`                       | `toolUses`, `lifetimeUsage`, `session`, `activeTools`, `responseText`                          |
+| `notification.ts` (`buildNotificationDetails`) | `turnCount`, `maxTurns`                                                                        |
+| `agent-tool.ts` (foreground streaming)         | `toolUses`, `turnCount`, `maxTurns`, `activeTools`, `responseText`, `lifetimeUsage`            |
+| `agent-menu.ts` (conversation viewer launch)   | passes to `ConversationViewer`                                                                 |
+
+### Who creates AgentActivity today
+
+`createAgentActivity()` in `agent-tool.ts` — a factory function that returns a plain object with defaults.
+
+### AGENTS.md constraints
+
+- One concern per file: the tracker gets its own module.
+- Avoid `any`: use typed accessors.
+- Output arguments: this refactor eliminates them from `ui-observer.ts`.
+- Keep modules focused: the tracker owns its mutable state; consumers use read-only accessors.
+
+## Design Overview
+
+### AgentActivityTracker class
+
+New file: `src/ui/agent-activity-tracker.ts`.
+
+The class owns the 7 mutable fields and exposes:
+
+1. Transition methods (the write surface — called by `ui-observer.ts` and agent-tool):
+
+   ```typescript
+   onToolStart(toolName: string): void    // adds to activeTools map
+   onToolEnd(toolName: string): void      // removes from activeTools, increments toolUses
+   onMessageStart(): void                  // resets responseText
+   onMessageUpdate(delta: string): void    // appends to responseText
+   onTurnEnd(): void                       // increments turnCount
+   onUsageUpdate(usage: UsageDelta): void  // accumulates into lifetimeUsage
+   setSession(session: SessionLike): void  // one-time session binding
+   ```
+
+2. Read-only accessors (the read surface — used by widget, notification, conversation viewer, agent-tool streaming):
+
+   ```typescript
+   get activeTools(): ReadonlyMap<string, string>
+   get toolUses(): number
+   get responseText(): string
+   get session(): SessionLike | undefined
+   get turnCount(): number
+   get maxTurns(): number | undefined
+   get lifetimeUsage(): Readonly<LifetimeUsage>
+   ```
+
+The constructor accepts `maxTurns?: number` (set at creation time, immutable).
+
+### UsageDelta type
+
+A narrow type for the usage values passed to `onUsageUpdate`:
+
+```typescript
+interface UsageDelta { input: number; output: number; cacheWrite: number }
+```
+
+This matches the shape `addUsage` already expects and avoids coupling to the full `LifetimeUsage` type name for what is logically a delta.
+
+### activeTools key strategy
+
+The current `activeTools` Map uses `toolName + "_" + Date.now()` as a key to allow multiple concurrent tools with the same name.
+`onToolStart` returns `void` and generates the key internally (same `Date.now()` strategy).
+`onToolEnd(toolName)` finds and removes the first matching entry (same logic as today).
+
+### subscribeUIObserver changes
+
+`subscribeUIObserver` changes its second parameter from `state: AgentActivity` to `tracker: AgentActivityTracker`.
+Instead of writing fields, it calls tracker methods:
+
+```typescript
+// Before:
+state.activeTools.set(event.toolName + "_" + Date.now(), event.toolName);
+// After:
+tracker.onToolStart(event.toolName);
+```
+
+### Consumer interface
+
+Readers continue to access the same properties but through getters.
+Since the tracker exposes matching property names, consumer code like `bg.turnCount` and `bg.toolUses` remains syntactically identical — only the type annotation changes from `AgentActivity` to `AgentActivityTracker`.
+
+The `AgentActivity` interface is removed entirely.
+All references migrate to `AgentActivityTracker`.
+
+### Map type change
+
+`SubagentRuntime.agentActivity` changes from `Map<string, AgentActivity>` to `Map<string, AgentActivityTracker>`.
+All dependency bags that pass this map (`AgentToolDeps`, `AgentMenuDeps`, `NotificationDeps`, `AgentWidget` constructor) update their type annotations.
+
+### createAgentActivity replacement
+
+The factory function in `agent-tool.ts` is replaced by `new AgentActivityTracker(maxTurns)`.
+
+## Module-Level Changes
+
+### New file
+
+| File                               | What                                                                         |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| `src/ui/agent-activity-tracker.ts` | `AgentActivityTracker` class with transition methods and read-only accessors |
+
+### New test file
+
+| File                                     | What                                                          |
+| ---------------------------------------- | ------------------------------------------------------------- |
+| `test/ui/agent-activity-tracker.test.ts` | Unit tests for all transition methods and read-only accessors |
+
+### Modified files
+
+| File                            | What changes                                                                                                                                                                                                   |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/ui-observer.ts`         | Accept `AgentActivityTracker` instead of `AgentActivity`; call transition methods instead of writing fields                                                                                                    |
+| `src/ui/agent-widget.ts`        | Remove `AgentActivity` interface; import `AgentActivityTracker`; update `Map` type and read sites (property names stay the same)                                                                               |
+| `src/ui/conversation-viewer.ts` | Import `AgentActivityTracker` instead of `AgentActivity`; update parameter type                                                                                                                                |
+| `src/ui/agent-menu.ts`          | Import `AgentActivityTracker` instead of `AgentActivity`; update `Map` type                                                                                                                                    |
+| `src/tools/agent-tool.ts`       | Import `AgentActivityTracker`; replace `createAgentActivity()` with `new AgentActivityTracker()`; replace `fgState.session = session` with `fgState.setSession(session)`; update `Map` type in `AgentToolDeps` |
+| `src/notification.ts`           | Import `AgentActivityTracker` instead of `AgentActivity`; update `buildNotificationDetails` parameter and `NotificationDeps.agentActivity` Map type                                                            |
+| `src/runtime.ts`                | Import `AgentActivityTracker`; change `agentActivity` Map type; update `AgentWidget` import (type only change since `AgentActivity` moves)                                                                     |
+| `src/index.ts`                  | No changes (already references `runtime.agentActivity` by reference, the type flows through)                                                                                                                   |
+
+### Modified test files
+
+| File                            | What changes                                                                                                                                               |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `test/ui/ui-observer.test.ts`   | Replace `makeActivity()` factory with `new AgentActivityTracker()`; access state through getters; assertions on accessor values instead of raw field reads |
+| `test/notification.test.ts`     | Replace `as AgentActivity` casts with `new AgentActivityTracker()`; set up tracker state via transition methods                                            |
+| `test/tools/agent-tool.test.ts` | Update `Map<string, AgentActivity>` type to `Map<string, AgentActivityTracker>`                                                                            |
+
+### Removed exports
+
+| Symbol                             | Was in                    | Replaced by                                                        |
+| ---------------------------------- | ------------------------- | ------------------------------------------------------------------ |
+| `AgentActivity` (interface)        | `src/ui/agent-widget.ts`  | `AgentActivityTracker` class in `src/ui/agent-activity-tracker.ts` |
+| `createAgentActivity()` (function) | `src/tools/agent-tool.ts` | `new AgentActivityTracker(maxTurns)`                               |
+
+Grep verification: `AgentActivity` is referenced in 7 source files and 3 test files (listed above) — all accounted for in the modified files list.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+The `AgentActivityTracker` class enables focused unit tests for each transition method in isolation:
+
+- `onToolStart` / `onToolEnd` — concurrent tool tracking, correct toolUses increment
+- `onMessageStart` / `onMessageUpdate` — response text lifecycle
+- `onTurnEnd` — turn counting from initial value
+- `onUsageUpdate` — accumulation semantics
+- `setSession` — one-time binding
+- Read-only accessors — verify consumers cannot mutate internal state
+
+These were previously impossible to test without going through `subscribeUIObserver` and a mock session.
+
+### Existing tests that simplify
+
+`test/ui/ui-observer.test.ts` — currently constructs a plain `AgentActivity` object and asserts on raw field mutations.
+After the change, it constructs an `AgentActivityTracker` and the assertions read the same properties through accessors.
+The `makeActivity()` helper is replaced by `new AgentActivityTracker()`.
+The test logic stays the same (event → tracker state check) but the assertions use getter-backed properties.
+
+### Existing tests that stay as-is
+
+`test/notification.test.ts` — the pure helper tests (`escapeXml`, `getStatusLabel`, `formatTaskNotification`, `buildNotificationDetails`) only need their `AgentActivity` type references updated to `AgentActivityTracker`.
+The notification system integration tests that cast `{} as AgentActivity` need minimal updates to construct a real tracker instead.
+
+`test/tools/agent-tool.test.ts` — only the `Map` type annotation changes.
+
+## TDD Order
+
+### 1. Red/green: AgentActivityTracker class — transition methods and read-only accessors
+
+Test file: `test/ui/agent-activity-tracker.test.ts`
+
+Tests:
+
+- Constructor sets initial state (`turnCount: 1`, empty `activeTools`, `toolUses: 0`, empty `responseText`, zero `lifetimeUsage`, `maxTurns` from constructor arg, `session` undefined)
+- `onToolStart` adds entry to `activeTools`
+- `onToolEnd` removes entry and increments `toolUses`
+- `onToolEnd` with no matching tool is a no-op (defensive)
+- Multiple concurrent tools with same name tracked independently
+- `onMessageStart` resets `responseText` to empty
+- `onMessageUpdate` appends delta to `responseText`
+- `onTurnEnd` increments `turnCount`
+- `onUsageUpdate` accumulates into `lifetimeUsage`
+- `setSession` stores the session reference
+- Read-only: `activeTools` returns `ReadonlyMap`
+- Read-only: `lifetimeUsage` returns `Readonly<LifetimeUsage>`
+
+Commit: `feat: add AgentActivityTracker class (#110)`
+
+### 2. Red/green: migrate ui-observer to use AgentActivityTracker
+
+Update `src/ui/ui-observer.ts` to accept `AgentActivityTracker` and call transition methods.
+Update `test/ui/ui-observer.test.ts`: replace `makeActivity()` with `new AgentActivityTracker()`, read state through accessors.
+
+All existing test scenarios must pass unchanged (same events → same observable state).
+
+Commit: `refactor: migrate ui-observer to AgentActivityTracker (#110)`
+
+### 3. Migrate agent-widget and conversation-viewer
+
+Update `src/ui/agent-widget.ts`: remove `AgentActivity` interface, import `AgentActivityTracker`, update `Map` type and constructor parameter.
+Update `src/ui/conversation-viewer.ts`: import `AgentActivityTracker`, update parameter type.
+
+No test changes needed — widget and conversation viewer are not unit-tested (they render UI).
+
+Commit: `refactor: migrate widget and conversation-viewer to AgentActivityTracker (#110)`
+
+### 4. Migrate agent-tool
+
+Update `src/tools/agent-tool.ts`: import `AgentActivityTracker`, replace `createAgentActivity()` with `new AgentActivityTracker()`, replace `fgState.session = session` with `fgState.setSession(session)`, update `AgentToolDeps` Map type.
+Update `test/tools/agent-tool.test.ts`: update Map type.
+
+Commit: `refactor: migrate agent-tool to AgentActivityTracker (#110)`
+
+### 5. Migrate notification and agent-menu
+
+Update `src/notification.ts`: import `AgentActivityTracker`, update `buildNotificationDetails` parameter and `NotificationDeps` Map type.
+Update `src/ui/agent-menu.ts`: import `AgentActivityTracker`, update Map type in `AgentMenuDeps`.
+Update `test/notification.test.ts`: replace `as AgentActivity` casts with real `AgentActivityTracker` instances.
+
+Commit: `refactor: migrate notification and agent-menu to AgentActivityTracker (#110)`
+
+### 6. Migrate runtime and clean up
+
+Update `src/runtime.ts`: import `AgentActivityTracker`, change `agentActivity` Map type.
+Remove any remaining `AgentActivity` references.
+Run `pnpm run check` to verify no type errors remain.
+
+Commit: `refactor: complete AgentActivityTracker migration, remove AgentActivity interface (#110)`
+
+## Risks and Mitigations
+
+| Risk                                                                              | Mitigation                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read-only getters change identity semantics for `activeTools` and `lifetimeUsage` | The `ReadonlyMap` and `Readonly<LifetimeUsage>` types restrict writes at compile time. Consumers already only read these values, so no runtime change. Return the internal mutable reference cast to readonly (no copy overhead). |
+| Spreading a class instance loses methods                                          | Grep for `{ ...activity` or `{ ...bg` patterns — none found in current code. The `buildDetails` function spreads `detailBase` (a plain object), not the activity.                                                                 |
+| `onToolEnd` matching logic fragility                                              | Port the exact same `for...of` + `break` pattern from `ui-observer.ts`. New unit tests cover this independently.                                                                                                                  |
+| `turnCount` initial value of 1 (not 0)                                            | The current `createAgentActivity` sets `turnCount: 1`. The tracker constructor preserves this. A dedicated test asserts the initial value.                                                                                        |
+| Test files casting `{} as AgentActivity`                                          | Replace with real `AgentActivityTracker` instances. Where tests only need `turnCount` and `maxTurns` (e.g., `buildNotificationDetails`), construct a tracker and call `onTurnEnd` to set up the desired state.                    |
+
+## Open Questions
+
+- None — the issue and architecture doc are prescriptive about the approach.
+  The only design latitude is whether `onToolStart` returns a key (for symmetric `onToolEnd(key)`) or whether `onToolEnd(toolName)` does a lookup.
+  The plan uses `onToolEnd(toolName)` with lookup to match the existing pattern and avoid threading a key through the session event handler.

package/docs/retro/0118-settings-manager-apply-methods.md

@@ -0,0 +1,40 @@
+---
+issue: 118
+issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
+---
+
+# Retro: #118 — SettingsManager apply methods
+
+## Final Retrospective (2026-05-21T21:00:00Z)
+
+### Session summary
+
+Planned and implemented 3 `apply*` methods on `SettingsManager` (`applyMaxConcurrent`, `applyDefaultMaxTurns`, `applyGraceTurns`) across 5 TDD cycles plus doc updates, released as `pi-subagents-v6.6.0`.
+Each method owns the full consequence chain (normalize → set → callback → persist → emit → return toast), eliminating the LoD/Tell-Don't-Ask violation in `showSettings` that was identified during the #109 retro.
+`notifyConcurrencyChanged` was removed from `AgentMenuManager`; the menu no longer coordinates between settings and the agent manager.
+
+### Observations
+
+#### What went well
+
+- **Retro-driven improvement validated.**
+  Issue #118 was filed during the #109 retro as a LoD/Tell-Don't-Ask follow-up, and the plan-issue prompt's consumer call-site sketch heuristic (added in #109's retro) was already in the plan template.
+  The plan for #118 included concrete before/after call-site sketches that made the design unambiguous — no `ask-user` decision needed.
+- **Interface-then-wiring TDD order worked cleanly.**
+  The #109 retro noted that interface changes propagate to `index.ts` immediately, forcing unplanned bridge edits.
+  This time the plan accounted for it: Cycle 4 committed only menu files (leaving a known `index.ts` type error), and Cycle 5 fixed the wiring in a separate commit.
+  The intermediate type error was contained and expected.
+- **`defaultMaxTurns` branch consolidation.**
+  During Cycle 4, the separate `n === 0` and `n >= 1` branches in `showSettings` were consolidated to a single `n >= 0` check, since `applyDefaultMaxTurns` handles the 0→unlimited mapping internally.
+  This was a minor but correct simplification that emerged naturally from the Tell-Don't-Ask refactor.
+
+#### What caused friction (agent side)
+
+- No material friction.
+  All 5 TDD cycles completed without rework, failed edits, or unexpected test failures.
+  The plan was tight and the issue's "Proposed change" section was unambiguous.
+
+#### What caused friction (user side)
+
+- No material friction observed.
+  The session ran end-to-end (plan → implement → ship → release) without user intervention.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.6.0",
+  "version": "6.7.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/notification.ts

@@ -1,6 +1,6 @@
 import { debugLog } from "./debug.js";
 import type { AgentRecord, NotificationDetails } from "./types.js";
-import type { AgentActivity } from "./ui/agent-widget.js";
+import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 
 // ---- Pure helpers (exported for unit testing) ----
@@ -60,7 +60,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
 export function buildNotificationDetails(
   record: AgentRecord,
   resultMaxLen: number,
-  activity?: AgentActivity,
+  activity?: AgentActivityTracker,
 ): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
@@ -113,7 +113,7 @@ export interface NotificationDeps {
     msg: { customType: string; content: string; display: boolean; details?: unknown },
     opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
   ) => void;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   markFinished: (id: string) => void;
   updateWidget: () => void;
 }

package/src/runtime.ts

@@ -6,7 +6,8 @@
  * Follows the same pattern as pi-permission-system's ExtensionRuntime.
  */
 
-import type { AgentActivity, AgentWidget, UICtx } from "./ui/agent-widget.js";
+import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
+import type { AgentWidget, UICtx } from "./ui/agent-widget.js";
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -31,7 +32,7 @@ export class SubagentRuntime {
    * Per-agent live activity state shared across the notification system,
    * widget, and tool handlers. The Map itself is never replaced.
    */
-  readonly agentActivity: Map<string, AgentActivity> = new Map();
+  readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
   /**
    * Persistent widget reference. Null until constructed after AgentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.

package/src/tools/agent-tool.ts

@@ -8,8 +8,8 @@ import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
+import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
-  type AgentActivity,
   type AgentDetails,
   buildInvocationTags,
   describeActivity,
@@ -26,19 +26,6 @@ import { formatLifetimeTokens, textResult } from "./helpers.js";
 
 // ---- Agent-tool-specific helpers ----
 
-/** Create a fresh AgentActivity state for tracking UI progress. */
-function createAgentActivity(maxTurns?: number): AgentActivity {
-  return {
-    activeTools: new Map(),
-    toolUses: 0,
-    turnCount: 1,
-    maxTurns,
-    responseText: "",
-    session: undefined,
-    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
-  };
-}
-
 /** Parenthetical status note for completed agent result text. */
 export function getStatusNote(status: string): string {
   switch (status) {
@@ -66,7 +53,7 @@ export function buildDetails(
     session?: any;
     lifetimeUsage: LifetimeUsage;
   },
-  activity?: AgentActivity,
+  activity?: AgentActivityTracker,
   overrides?: Partial<AgentDetails>,
 ): AgentDetails {
   return {
@@ -106,7 +93,7 @@ export interface AgentToolWidget {
 export interface AgentToolDeps {
   manager: AgentToolManager;
   widget: AgentToolWidget;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   emitEvent: (name: string, data: unknown) => void;
   registry: AgentTypeRegistry;
   typeListText: string;
@@ -415,7 +402,7 @@ Guidelines:
 
       // Background execution
       if (runInBackground) {
-        const bgState = createAgentActivity(effectiveMaxTurns);
+        const bgState = new AgentActivityTracker(effectiveMaxTurns);
 
         let id: string;
 
@@ -433,7 +420,7 @@ Guidelines:
             isolation,
             invocation: agentInvocation,
             onSessionCreated: (session: any) => {
-              bgState.session = session;
+              bgState.setSession(session);
               subscribeUIObserver(session, bgState);
             },
           });
@@ -487,7 +474,7 @@ Guidelines:
       const startedAt = Date.now();
       let fgId: string | undefined;
 
-      const fgState = createAgentActivity(effectiveMaxTurns);
+      const fgState = new AgentActivityTracker(effectiveMaxTurns);
       let unsubUI: (() => void) | undefined;
 
       const streamUpdate = () => {
@@ -535,7 +522,7 @@ Guidelines:
             parentSessionFile: ctx.sessionManager.getSessionFile(),
             parentSessionId: ctx.sessionManager.getSessionId(),
             onSessionCreated: (session: any) => {
-              fgState.session = session;
+              fgState.setSession(session);
               unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
               for (const a of deps.manager.listAgents()) {
                 if (a.session === session) {

package/src/ui/agent-activity-tracker.ts

@@ -0,0 +1,108 @@
+/**
+ * agent-activity-tracker.ts — Per-agent live activity state with explicit transition methods.
+ *
+ * Replaces the mutable `AgentActivity` interface that was written via output arguments
+ * in `ui-observer.ts`. Callers use named transition methods; readers use read-only accessors.
+ */
+
+import { addUsage, type LifetimeUsage, type SessionLike } from "../usage.js";
+
+/** Usage delta accepted by onUsageUpdate — matches the LifetimeUsage accumulator shape. */
+export interface UsageDelta {
+	input: number;
+	output: number;
+	cacheWrite: number;
+}
+
+/** Per-agent live activity state with explicit transition methods and read-only accessors. */
+export class AgentActivityTracker {
+	private _activeTools = new Map<string, string>();
+	private _toolKeySeq = 0;
+	private _toolUses = 0;
+	private _responseText = "";
+	private _session: SessionLike | undefined = undefined;
+	private _turnCount = 1;
+	private _lifetimeUsage: LifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
+
+	constructor(private readonly _maxTurns?: number) {}
+
+	// ── Transition methods (write surface) ──────────────────────────────────
+
+	/** Record that a tool has started executing. */
+	onToolStart(toolName: string): void {
+		this._activeTools.set(toolName + "_" + (++this._toolKeySeq), toolName);
+	}
+
+	/** Record that a tool has finished executing; increments toolUses. No-op when no matching tool is active. */
+	onToolEnd(toolName: string): void {
+		for (const [key, name] of this._activeTools) {
+			if (name === toolName) {
+				this._activeTools.delete(key);
+				this._toolUses++;
+				break;
+			}
+		}
+	}
+
+	/** Reset the current response text (called at the start of each assistant message). */
+	onMessageStart(): void {
+		this._responseText = "";
+	}
+
+	/** Append a text delta to the current response text. */
+	onMessageUpdate(delta: string): void {
+		this._responseText += delta;
+	}
+
+	/** Record that a turn has ended; increments turnCount. */
+	onTurnEnd(): void {
+		this._turnCount++;
+	}
+
+	/** Accumulate a usage delta into the lifetime usage totals. */
+	onUsageUpdate(delta: UsageDelta): void {
+		addUsage(this._lifetimeUsage, delta);
+	}
+
+	/** Bind the session reference (called once when the agent session is created). */
+	setSession(session: SessionLike): void {
+		this._session = session;
+	}
+
+	// ── Read-only accessors ──────────────────────────────────────────────────
+
+	/** Currently-active tools: key → tool name. Multiple entries for concurrent same-name tools. */
+	get activeTools(): ReadonlyMap<string, string> {
+		return this._activeTools;
+	}
+
+	/** Total completed tool invocations. */
+	get toolUses(): number {
+		return this._toolUses;
+	}
+
+	/** The agent's latest partial response text (reset at each message start). */
+	get responseText(): string {
+		return this._responseText;
+	}
+
+	/** The active SDK session, or undefined before the first session is created. */
+	get session(): SessionLike | undefined {
+		return this._session;
+	}
+
+	/** Current turn count (starts at 1). */
+	get turnCount(): number {
+		return this._turnCount;
+	}
+
+	/** Effective max turns for this agent, or undefined for unlimited. */
+	get maxTurns(): number | undefined {
+		return this._maxTurns;
+	}
+
+	/** Accumulated lifetime token usage (survives compaction). */
+	get lifetimeUsage(): Readonly<LifetimeUsage> {
+		return this._lifetimeUsage;
+	}
+}

package/src/ui/agent-menu.ts

@@ -9,7 +9,7 @@ import {
 } from "../agent-types.js";
 import type { ModelRegistry } from "../model-resolver.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
-import type { AgentActivity } from "./agent-widget.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 import { formatDuration, getDisplayName } from "./agent-widget.js";
 
 // ---- Deps interface ----
@@ -35,7 +35,7 @@ export interface AgentMenuSettings {
 export interface AgentMenuDeps {
   manager: AgentMenuManager;
   registry: AgentTypeRegistry;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   /** Resolve model label for a given agent type + registry. */
   getModelLabel: (type: string, registry?: ModelRegistry) => string;
   /** Settings manager — owns in-memory values and persistence. */

package/src/ui/agent-widget.ts

@@ -9,7 +9,8 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
 import { type AgentConfigLookup, AgentTypeRegistry } from "../agent-types.js";
 import type { AgentInvocation, SubagentType } from "../types.js";
-import { getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
+import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 
 // ---- Constants ----
 
@@ -49,20 +50,6 @@ export type UICtx = {
   ): void;
 };
 
-/** Per-agent live activity state. */
-export interface AgentActivity {
-  activeTools: Map<string, string>;
-  toolUses: number;
-  responseText: string;
-  session?: SessionLike;
-  /** Current turn count. */
-  turnCount: number;
-  /** Effective max turns for this agent (undefined = unlimited). */
-  maxTurns?: number;
-  /** Lifetime usage breakdown — see LifetimeUsage docs. */
-  lifetimeUsage: LifetimeUsage;
-}
-
 /** Metadata attached to Agent tool results for custom rendering. */
 export interface AgentDetails {
   displayName: string;
@@ -177,7 +164,7 @@ function truncateLine(text: string, len = 60): string {
 }
 
 /** Build a human-readable activity string from currently-running tools or response text. */
-export function describeActivity(activeTools: Map<string, string>, responseText?: string): string {
+export function describeActivity(activeTools: ReadonlyMap<string, string>, responseText?: string): string {
   if (activeTools.size > 0) {
     const groups = new Map<string, number>();
     for (const toolName of activeTools.values()) {
@@ -224,7 +211,7 @@ export class AgentWidget {
 
   constructor(
     private manager: AgentManager,
-    private agentActivity: Map<string, AgentActivity>,
+    private agentActivity: Map<string, AgentActivityTracker>,
     private registry: AgentTypeRegistry,
   ) {}
 

package/src/ui/conversation-viewer.ts

@@ -11,8 +11,8 @@ import type { AgentConfigLookup } from "../agent-types.js";
 import { extractText } from "../context.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
-import type { Theme } from "./agent-widget.js";
-import { type AgentActivity, buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
+import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./agent-widget.js";
 
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
@@ -31,7 +31,7 @@ export class ConversationViewer implements Component {
     private tui: TUI,
     private session: AgentSession,
     private record: AgentRecord,
-    private activity: AgentActivity | undefined,
+    private activity: AgentActivityTracker | undefined,
     private theme: Theme,
     private done: (result: undefined) => void,
     private registry: AgentConfigLookup,

package/src/ui/ui-observer.ts

@@ -1,13 +1,12 @@
 /**
- * ui-observer.ts — Subscribes to session events and updates AgentActivity state.
+ * ui-observer.ts — Subscribes to session events and updates AgentActivityTracker state.
  *
  * Replaces the callback-based createActivityTracker pattern with a direct
  * session subscription for streaming UI state (active tools, response text,
  * turn count, lifetime usage).
  */
 
-import { addUsage } from "../usage.js";
-import type { AgentActivity } from "./agent-widget.js";
+import type { AgentActivityTracker } from "./agent-activity-tracker.js";
 
 /** Narrow session interface — only the subscribe method needed by the observer. */
 interface SubscribableSession {
@@ -15,15 +14,15 @@ interface SubscribableSession {
 }
 
 /**
- * Subscribe to session events and stream UI state into an AgentActivity object.
+ * Subscribe to session events and stream UI state into an AgentActivityTracker.
  *
  * Handles:
- * - `tool_execution_start` → add to `state.activeTools`
- * - `tool_execution_end` → remove from `state.activeTools`, `state.toolUses++`
- * - `message_start` → reset `state.responseText`
- * - `message_update` (text_delta) → append to `state.responseText`
- * - `turn_end` → `state.turnCount++`
- * - `message_end` (assistant, with usage) → `addUsage(state.lifetimeUsage, …)`
+ * - `tool_execution_start` → `tracker.onToolStart(name)`
+ * - `tool_execution_end` → `tracker.onToolEnd(name)`
+ * - `message_start` → `tracker.onMessageStart()`
+ * - `message_update` (text_delta) → `tracker.onMessageUpdate(delta)`
+ * - `turn_end` → `tracker.onTurnEnd()`
+ * - `message_end` (assistant, with usage) → `tracker.onUsageUpdate(usage)`
  *
  * Calls `onUpdate?.()` after each state mutation to trigger re-renders.
  *
@@ -31,47 +30,41 @@ interface SubscribableSession {
  */
 export function subscribeUIObserver(
 	session: SubscribableSession,
-	state: AgentActivity,
+	tracker: AgentActivityTracker,
 	onUpdate?: () => void,
 ): () => void {
 	return session.subscribe((event: any) => {
 		if (event.type === "tool_execution_start") {
-			state.activeTools.set(event.toolName + "_" + Date.now(), event.toolName);
+			tracker.onToolStart(event.toolName);
 			onUpdate?.();
 		}
 
 		if (event.type === "tool_execution_end") {
-			for (const [key, name] of state.activeTools) {
-				if (name === event.toolName) {
-					state.activeTools.delete(key);
-					break;
-				}
-			}
-			state.toolUses++;
+			tracker.onToolEnd(event.toolName);
 			onUpdate?.();
 		}
 
 		if (event.type === "message_start") {
-			state.responseText = "";
+			tracker.onMessageStart();
 		}
 
 		if (
 			event.type === "message_update" &&
 			event.assistantMessageEvent?.type === "text_delta"
 		) {
-			state.responseText += event.assistantMessageEvent.delta;
+			tracker.onMessageUpdate(event.assistantMessageEvent.delta);
 			onUpdate?.();
 		}
 
 		if (event.type === "turn_end") {
-			state.turnCount++;
+			tracker.onTurnEnd();
 			onUpdate?.();
 		}
 
 		if (event.type === "message_end" && event.message?.role === "assistant") {
 			const u = event.message.usage;
 			if (u) {
-				addUsage(state.lifetimeUsage, {
+				tracker.onUsageUpdate({
 					input: u.input ?? 0,
 					output: u.output ?? 0,
 					cacheWrite: u.cacheWrite ?? 0,