@gotgenes/pi-subagents 6.8.0 → 6.8.2

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.8.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.1...pi-subagents-v6.8.2) (2026-05-22)
+
+
+### Documentation
+
+* mark Step C complete in architecture.md ([#112](https://github.com/gotgenes/pi-packages/issues/112)) ([9f6e783](https://github.com/gotgenes/pi-packages/commit/9f6e783ab4ddcabdc24224e02aa631b93b0fb6d4))
+* plan replace AgentManager callbacks with observer interface ([#112](https://github.com/gotgenes/pi-packages/issues/112)) ([b32dde1](https://github.com/gotgenes/pi-packages/commit/b32dde1e473611b2734a287e88c8d155642405a7))
+* **retro:** add retro notes for issue [#123](https://github.com/gotgenes/pi-packages/issues/123) ([e9333ee](https://github.com/gotgenes/pi-packages/commit/e9333ee2af70e821ba1bace63bdbd7befa72ce84))
+
+## [6.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.0...pi-subagents-v6.8.1) (2026-05-21)
+
+
+### Documentation
+
+* plan remove vi.fn() cast smell from test helpers ([#123](https://github.com/gotgenes/pi-packages/issues/123)) ([d0e33b3](https://github.com/gotgenes/pi-packages/commit/d0e33b39cf419bb03a2d69c39992600752ce8517))
+* **retro:** add retro notes for issue [#111](https://github.com/gotgenes/pi-packages/issues/111) ([37eea32](https://github.com/gotgenes/pi-packages/commit/37eea32b32135b792c6c94933267c3e5a5f2cd7b))
+
 ## [6.8.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.7.0...pi-subagents-v6.8.0) (2026-05-21)
 
 

package/docs/architecture/architecture.md

@@ -384,7 +384,7 @@ Each step is sequenced so it makes the next step easier.
 | ~~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~~   | **Fixed #111**: `ExecutionState`, `WorktreeState`, `NotificationState` collaborators; `pendingSteers` moved to `AgentManager`; stats encapsulated behind mutation methods |
-| Fire-and-forget callbacks      | `AgentManagerOptions`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
+| ~~Fire-and-forget callbacks~~  | ~~`AgentManagerOptions`~~                | **Fixed #112**: `AgentManagerObserver` interface; `observer` replaces 3 callbacks; `index.ts` constructs one observer object instead of 3 closure lambdas                 |
 | Duplicate `SpawnOptions`       | `service.ts` + `agent-manager.ts`        | Two incompatible shapes (JSON-friendly vs runtime types) with the same name                                                                                               |
 | Type dumping ground            | `types.ts`                               | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each |
 | Wide dependency bags           | `AgentToolDeps` (7), `AgentMenuDeps` (8) | Settings narrowed (#109); registry narrowed (#108); more narrowing planned in D steps                                                                                     |
@@ -445,12 +445,12 @@ Split post-construction mutation into phase-specific collaborators, each born co
 Each piece is born complete at the moment its information is available.
 The record doesn't accumulate half-baked state — it receives fully constructed collaborators.
 
-### Step C: Replace `AgentManager` callbacks with observer (#112)
+### Step C: Replace `AgentManager` callbacks with observer (#112) ✅
 
-Replace the `onStart`/`onComplete`/`onCompact` callback parameters with an `AgentManagerObserver` interface (or typed event emitter).
-The observer methods receive the same data the callbacks receive today.
-`index.ts` constructs the observer once instead of building 3 closure callbacks that capture `runtime`, `pi`, `notifications`, etc.
-`AgentManagerOptions` drops from 8 → 5 fields.
+**Done.**
+`AgentManagerObserver` interface replaces `onStart`/`onComplete`/`onCompact`.
+`index.ts` constructs one observer object instead of 3 closure lambdas.
+`AgentManagerOptions` drops from 9 → 7 fields.
 
 ### Step D: Disambiguate `SpawnOptions` and narrow dependency bags
 

package/docs/plans/0112-replace-agent-manager-callbacks.md

@@ -0,0 +1,241 @@
+---
+issue: 112
+issue_title: "refactor(pi-subagents): replace AgentManager callbacks with observer interface"
+---
+
+# Replace AgentManager callbacks with observer interface
+
+## Problem Statement
+
+`AgentManagerOptions` accepts three fire-and-forget callbacks — `onStart`, `onComplete`, `onCompact` — that `index.ts` wires as closure lambdas capturing `runtime`, `pi`, `notifications`, and other extension state.
+This is the same callback-threading pattern that was replaced with direct session subscriptions in #100, but one level up.
+The callbacks are notification-style (fire-and-forget, no return value) and match the observer pattern exactly.
+
+## Goals
+
+- Replace the three callback parameters on `AgentManagerOptions` with a single `observer?: AgentManagerObserver` interface.
+- `index.ts` constructs one observer object instead of three independent closure lambdas.
+- `AgentManagerOptions` shrinks by two net fields (remove 3 callbacks, add 1 observer).
+- Preserve all existing behavior: lifecycle events, record persistence, notification dispatch, compaction events.
+- Non-breaking refactor — no public API changes (the callbacks are internal to the package).
+
+## Non-Goals
+
+- Extracting the observer implementation from `index.ts` into its own module — that can follow if the object grows.
+- Changing `RecordObserverOptions` (session-level observer) — it remains a separate concern at a different layer.
+- Narrowing `AgentToolDeps` or `AgentMenuDeps` — tracked in #114.
+- Disambiguating `SpawnOptions` — tracked in #113.
+
+## Background
+
+### Current callback wiring
+
+`agent-manager.ts` defines three callback type aliases and stores them as private fields:
+
+```typescript
+export type OnAgentStart = (record: AgentRecord) => void;
+export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+```
+
+`AgentManager` invokes them at three points:
+
+1. `onStart` — called in `startAgent()` after `record.markRunning()`.
+2. `onComplete` — called in `startAgent()`'s `.then()` and `.catch()` handlers for background agents, and in `drainQueue()` on late failure.
+3. `onCompact` — relayed through `subscribeRecordObserver()` → `RecordObserverOptions.onCompact`.
+
+`index.ts` builds ~30 lines of closure lambdas (lines 73–116) that capture `pi`, `notifications`, and `buildEventData`.
+
+### Observer pattern already established
+
+`record-observer.ts` and `ui/ui-observer.ts` are session-level observers that subscribe directly to session events.
+This refactoring applies the same principle at the manager level — grouping related notification callbacks into a single interface.
+
+### Dependency: issue #111 (AgentRecord lifecycle split)
+
+Issue #111 is closed.
+The observer interface is designed against the current record shape, which reflects the post-#111 lifecycle split.
+
+### Architecture reference
+
+Phase 7, Step C in `docs/architecture/architecture.md`.
+
+## Design Overview
+
+### Observer interface
+
+```typescript
+export interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+}
+```
+
+All three methods are fire-and-forget (void return, no async).
+The interface uses past-tense naming (`Started`, `Completed`, `Compacted`) to signal that these are after-the-fact notifications, not hooks that influence the operation.
+
+### `AgentManagerOptions` change
+
+```typescript
+export interface AgentManagerOptions {
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  exec: ShellExec;
+  registry: AgentTypeRegistry;
+  getMaxConcurrent?: () => number;
+  getRunConfig?: () => RunConfig;
+  observer?: AgentManagerObserver;  // replaces onStart, onComplete, onCompact
+}
+```
+
+Fields go from 9 → 7 (remove 3 callbacks, add 1 observer).
+
+### AgentManager internal changes
+
+The three private fields (`onStart`, `onComplete`, `onCompact`) become one: `private observer?: AgentManagerObserver`.
+Call sites change from `this.onStart?.(record)` to `this.observer?.onAgentStarted(record)`.
+
+The `onCompact` relay into `subscribeRecordObserver` changes from:
+
+```typescript
+onCompact: (r, info) => this.onCompact?.(r, info),
+```
+
+to:
+
+```typescript
+onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+```
+
+### `CompactionInfo` stays in `agent-manager.ts`
+
+`CompactionInfo` is a data shape consumed by the observer interface and already defined in `agent-manager.ts`.
+It stays co-located since both `AgentManagerObserver` and `CompactionInfo` are exported from the same module.
+`record-observer.ts` continues to import `CompactionInfo` from `agent-manager.ts`.
+
+### Observer construction in `index.ts`
+
+The three closure lambdas collapse into one object literal:
+
+```typescript
+const observer: AgentManagerObserver = {
+  onAgentStarted(record) {
+    pi.events.emit("subagents:started", {
+      id: record.id, type: record.type, description: record.description,
+    });
+  },
+  onAgentCompleted(record) {
+    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+    const eventData = buildEventData(record);
+    if (isError) pi.events.emit("subagents:failed", eventData);
+    else pi.events.emit("subagents:completed", eventData);
+
+    pi.appendEntry("subagents:record", { /* same fields as today */ });
+
+    if (record.notification?.resultConsumed) {
+      notifications.cleanupCompleted(record.id);
+      return;
+    }
+    notifications.sendCompletion(record);
+  },
+  onAgentCompacted(record, info) {
+    pi.events.emit("subagents:compacted", {
+      id: record.id, type: record.type, description: record.description,
+      reason: info.reason, tokensBefore: info.tokensBefore,
+      compactionCount: record.compactionCount,
+    });
+  },
+};
+```
+
+Passed as `observer` to `new AgentManager({ ..., observer })`.
+
+### Removed exports
+
+The three callback type aliases are removed:
+
+- `OnAgentStart`
+- `OnAgentComplete`
+- `OnAgentCompact`
+
+These are only imported in `agent-manager.test.ts` — no production consumers outside `agent-manager.ts`.
+
+## Module-Level Changes
+
+### `src/agent-manager.ts`
+
+- Add `AgentManagerObserver` interface (3 methods).
+- Remove `OnAgentStart`, `OnAgentComplete`, `OnAgentCompact` type aliases.
+- Replace `onStart`, `onComplete`, `onCompact` fields in `AgentManagerOptions` with `observer?: AgentManagerObserver`.
+- Replace three private fields with `private observer?: AgentManagerObserver`.
+- Update constructor to assign `this.observer = options.observer`.
+- Update all call sites: `this.onStart?.(record)` → `this.observer?.onAgentStarted(record)`, etc.
+- The `onCompact` relay to `subscribeRecordObserver` uses `this.observer?.onAgentCompacted`.
+
+### `src/index.ts`
+
+- Replace the three closure-lambda properties (`onComplete:`, `onStart:`, `onCompact:`) with a single `observer` object literal.
+- Import `AgentManagerObserver` from `agent-manager.ts`.
+- Remove any now-unused callback type imports.
+
+### `src/record-observer.ts`
+
+- No changes.
+  `RecordObserverOptions.onCompact` stays as-is — it is the session-level relay, not the manager-level observer.
+  `CompactionInfo` import from `agent-manager.ts` stays unchanged.
+
+### `test/agent-manager.test.ts`
+
+- Update imports: remove `OnAgentStart`, `OnAgentComplete`, `OnAgentCompact`; add `AgentManagerObserver`.
+- Update `createManager` helper: replace the three callback overrides with `observer?: Partial<AgentManagerObserver>`.
+  The factory spreads a no-op default observer with test-provided overrides.
+- Update each test that wires a callback to construct an observer object instead.
+
+## Test Impact Analysis
+
+1. No new unit tests are enabled by this refactoring — it's a 1:1 shape change.
+2. No existing tests become redundant — each test exercises a specific lifecycle scenario (race condition, foreground vs background, error handling, queue drain).
+3. All existing `agent-manager.test.ts` tests stay, with mechanical updates to the observer wiring.
+   The assertions remain the same (e.g., "observer.onAgentCompleted fires with `resultConsumed=false` when `markConsumed` called after await").
+
+## TDD Order
+
+### Step 1: Introduce `AgentManagerObserver` interface alongside existing callbacks
+
+Add the interface to `agent-manager.ts`.
+No production behavior changes — the interface is unused at this point.
+
+- Commit: `refactor: add AgentManagerObserver interface`
+
+### Step 2: Switch `AgentManager` internals to observer
+
+1. Replace the three `onStart`/`onComplete`/`onCompact` fields on `AgentManagerOptions` with `observer?: AgentManagerObserver`.
+2. Replace the three private fields with one `private observer?: AgentManagerObserver`.
+3. Update all internal call sites (`this.onStart?.(record)` → `this.observer?.onAgentStarted(record)`, etc.).
+4. Remove the three callback type aliases (`OnAgentStart`, `OnAgentComplete`, `OnAgentCompact`).
+5. Update `test/agent-manager.test.ts`: change imports, update `createManager` helper and all test call sites to construct observer objects instead of individual callbacks.
+6. Run `pnpm run check` to verify types.
+
+- Commit: `refactor: replace AgentManager callbacks with observer interface (#112)`
+
+### Step 3: Update `index.ts` to construct observer
+
+1. Replace the three closure-lambda properties in the `new AgentManager({...})` call with a single `observer` object.
+2. Import `AgentManagerObserver` type.
+3. Remove unused callback type imports.
+4. Run full test suite.
+
+- Commit: `refactor: construct AgentManagerObserver in index.ts (#112)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                | Mitigation                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tests break silently because esbuild ignores excess properties — old `onComplete` fields pass through without error | Step 2 removes the type aliases, so TypeScript catches any test still using the old shape via `pnpm run check`                                                              |
+| `onComplete` error-swallowing behavior changes                                                                      | The `try/catch` around `this.onComplete?.(record)` in the `.then()` path moves exactly to `this.observer?.onAgentCompleted(record)` — same guard, same catch, same debugLog |
+| `Partial<AgentManagerObserver>` in test factory silently drops required methods                                     | Tests that need a specific method construct it explicitly; the factory only provides a convenient default for tests that don't care about any observer method               |
+
+## Open Questions
+
+- None — the issue's proposed design is unambiguous and aligns with the established session-observer pattern.

package/docs/plans/0123-remove-vi-fn-cast-smell.md

@@ -0,0 +1,179 @@
+---
+issue: 123
+issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
+---
+
+# Remove vi.fn() cast smell from test helpers
+
+## Problem Statement
+
+Several test files construct mock objects typed to narrow interfaces (`AgentManagerLike`, `LifecycleRuntime`, `LifecycleManager`, `ToolStartRuntime`).
+Because the returned objects are typed to the interface — not to Vitest's mock types — tests that need to configure individual method stubs are forced to cast:
+
+```typescript
+(deps.manager.abort as ReturnType<typeof vi.fn>).mockReturnValue(false);
+(deps.manager.getRecord as ReturnType<typeof vi.fn>).mockReturnValue(record);
+```
+
+This silences TypeScript without constraining the call's return type — if `getRecord`'s return type changes, the cast won't catch it.
+Nine occurrences exist across three test files.
+
+## Goals
+
+- Eliminate all `as ReturnType<typeof vi.fn>` casts from the test suite.
+- Preserve type safety: mock configuration calls should be checked against the real method signatures.
+- Keep the change minimal — this is a test hygiene fix, not a structural redesign.
+
+## Non-Goals
+
+- Changing `AgentManagerLike`, `LifecycleRuntime`, `LifecycleManager`, `ToolStartRuntime`, or any production code.
+- Restructuring test layout or merging describe blocks.
+
+## Background
+
+The cast pattern was noted during #111 implementation and preserved to keep scope tight.
+Issue #111 (split `AgentRecord` lifecycle state) is now closed and implemented.
+
+### Affected files
+
+| File                               | Occurrences | Interface                              |
+| ---------------------------------- | ----------- | -------------------------------------- |
+| `test/service-adapter.test.ts`     | 5           | `AgentManagerLike`                     |
+| `test/handlers/lifecycle.test.ts`  | 2           | `LifecycleRuntime`, `LifecycleManager` |
+| `test/handlers/tool-start.test.ts` | 2           | `ToolStartRuntime`                     |
+
+### Cast sites by file
+
+`service-adapter.test.ts` — the "steer, abort, waitForAll, hasRunning" block's `createDeps` returns `AdapterDeps` directly.
+Five casts reconfigure `getRecord`, `abort`, or `queueSteer` after construction:
+
+1. `(deps.manager.abort as ReturnType<typeof vi.fn>).mockReturnValue(false)`
+2. `(deps.manager.getRecord as ReturnType<typeof vi.fn>).mockReturnValue({...})` (×4)
+
+`lifecycle.test.ts` — mock objects are assigned to `let` variables in `beforeEach`, typed to `LifecycleRuntime` and `LifecycleManager`.
+Two casts reconfigure methods to track call order:
+
+1. `(runtime.setSessionContext as ReturnType<typeof vi.fn>).mockImplementation(...)`
+2. `(manager.clearCompleted as ReturnType<typeof vi.fn>).mockImplementation(...)`
+
+Note: the same file already uses `vi.mocked()` in the shutdown-order test — both patterns coexist, which is itself a consistency smell.
+
+`tool-start.test.ts` — mock object assigned to a `let` variable typed to `ToolStartRuntime`.
+Two casts reconfigure methods to track call order:
+
+1. `(runtime.setUICtx as ReturnType<typeof vi.fn>).mockImplementation(...)`
+2. `(runtime.onTurnStart as ReturnType<typeof vi.fn>).mockImplementation(...)`
+
+### Approach: named-variable extraction
+
+Extract individual `vi.fn()` stubs into named variables.
+This is the approach the issue recommends and it aligns with the testing skill's guidance on extractable stubs.
+
+The alternative — `vi.mocked()` — is already used in `lifecycle.test.ts` for the shutdown-order test and works for hand-built mocks, but is semantically less clean: `vi.mocked()` asserts that a value is already a mock, which is true here but opaque to readers.
+Named variables make the mock-ness explicit at the construction site.
+
+For `lifecycle.test.ts`, the named-variable approach also eliminates the inconsistency between the two ordering tests — one currently uses `vi.mocked()` and the other uses casts.
+After this change both will use named stubs.
+
+## Design Overview
+
+### service-adapter.test.ts
+
+Refactor the "steer, abort, waitForAll, hasRunning" block's `createDeps` to return named stubs:
+
+```typescript
+function createDeps(overrides: Partial<AdapterDeps> = {}) {
+  const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>();
+  const mockAbort = vi.fn<AgentManagerLike["abort"]>(() => true);
+  const mockQueueSteer = vi.fn<AgentManagerLike["queueSteer"]>(() => true);
+
+  const deps: AdapterDeps = {
+    manager: {
+      spawn: vi.fn(() => "id"),
+      getRecord: mockGetRecord,
+      listAgents: vi.fn(() => []),
+      abort: mockAbort,
+      waitForAll: vi.fn(async () => {}),
+      hasRunning: vi.fn(() => true),
+      queueSteer: mockQueueSteer,
+    },
+    resolveModel: vi.fn(),
+    getCtx: () => ({ pi: {}, ctx: {} }),
+    getModelRegistry: () => ({ find: () => null, getAll: () => [] }),
+    ...overrides,
+  };
+
+  return { deps, mockGetRecord, mockAbort, mockQueueSteer };
+}
+```
+
+Callers destructure what they need:
+
+```typescript
+const { deps, mockAbort } = createDeps();
+mockAbort.mockReturnValue(false);  // ← type-checked, no cast
+```
+
+### lifecycle.test.ts
+
+Promote the `beforeEach`-scoped `runtime` and `manager` mock construction to use named stubs.
+The stubs that need reconfiguration (`setSessionContext`, `clearCompleted`) become named `let` variables alongside the existing `runtime`/`manager` lets, reset in `beforeEach`:
+
+```typescript
+let mockSetSessionContext: MockInstance<LifecycleRuntime["setSessionContext"]>;
+let mockClearCompleted: MockInstance<LifecycleManager["clearCompleted"]>;
+// ...assigned in beforeEach when building runtime/manager
+```
+
+Also convert the shutdown-order test's `vi.mocked()` calls to the same pattern for consistency — `unpublishService`, `clearSessionContext`, `abortAll`, `disposeNotifications`, `dispose` all become named stubs.
+
+### tool-start.test.ts
+
+Same pattern: promote `setUICtx` and `onTurnStart` to named `let` variables:
+
+```typescript
+let mockSetUICtx: MockInstance<ToolStartRuntime["setUICtx"]>;
+let mockOnTurnStart: MockInstance<ToolStartRuntime["onTurnStart"]>;
+```
+
+## Module-Level Changes
+
+| File                               | Change                                                                                                                                                                                                |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `test/service-adapter.test.ts`     | Refactor `createDeps` in the "steer, abort, waitForAll, hasRunning" block to return named mock stubs alongside `deps`. Update all 5 cast sites to use named stubs.                                    |
+| `test/handlers/lifecycle.test.ts`  | Extract `mockSetSessionContext`, `mockClearCompleted`, `mockAbortAll`, `mockDispose`, `mockClearSessionContext` as named `let` variables. Replace 2 casts and 5 `vi.mocked()` calls with named stubs. |
+| `test/handlers/tool-start.test.ts` | Extract `mockSetUICtx` and `mockOnTurnStart` as named `let` variables. Replace 2 casts with named stubs.                                                                                              |
+
+No production files are changed.
+
+## Test Impact Analysis
+
+1. No new tests are added — this is a refactoring of existing test infrastructure.
+2. No tests become redundant — every existing assertion stays.
+3. All existing tests must pass unchanged; only the mock-wiring changes.
+
+## TDD Order
+
+1. **Commit:** Refactor `createDeps` in `service-adapter.test.ts` to return named stubs; update all 5 cast sites.
+   All tests pass before and after.
+   Commit: `test: remove vi.fn() cast smell from service-adapter tests (#123)`
+2. **Commit:** Extract named stubs in `lifecycle.test.ts`; replace 2 casts and 5 `vi.mocked()` calls.
+   All tests pass.
+   Commit: `test: remove vi.fn() cast smell from lifecycle tests (#123)`
+3. **Commit:** Extract named stubs in `tool-start.test.ts`; replace 2 casts.
+   All tests pass.
+   Commit: `test: remove vi.fn() cast smell from tool-start tests (#123)`
+
+Each step is an independent file — order doesn't matter, but one-file-per-commit keeps diffs reviewable.
+
+## Risks and Mitigations
+
+| Risk                                                                                                                          | Mitigation                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Overrides via `...overrides` in `service-adapter.test.ts` could replace a manager method, leaving the named stub disconnected | Only `manager`-level overrides are spread; individual method overrides aren't used in this block.       |
+| Named stubs add return-surface to helpers                                                                                     | Each helper is test-local and the extra names are self-documenting. The alternative (casting) is worse. |
+| Converting `vi.mocked()` in `lifecycle.test.ts` shutdown test expands scope slightly beyond the cast pattern                  | Worth it for consistency — mixing `vi.mocked()` and named stubs in the same file is a different smell.  |
+
+## Open Questions
+
+None — the issue is fully scoped and the approach is established in the codebase.

package/docs/retro/0111-split-agent-record-lifecycle.md

@@ -0,0 +1,61 @@
+---
+issue: 111
+issue_title: "refactor(pi-subagents): split AgentRecord lifecycle state into phase-specific objects"
+---
+
+# Retro: #111 — split AgentRecord lifecycle state into phase-specific objects
+
+## Final Retrospective (2026-05-22T01:50:00Z)
+
+### Session summary
+
+Planned and implemented the `AgentRecord` lifecycle split across 12 TDD cycles plus doc updates, released as `pi-subagents-v6.8.0`.
+Three new phase-specific collaborators (`ExecutionState`, `WorktreeState`, `NotificationState`) replace 9 post-construction mutable fields.
+`pendingSteers` moved to a `Map` on `AgentManager`; stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods with read-only getters.
+`AgentRecordInit` trimmed from 19 optional fields to 4.
+
+### Observations
+
+#### What went well
+
+- **Lift-and-shift scaled from 7 files (#110) to 18 files (#111) without any intermediate test breakage.**
+  Every commit left all 41 test files passing.
+  The pattern — add new alongside old, migrate consumers with fallbacks (`record.execution?.session ?? record.session`), strip fallbacks in a final commit — is reliable for multi-step encapsulation refactors.
+- **Stats encapsulation was simpler than expected.**
+  Converting `toolUses`, `lifetimeUsage`, `compactionCount` to private fields with getters and mutation methods required zero changes to read-only consumers because the getter names match the old field names.
+  Only `record-observer.ts` (the sole writer) needed updating.
+- **The `createTestRecord` factory intersection type trick preserved backward compatibility.**
+  The factory accepts `toolUses?: number` via `Partial<AgentRecordInit> & { toolUses?: number; ... }` and internally calls `record.incrementToolUses()` in a loop.
+  This let 10+ test files continue passing `toolUses: 5` without rewriting each to call mutation methods directly.
+- **`Promise.withResolvers` timing analysis in the plan was unnecessary.**
+  The plan spent ~40 lines analyzing whether `promise` should live inside `ExecutionState` and concluded it should stay separate.
+  Implementation confirmed: `record.execution` is set in `onSessionCreated` (async callback), `record.promise` is set after `runner.run()` (synchronous return) — different moments, straightforward.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In the step 7 test for `record.execution`, the initial mock runner used `mockResolvedValue(...)` which doesn't call `onSessionCreated`, so `record.execution` stayed `undefined`.
+  Had to switch to `mockImplementation(async (..., opts) => { opts.onSessionCreated?.(session); ... })`.
+  The existing tests in the same file already use this pattern for record-observer tests, but I didn't check them first.
+  Impact: one test rewrite (~2 minutes), no rework to production code.
+- `scope-drift` — Step 4 absorbed step 5 (adding collaborator fields) without noting the merge in the commit or session log.
+  Step 5 became a no-op.
+  Impact: no rework, but the session narrative skipped a plan step without explanation.
+- `wrong-abstraction` — Step 12 was planned as a simple cleanup ("remove old fields and trim `AgentRecordInit`") but required coordinated changes across 18 files: removing 9 fields from `AgentRecordInit`, updating the `createTestRecord` factory, fixing 5 test files that passed removed fields, and stripping all fallback patterns.
+  This was 2-3 steps' worth of work compressed into one.
+  Impact: step 12 took significantly longer than other steps, though it landed cleanly.
+- `missing-context` — Did not proactively flag the `as ReturnType<typeof vi.fn>` cast smell in `service-adapter.test.ts` while migrating that file.
+  The user noticed it and asked about it.
+  Filed as #123.
+  Impact: added friction but no rework; follow-up issue created.
+  User-caught.
+
+#### What caused friction (user side)
+
+- No material friction observed.
+  The user's `ask_user` decisions during planning (NotificationState collaborator, Map on AgentManager) gave clear direction.
+  Quick "follow-up" response on the cast smell kept scope tight.
+
+### Changes made
+
+1. `packages/pi-subagents/docs/retro/0111-split-agent-record-lifecycle.md` — this retro file.
+2. `.pi/skills/testing/SKILL.md` — added field-removal rule symmetric to the existing field-addition rule (esbuild silent pass-through on unknown init properties).

package/docs/retro/0123-remove-vi-fn-cast-smell.md

@@ -0,0 +1,49 @@
+---
+issue: 123
+issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
+---
+
+# Retro: #123 — remove vi.fn() cast smell from test helpers
+
+## Final Retrospective (2026-05-22T00:00:00Z)
+
+### Session summary
+
+Planned and implemented removal of all 9 `as ReturnType<typeof vi.fn>` casts and 5 `vi.mocked()` calls across 3 test files, replacing them with named typed mock variables.
+Released as `pi-subagents-v6.8.1`.
+Pure test hygiene — no production code changes, no behavioral changes, 652 tests unchanged.
+
+### Observations
+
+#### What went well
+
+- **Three-file scope executed cleanly once the plan was right.**
+  Each file was an independent commit with no cross-file dependencies.
+  The named-variable pattern (`const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>()`) worked identically across all three test files despite different mock construction styles (factory function vs `beforeEach` assignment).
+
+#### What caused friction (agent side)
+
+- `scope-drift` — The initial plan scoped the fix to `service-adapter.test.ts` only, listing `lifecycle.test.ts` and `tool-start.test.ts` as explicit Non-Goals — despite the planning-phase grep showing all 9 cast sites across 3 files.
+  The user redirected with "let's eliminate this pattern of behavior."
+  Updated the GitHub issue body, rewrote the plan, and amended the commit.
+  Impact: plan rewrite (~2 minutes), no implementation rework.
+  User-caught.
+- `missing-context` — Imported `MockInstance` from `vitest` during step 1 (`service-adapter.test.ts`) but actually used `ReturnType<typeof vi.fn<...>>` — matching the pattern used in the other two files.
+  The unused import was caught by `pnpm run lint` at the post-implementation check, not proactively.
+  Impact: one extra edit + amend cycle.
+  Self-identified (via lint).
+- `other` — Ran `git commit --amend` to fix the unused import but HEAD was step 3's commit (`tool-start`), not step 1's (`service-adapter`).
+  The amend landed the `service-adapter.test.ts` change into the wrong commit with the wrong message.
+  Required `git reset --soft` back to the plan commit and recommitting all 3 files.
+  Impact: ~1 minute of git surgery, clean result.
+  Self-identified.
+
+#### What caused friction (user side)
+
+- The issue body scoped the fix to `service-adapter.test.ts` only, which the agent followed literally.
+  The broader intent ("eliminate this pattern") was implicit.
+  Flagging the desired scope as "all files with this pattern" in the issue body would have avoided the plan rewrite.
+
+### Changes made
+
+1. Wrote retro file at `packages/pi-subagents/docs/retro/0123-remove-vi-fn-cast-smell.md`.

package/package.json

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

package/src/agent-manager.ts

@@ -13,7 +13,6 @@ import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
-import type { ExecutionState } from "./execution-state.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
@@ -21,11 +20,15 @@ import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, Subagen
 import type { WorktreeManager } from "./worktree.js";
 import { WorktreeState } from "./worktree-state.js";
 
-export type OnAgentComplete = (record: AgentRecord) => void;
-export type OnAgentStart = (record: AgentRecord) => void;
-export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
+/** Observer interface for agent lifecycle notifications. */
+export interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+}
+
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
@@ -37,9 +40,7 @@ export interface AgentManagerOptions {
   /** Injected getter for the concurrency limit — owned by SettingsManager. */
   getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
-  onStart?: OnAgentStart;
-  onComplete?: OnAgentComplete;
-  onCompact?: OnAgentCompact;
+  observer?: AgentManagerObserver;
 }
 
 interface SpawnArgs {
@@ -80,9 +81,7 @@ export interface SpawnOptions {
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
-  private onComplete?: OnAgentComplete;
-  private onStart?: OnAgentStart;
-  private onCompact?: OnAgentCompact;
+  private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
   private readonly exec: ShellExec;
@@ -102,9 +101,7 @@ export class AgentManager {
     this.worktrees = options.worktrees;
     this.exec = options.exec;
     this.registry = options.registry;
-    this.onComplete = options.onComplete;
-    this.onStart = options.onStart;
-    this.onCompact = options.onCompact;
+    this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
@@ -196,7 +193,7 @@ export class AgentManager {
 
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
-    this.onStart?.(record);
+    this.observer?.onAgentStarted(record);
 
     // Wire parent abort signal to stop the subagent when the parent is interrupted
     let detachParentSignal: (() => void) | undefined;
@@ -239,7 +236,7 @@ export class AgentManager {
         }
         // Subscribe record observer for stats accumulation
         unsubRecordObserver = subscribeRecordObserver(session, record, {
-          onCompact: (r, info) => this.onCompact?.(r, info),
+          onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
         });
         options.onSessionCreated?.(session);
       },
@@ -268,7 +265,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
+          try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
           this.drainQueue();
         }
         return responseText;
@@ -290,7 +287,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          this.onComplete?.(record);
+          this.observer?.onAgentCompleted(record);
           this.drainQueue();
         }
         return "";
@@ -311,7 +308,7 @@ export class AgentManager {
         // Late failure (e.g. strict worktree-isolation) — surface on the record
         // so the user/agent can see it via /agents, then keep draining.
         record.markError(err);
-        this.onComplete?.(record);
+        this.observer?.onAgentCompleted(record);
       }
     }
   }
@@ -347,7 +344,7 @@ export class AgentManager {
     record.resetForResume(Date.now());
 
     const unsubResume = subscribeRecordObserver(session, record, {
-      onCompact: (r, info) => this.onCompact?.(r, info),
+      onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
     });
 
     try {

package/src/index.ts

@@ -12,7 +12,7 @@
 
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { AgentManager } from "./agent-manager.js";
+import { AgentManager, type AgentManagerObserver } from "./agent-manager.js";
 import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
@@ -64,14 +64,18 @@ export default function (pi: ExtensionAPI) {
   });
   settings.load();
 
-  // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager({
-    runner: { run: runAgent, resume: resumeAgent },
-    worktrees: new GitWorktreeManager(process.cwd()),
-    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
-    registry,
-    onComplete: (record) => {
-      // Emit lifecycle event based on terminal status
+  // Observer: receives agent lifecycle notifications and dispatches events/notifications.
+  const observer: AgentManagerObserver = {
+    onAgentStarted(record) {
+      // Emit started event when agent transitions to running (including from queue).
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+    onAgentCompleted(record) {
+      // Emit lifecycle event based on terminal status.
       const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
       const eventData = buildEventData(record);
       if (isError) {
@@ -80,14 +84,14 @@ export default function (pi: ExtensionAPI) {
         pi.events.emit("subagents:completed", eventData);
       }
 
-      // Persist final record for cross-extension history reconstruction
+      // Persist final record for cross-extension history reconstruction.
       pi.appendEntry("subagents:record", {
         id: record.id, type: record.type, description: record.description,
         status: record.status, result: record.result, error: record.error,
         startedAt: record.startedAt, completedAt: record.completedAt,
       });
 
-      // Skip notification if result was already consumed via get_subagent_result
+      // Skip notification if result was already consumed via get_subagent_result.
       if (record.notification?.resultConsumed) {
         notifications.cleanupCompleted(record.id);
         return;
@@ -95,15 +99,7 @@ export default function (pi: ExtensionAPI) {
 
       notifications.sendCompletion(record);
     },
-    onStart: (record) => {
-      // Emit started event when agent transitions to running (including from queue)
-      pi.events.emit("subagents:started", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-      });
-    },
-    onCompact: (record, info) => {
+    onAgentCompacted(record, info) {
       // Emit compacted event when agent's session compacts (preserves count on record).
       pi.events.emit("subagents:compacted", {
         id: record.id,
@@ -114,6 +110,14 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
+  };
+
+  const manager = new AgentManager({
+    runner: { run: runAgent, resume: resumeAgent },
+    worktrees: new GitWorktreeManager(process.cwd()),
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+    registry,
+    observer,
     getMaxConcurrent: () => settings.maxConcurrent,
     getRunConfig: () => settings,
   });