@gotgenes/pi-subagents 16.3.1 → 16.5.0

package/docs/plans/0412-unify-session-mock-builders.md

@@ -0,0 +1,146 @@
+---
+issue: 412
+issue_title: "Unify the three overlapping session-mock builders in pi-subagents tests"
+---
+
+# Unify the overlapping session-mock builders (targeted reuse)
+
+## Problem Statement
+
+`test/helpers/` carries three session-mock builders whose shapes overlap on four fields — `messages`, `subscribe`, `dispose`, `steer`:
+
+- `createMockSession` (`mock-session.ts`) — a subscribable event bus (`messages`, `subscribe`, `emit`, `dispose`, `steer`, `sessionManager`).
+- `createSubagentSessionStub` (`mock-session.ts`) — a born-complete `SubagentSession` wrapper (turn-loop spies plus `messages`/`subscribe`/`dispose`/`steer` delegation).
+- `createFactorySession` (`subagent-session-io.ts`) — the `createSubagentSession`-factory session (`bindExtensions`, `setActiveToolsByName`, `getActiveToolNames`, plus `messages`/`subscribe`/`prompt`/`abort`/`steer`/`dispose`).
+
+Issue [#412] asks whether to unify the three behind one configurable builder.
+The issue itself flags the risk — "trading three small honest stubs for one over-parameterized factory" — and quotes Sandi Metz: "duplication is far cheaper than the wrong abstraction."
+
+## Goals
+
+- Remove the one genuine independent redeclaration of the four shared base fields, which lives in `createFactorySession`.
+- Make `createMockSession` the explicit shared core, and have `createFactorySession` layer its factory facet on top of that core (working event bus as the core default).
+- Keep the change test-only and behavior-preserving for production code.
+
+This change is **not breaking** — it touches only `test/helpers/` and a doc note; no published surface, default, or runtime behavior changes.
+
+## Non-Goals
+
+- The full composable-factory design from the issue's "Proposed change" (one `createSessionMock()` with opt-in `withTurnLoop()` / `withBindFacet()` extensions).
+  Rejected at the `Decide` gate (operator chose targeted reuse) because it forces a multi-facet parameterized factory the issue itself warns against.
+- Changing `createSubagentSessionStub`.
+  It already **composes** a `createMockSession` internally and delegates `steer`/`dispose`/`subscribe`/`messages` to it, so its overlap is intrinsic delegation glue, not duplication.
+- Renaming any builder or changing any builder's public signature.
+- Touching production `src/` modules.
+
+## Background
+
+Relevant modules:
+
+- `test/helpers/mock-session.ts` — defines `createMockSession` (the event-bus core), `createSubagentSessionStub` (the `SubagentSession` wrapper, which calls `createMockSession()` as its default `session`), plus the `toAgentSession`/`toSubagentSession` casts.
+- `test/helpers/subagent-session-io.ts` — defines `createFactorySession` (and the IO/lookup/lifecycle stubs).
+  `createFactorySession` independently redeclares `messages: []` and an **inert** `subscribe: vi.fn(() => () => {})`, plus its own `steer`/`dispose`, then adds the factory facet.
+- `src/lifecycle/create-subagent-session.ts` — production consumer of the raw factory session: calls `getActiveToolNames()`, `setActiveToolsByName()`, `bindExtensions()`, and `dispose()`.
+- `src/lifecycle/subagent-session.ts` — wraps the raw session and calls `session.subscribe(...)`, `session.prompt(...)`, `session.abort(...)`, `session.steer(...)`, `session.dispose()`, `session.messages`.
+
+Structural reading (per the `code-design` "structural reasons before extracting duplication" heuristic): the three builders sit on two axes — AgentSession-vs-`SubagentSession` (type) and event-bus-vs-factory (facet).
+`createMockSession` and `createFactorySession` are both AgentSession stubs; `createSubagentSessionStub` is the `SubagentSession` wrapper.
+The only honest, non-delegation duplication is `createFactorySession`'s independent base, so that is the entire target.
+
+AGENTS.md constraint: this is the `@gotgenes/pi-subagents` package; run package-scoped scripts via `pnpm --filter @gotgenes/pi-subagents exec vitest run` and type-check with `pnpm run check`.
+
+## Design Overview
+
+`createMockSession` is already the core shape, with the working event bus the operator chose as the default.
+`createFactorySession` is rebuilt to spread that core and add only the factory facet:
+
+```typescript
+export function createFactorySession(options: FactorySessionOptions = {}) {
+	const before = options.toolsBeforeBind ?? ["read"];
+	const after = options.toolsAfterBind ?? before;
+	let bound = false;
+	return {
+		...createMockSession(), // working event bus + messages/steer/dispose/sessionManager core
+		prompt: vi.fn().mockResolvedValue(undefined),
+		abort: vi.fn(),
+		getActiveToolNames: vi.fn(() => (bound ? after : before)),
+		setActiveToolsByName: vi.fn(),
+		bindExtensions: vi.fn(async () => {
+			bound = true;
+		}),
+	};
+}
+```
+
+Mock-typing is preserved through the spread.
+`createMockSession()` returns `MockSession & Record<string, unknown>`; the explicit facet properties added in the literal intersect with the `Record`'s `unknown` index signature, and `unknown & Mock<...>` narrows to `Mock<...>`.
+Verified with a throwaway `tsc --noEmit` probe: `session.setActiveToolsByName.mock.calls[0][0]` type-checks after the spread.
+
+Facet semantics are unchanged: `getActiveToolNames` closes over a `bound` flag flipped by `bindExtensions`, returning `before` until bind and `after` after.
+
+Behavioral delta (intentional, per the operator's "working bus is the core default" choice): `createFactorySession`'s `subscribe` changes from inert (`() => () => {}`) to the core's real bus, and the session gains `emit` and `sessionManager`.
+No factory test emits events, and production `subagent-session.ts` only registers a subscriber (never emits during these tests), so the change is inert in practice — the disposer now truly unregisters instead of being a no-op.
+
+Edge cases:
+
+- `create-subagent-session.test.ts:194` asserts `expect(session.dispose).toHaveBeenCalledOnce()` — `dispose` remains a `vi.fn()` spy supplied by the core, so the assertion holds.
+- The factory session is returned through `io.createSession.mockResolvedValue({ session })`, not assigned as a fresh literal to a typed slot, so the extra `emit`/`sessionManager` fields raise no excess-property error.
+
+## Module-Level Changes
+
+- `test/helpers/subagent-session-io.ts` — rewrite `createFactorySession` to spread `...createMockSession()` and add the factory facet; import `createMockSession` from `#test/helpers/mock-session`.
+  Update its docstring to state it layers the factory facet on the shared `createMockSession` core.
+- `test/helpers/subagent-session-io.test.ts` — add one self-test asserting `createFactorySession` exposes the core's working event bus (subscribe a fn, `emit`, assert receipt).
+  Existing `createFactorySession` self-tests remain unchanged.
+- `test/helpers/mock-session.ts` — docstring touch-up only: note that `createMockSession` is the shared session-mock core that `createFactorySession` builds on (no code change).
+- `docs/architecture/architecture.md` — update the Phase 17 Step 7 "Landed" closing sentence (currently "The three overlapping session-mock builders this surfaced are tracked separately [#412].") to record the resolution: targeted reuse — `createFactorySession` now layers on the `createMockSession` core; `createSubagentSessionStub`'s overlap is intrinsic delegation and was left as-is.
+
+Grep confirmation (no other consumers break): `createFactorySession` is referenced only in `create-subagent-session.test.ts` and its own self-test/source; `.pi/skills/package-*/SKILL.md` mention none of the three builders by name; the `[#412]:` reference-link definition already exists at the bottom of `architecture.md`.
+
+## Test Impact Analysis
+
+1. **New tests enabled** — one self-test for `createFactorySession`'s newly-inherited working event bus (subscribe/emit), previously impossible because its `subscribe` was inert.
+2. **Tests made redundant** — none.
+   The existing `createFactorySession` self-tests exercise the factory facet (the eight methods, the before/after bind flip), which is unchanged and still its own concern.
+3. **Tests that must stay as-is** — the `createMockSession` event-bus self-tests in `mock-session.test.ts` (they pin the core the factory now reuses); the `createFactorySession` facet self-tests; `create-subagent-session.test.ts` lifecycle tests (they exercise the production consumer of the factory session).
+
+## Invariants at risk
+
+The change touches the lifecycle test fixtures refactored in Phase 17 Step 7 ([#378]).
+That step's documented `Outcome`/`Landed` invariants and the tests that pin them:
+
+- "AAA structure: `createSubagentSession(...)` act kept explicit per test" — pinned by `create-subagent-session.test.ts` (the act calls remain in each `it`; this plan does not touch them).
+- "`createFactorySession` flips `getActiveToolNames` from before-bind to after-bind" — pinned by the existing `subagent-session-io.test.ts` facet self-tests, which stay green through the rewrite.
+
+No earlier outcome is regressed: the rewrite preserves every facet assertion and only adds the event-bus surface.
+
+## TDD Order
+
+1. **`refactor(test):` fold `createFactorySession` onto the shared core** (#412).
+   - Red: add `it("exposes the core's working event bus (subscribe/emit)")` to the `createFactorySession` describe in `subagent-session-io.test.ts` — fails to compile/pass because the current return has no `emit` and an inert `subscribe`.
+   - Green: rewrite `createFactorySession` to `{ ...createMockSession(), <factory facet> }`; import `createMockSession`; refresh the docstrings in both helper files.
+   - Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/helpers/subagent-session-io.test.ts test/helpers/mock-session.test.ts test/lifecycle/create-subagent-session.test.ts`, then `pnpm run check` (spread-typing) and the full package suite.
+   - Commit: `refactor(test): build createFactorySession on the shared createMockSession core (#412)`.
+2. **`docs:` record the resolution in the architecture doc** (#412).
+   - Update the Phase 17 Step 7 closing sentence in `docs/architecture/architecture.md` to describe the targeted-reuse outcome (no roadmap-table or metric-row change required; rerun `pnpm fallow:dupes` only to report, not to gate).
+   - Commit: `docs: record session-mock builder unification outcome (#412)`.
+
+Both steps are test/doc-only with single, isolated surfaces, so no lift-and-shift staging is needed.
+
+## Risks and Mitigations
+
+- **Risk:** the spread erases `Mock<...>` typing on the facet methods, breaking `.mock.calls` assertions.
+  **Mitigation:** verified with a throwaway `tsc --noEmit` probe that `setActiveToolsByName.mock.calls[0][0]` type-checks after the spread (intersection narrows `unknown & Mock<...>` to `Mock<...>`); Step 1 reruns `pnpm run check`.
+- **Risk:** the inert→working `subscribe` change alters a lifecycle test's behavior.
+  **Mitigation:** no factory test emits events; production only registers a subscriber during these tests; `session.dispose` remains a spy.
+  Step 1's verify command runs the lifecycle suite.
+- **Risk:** the extra `emit`/`sessionManager` fields trip excess-property checks at a consumer.
+  **Mitigation:** the factory session flows through `mockResolvedValue({ session })`, not a fresh typed literal, so excess-property checking does not apply.
+
+## Open Questions
+
+None.
+The operator confirmed targeted reuse with a working-bus core default at the `Decide` gate.
+
+[#378]: https://github.com/gotgenes/pi-packages/issues/378
+[#412]: https://github.com/gotgenes/pi-packages/issues/412

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

@@ -0,0 +1,228 @@
+---
+issue: 420
+issue_title: "pi-subagents: fold subagent run metrics and live activity onto the core record"
+---
+
+# Fold subagent run metrics and live activity onto the core record
+
+## Problem Statement
+
+The run-metric domain is split across two parallel observers, each subscribed to every child session.
+`record-observer` accumulates `SubagentState` (tool uses, lifetime usage, compaction count); `ui-observer` accumulates a separate `AgentActivityTracker` (active tools, response text, turn count).
+`turnCount` is a genuine run metric that lives only in the UI tracker, so `notification.ts` and the foreground result text reach into the tracker to recover it (Phase 18 Finding 4).
+Consolidating the live-activity fields onto the single owned run-state value object (`SubagentState`) removes the duplication and is the first move in disentangling the UI's activity tier from the core.
+
+This is Phase 18 Step 1 of the architecture roadmap (`docs/architecture/architecture.md`).
+It is a **pure addition, tidy-first**: `AgentActivityTracker` and `ui-observer` still exist, both observers still run, and nothing reads the new getters yet.
+The reader migration is Step 2 ([#421]) and the tracker deletion is Step 3 ([#422]).
+
+## Goals
+
+- Extend `SubagentState` (`src/lifecycle/subagent-state.ts`) with the live-activity fields — `turnCount`, `activeTools`, `responseText` — and their transition methods, behind read-only getters, owning all their own mutations (no field written from outside).
+- Have `subscribeSubagentObserver` (`src/observation/record-observer.ts`) handle `turn_end`, `tool_execution_start`, `message_start`, and `message_update` (text_delta) alongside the events it already handles, mutating the same `SubagentState`.
+- Add read-only `turnCount` / `maxTurns` / `activeTools` / `responseText` getters to `Subagent` (`src/lifecycle/subagent.ts`); the first three plus `responseText` delegate to the owned state, `maxTurns` delegates to `this.execution.maxTurns` (the effective max-turns already wired at spawn).
+- Preserve the `AgentActivityTracker` semantics the readers depend on so Step 2 is a clean swap: `turnCount` starts at 1 and increments on each `turn_end`; `activeTools` is a `ReadonlyMap<string, string>` keyed `name_seq` to disambiguate concurrent same-name tools; `responseText` resets at each `message_start` and appends each text delta.
+
+This change is **not breaking**.
+The published service surface (`src/service/service.ts`) exposes `SubagentRecord`/`SubagentStatus`, not `SubagentState` or the `Subagent` constructor; the change only adds getters and value-object fields.
+No observable behavior changes — both observers still run and no consumer reads the new getters.
+
+## Non-Goals
+
+- Migrating any reader (`widget-renderer`, `conversation-viewer`, `agent-menu`, `foreground-runner`, `notification`) off `AgentActivityTracker` — Step 2 ([#421]).
+- Deleting `AgentActivityTracker` / `ui-observer` or dropping `SubagentRuntime.agentActivity` — Step 3 ([#422]).
+- Removing the second (`ui-observer`) session subscription — Step 3.
+- Adding a `session` reference to `SubagentState` — the tracker's `_session`/`setSession` exists only for the UI's polling reads and is migrated/removed in Steps 2–3, not folded here.
+- The deeper "metrics as a pure observer projection" target — deliberately deferred per the architecture doc's first-principles refinement; folding onto the record (consistent with Phase 17's `SubagentState`) avoids inventing an asynchronous-observation seam.
+- Resetting the new live-activity fields in `resetForResume` — see Design Overview; left unchanged to preserve tracker parity.
+
+## Background
+
+Relevant modules and how they relate:
+
+- `src/lifecycle/subagent-state.ts` — the value object under change.
+  Already owns status/result/error/timestamps and stats (`toolUses`, `lifetimeUsage`, `compactionCount`) behind getters, mutated only via transition/accumulation methods (`markRunning`, `incrementToolUses`, `addUsage`, `incrementCompactions`).
+  Pure value object — imports only `LifetimeUsage`/`addUsage` from `usage.ts`; no Pi SDK imports (keep it that way).
+- `src/observation/record-observer.ts` — `subscribeSubagentObserver(session, state, { onCompact })` subscribes once and currently handles `tool_execution_end`, `message_end` (assistant), and `compaction_end`.
+- `src/ui/agent-activity-tracker.ts` — the parallel `AgentActivityTracker` whose live fields (`_activeTools`, `_toolKeySeq`, `_responseText`, `_turnCount` starting at 1) and transition methods (`onToolStart`, `onToolDone`, `onMessageStart`, `onMessageUpdate`, `onTurnEnd`) are the behavior being folded onto `SubagentState`.
+  It also carries `_session`/`setSession` and `maxTurns` — `maxTurns` is folded (via `execution`), `_session` is not.
+- `src/ui/ui-observer.ts` — `subscribeUIObserver` maps `tool_execution_start`/`tool_execution_end`/`message_start`/`message_update`/`turn_end` onto the tracker.
+  The event-shape reference for the new `record-observer` branches (`event.toolName`; `event.assistantMessageEvent.type === "text_delta"` → `event.assistantMessageEvent.delta`).
+- `src/lifecycle/subagent.ts` — holds one private `SubagentState`; its getters and mutation methods are one-line delegations.
+  `run()` and `resume()` both attach `subscribeSubagentObserver(session, this.state, …)`.
+  `this.execution.maxTurns` is the effective max-turns (both spawners pass `execution.effectiveMaxTurns` as `options.maxTurns`, threaded into `SubagentExecution.maxTurns` by `SubagentManager.spawn`).
+- `src/tools/spawn-config.ts` — `effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? settings.defaultMaxTurns)`.
+  `AgentActivityTracker` is constructed with `effectiveMaxTurns`; `SubagentExecution.maxTurns` carries the same value, so the new `maxTurns` getter matches the tracker.
+
+AGENTS.md / code-design constraints that apply:
+
+- Keep Pi SDK imports out of `SubagentState` — the new fields and methods stay SDK-free.
+- The new `record-observer` branches consume SDK event payloads via the existing lean structural reads (`event.toolName`, `event.assistantMessageEvent`) — no new SDK type imports needed.
+- `SubagentState` and `Subagent` are reached through the `types.ts`/internal barrels; adding getters does not change any export.
+
+## Design Overview
+
+### `SubagentState` additions
+
+Three new private fields with read-only getters and five transition methods, mirroring the `AgentActivityTracker` semantics exactly so the Step 2 swap is byte-equivalent:
+
+```typescript
+// Live activity — accumulated via transition methods, readable via getters
+private _turnCount = 1;
+get turnCount(): number { return this._turnCount; }
+
+private _activeTools = new Map<string, string>();
+get activeTools(): ReadonlyMap<string, string> { return this._activeTools; }
+
+private _toolKeySeq = 0;
+
+private _responseText = "";
+get responseText(): string { return this._responseText; }
+
+/** Record a turn boundary. Called by record-observer on turn_end. */
+incrementTurnCount(): void { this._turnCount++; }
+
+/** Record a tool starting. Called by record-observer on tool_execution_start. */
+addActiveTool(toolName: string): void {
+	this._activeTools.set(toolName + "_" + (++this._toolKeySeq), toolName);
+}
+
+/** Remove one active tool by name (first match). Called by record-observer on tool_execution_end. */
+removeActiveTool(toolName: string): void {
+	for (const [key, name] of this._activeTools) {
+		if (name === toolName) { this._activeTools.delete(key); break; }
+	}
+}
+
+/** Reset the current response text. Called by record-observer on message_start. */
+resetResponseText(): void { this._responseText = ""; }
+
+/** Append a text delta to the current response text. Called by record-observer on message_update. */
+appendResponseText(delta: string): void { this._responseText += delta; }
+```
+
+The `_toolKeySeq` counter has no getter — it is internal disambiguation state, exactly as in the tracker.
+`turnCount` initializes to `1` (not `0`) to match the tracker; the readers (`notification.ts` `turnCount ?? 0`, `result-renderer.ts` `turnCount > 0`) already assume the at-least-1 invariant once an agent exists.
+
+`resetForResume` is left **unchanged**.
+The tracker is not reset on resume today (the resume path in `agent-tool.ts` does not reconstruct it), so the record-observer accumulating onto the surviving `SubagentState` across a resume preserves parity (turn count continues, response text carries the last message, active tools are empty after a completed run).
+Touching `resetForResume` here would be a behavior change, contradicting the pure-addition contract.
+Flagged in Risks for Step 2 to revisit if a reader demands a reset.
+
+### `record-observer` additions
+
+Three new branches alongside the existing ones, reading the same SDK payload shapes `ui-observer` reads:
+
+```typescript
+if (event.type === "tool_execution_start") state.addActiveTool(event.toolName);
+if (event.type === "turn_end") state.incrementTurnCount();
+if (event.type === "message_start") state.resetResponseText();
+if (
+	event.type === "message_update" &&
+	event.assistantMessageEvent.type === "text_delta"
+) {
+	state.appendResponseText(event.assistantMessageEvent.delta);
+}
+```
+
+The existing `tool_execution_end` branch already fires `state.incrementToolUses()`; it gains a paired `state.removeActiveTool(event.toolName)` so the active-tool map drains symmetrically (the tracker did this in `onToolDone`).
+The observer takes no new options and emits no callbacks for these branches — the live fields are read-only state, polled by consumers later.
+
+### `Subagent` getters
+
+Four one-line getters added next to the existing `toolUses`/`lifetimeUsage`/`compactionCount` delegations:
+
+```typescript
+get turnCount(): number { return this.state.turnCount; }
+get activeTools(): ReadonlyMap<string, string> { return this.state.activeTools; }
+get responseText(): string { return this.state.responseText; }
+get maxTurns(): number | undefined { return this.execution.maxTurns; }
+```
+
+`maxTurns` is the one getter that does not delegate to `state` — max-turns is execution config, not accumulated run state, and `this.execution.maxTurns` already holds the effective value (`effectiveMaxTurns`) the tracker was constructed with.
+
+### Extracted-module interaction check (record-observer ↔ SubagentState)
+
+The observer already targets `SubagentState` directly (Phase 17) and carries no `Subagent` dependency.
+The new branches are Tell-Don't-Ask: the observer tells the state to mutate (`addActiveTool`, `incrementTurnCount`, …) and never reads-then-writes a field on the state.
+No output arguments, no reach-through, no reverse search — the same shape as the existing three branches.
+
+## Module-Level Changes
+
+- `src/lifecycle/subagent-state.ts` — add `_turnCount`/`_activeTools`/`_toolKeySeq`/`_responseText` fields, their getters (`turnCount`, `activeTools`, `responseText`), and five transition methods (`incrementTurnCount`, `addActiveTool`, `removeActiveTool`, `resetResponseText`, `appendResponseText`).
+  Update the file header doc comment to note the live-activity fields.
+- `src/observation/record-observer.ts` — add `tool_execution_start`, `turn_end`, `message_start`, `message_update` (text_delta) branches; add `removeActiveTool` to the existing `tool_execution_end` branch.
+  Update the JSDoc "Handles:" list.
+- `src/lifecycle/subagent.ts` — add `turnCount`, `activeTools`, `responseText`, `maxTurns` getters.
+- `src/lifecycle/subagent-state.ts` is referenced in `.pi/skills/package-pi-subagents/SKILL.md` and `docs/architecture/architecture.md` only as a value object / domain entry; no symbol is removed or renamed, so no skill/doc prose update is required.
+  The architecture doc's Phase 18 Step 1 entry already describes this work — no edit needed.
+
+No existing export is removed or renamed; no call site changes.
+The `AgentActivityTracker` / `ui-observer` modules are untouched (they are deleted in Step 3).
+
+## Test Impact Analysis
+
+This is an additive change, so the analysis is mostly about new coverage:
+
+1. **New unit tests enabled.**
+   `subagent-state.test.ts` gains direct tests for the new fields/methods (turn count starts at 1 and increments; active-tool add/remove with concurrent same-name handling; response-text reset/append) — testable on a bare `SubagentState` with no session or executor.
+   `record-observer.test.ts` gains tests that emitting `tool_execution_start`/`turn_end`/`message_start`/`message_update`/`tool_execution_end` drives the new state fields, using the existing `createMockSession` `emit` harness.
+2. **Tests that become redundant.**
+   None yet — `ui-observer.test.ts` and the tracker tests still pin live behavior until Step 3 deletes those modules.
+   The new tests overlap conceptually with `ui-observer.test.ts` but exercise a different module (`record-observer` → `SubagentState`), so both stay until the tracker is removed.
+3. **Tests that must stay as-is.**
+   All existing `record-observer.test.ts` cases (tool uses, lifetime usage, compaction) genuinely exercise the observer→state path being extended and must keep passing unchanged.
+   `subagent.test.ts` getter/delegation tests stay; new getter tests are added beside them.
+
+## Invariants at risk
+
+Phase 17 Step 1 ([#373]) established that `SubagentState` owns all its own mutations (no field written from outside) and that `record-observer` targets `SubagentState` directly with no `Subagent` dependency.
+
+- **Invariant: the value object owns every mutation** — pinned by the encapsulation tests in `subagent-state.test.ts` (fields are read-only getters; mutation only via methods).
+  The new fields follow the same private-field/getter/transition-method shape; new tests assert mutation flows only through the new methods.
+- **Invariant: `record-observer` carries no `Subagent` dependency** — pinned by `record-observer.test.ts` constructing a bare `SubagentState` (never a `Subagent`).
+  The new branches keep that property (they call `state.*` only); the existing test setup (`makeState()` returns `new SubagentState(...)`) already guards it.
+
+No earlier phase step's `Outcome:` is regressed — this step only adds to the record both prior steps consolidated onto.
+
+## TDD Order
+
+1. **`SubagentState` live-activity fields and transition methods.**
+   Surface: `test/lifecycle/subagent-state.test.ts`.
+   Red→green: new `describe` blocks for turn count (defaults to 1, `incrementTurnCount` increments), active tools (`addActiveTool` adds with unique keys for concurrent same-name tools, `removeActiveTool` removes first match and is a no-op when absent, getter is read-only), and response text (defaults to `""`, `resetResponseText` clears, `appendResponseText` concatenates).
+   Implement the fields/getters/methods in `src/lifecycle/subagent-state.ts`.
+   Commit: `feat: add live-activity fields to SubagentState (#420)`.
+2. **`record-observer` populates the live-activity fields.**
+   Surface: `test/observation/record-observer.test.ts`.
+   Red→green: new tests that `tool_execution_start` adds an active tool, paired `tool_execution_end` removes it (extending the existing tool-uses test or a sibling case), `turn_end` increments `turnCount`, `message_start` resets `responseText`, and `message_update` text_delta appends; assert non-text_delta `message_update` is ignored.
+   Implement the new branches in `src/observation/record-observer.ts` and the `removeActiveTool` call in the existing `tool_execution_end` branch.
+   Commit: `feat: accumulate live activity in record-observer (#420)`.
+3. **`Subagent` exposes the live-activity getters.**
+   Surface: `test/lifecycle/subagent.test.ts`.
+   Red→green: tests that `turnCount`/`activeTools`/`responseText` delegate to the owned state (seed via a supplied `SubagentState` or by driving the attached observer), and `maxTurns` returns `execution.maxTurns`.
+   Implement the four getters in `src/lifecycle/subagent.ts`.
+   Run `pnpm run check` after this commit — the getters are the public-facing surface this step adds.
+   Commit: `feat: expose live-activity getters on Subagent (#420)`.
+
+Each step is independently green: the field exists before the observer writes it, and the observer writes it before `Subagent` exposes it.
+No existing test breaks at any step (pure addition, no removed/renamed symbol).
+
+## Risks and Mitigations
+
+- **Risk: the folded fields drift from `AgentActivityTracker` semantics, making Step 2's swap not behavior-preserving.**
+  Mitigation: the transition methods are copied field-for-field (turn count starts at 1, `name_seq` keying, first-match removal, reset-then-append response text); Step 2's reader-migration tests will compare record getters against the tracker before deletion.
+- **Risk: resume parity — the surviving `SubagentState` accumulates turn count across a resume while a fresh tracker would not.**
+  Mitigation: the tracker is *not* reset on resume today either (it is not reconstructed), so the record matches.
+  `resetForResume` is left unchanged and the decision is documented; Step 2 revisits if a reader needs a per-resume reset.
+- **Risk: a second observer now writes the same conceptual fields (record-observer + ui-observer), briefly duplicating active-tool/turn-count bookkeeping.**
+  Mitigation: this is the intended tidy-first overlap; the duplicate (`ui-observer`) is removed in Step 3 ([#422]).
+  No consumer reads the record's copy yet, so the duplication is inert.
+
+## Open Questions
+
+- Whether `resetForResume` should clear the live-activity fields is deferred to Step 2 ([#421]), where the actual reader behavior on resume is observable.
+  Resolving it now would be speculative and would break the pure-addition contract.
+
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#373]: https://github.com/gotgenes/pi-packages/issues/373

package/docs/retro/0378-consolidate-lifecycle-test-fixtures.md

@@ -0,0 +1,100 @@
+---
+issue: 378
+issue_title: "Consolidate lifecycle test fixtures"
+---
+
+# Retro: #378 — Consolidate lifecycle test fixtures
+
+## Stage: Planning (2026-06-15T00:00:00Z)
+
+### Session summary
+
+Planned Phase 17 Step 7 — consolidating the lifecycle test clone families into shared/file-local helpers.
+Produced `docs/plans/0378-consolidate-lifecycle-test-fixtures.md` with a six-step lift-and-shift TDD order and committed it.
+
+### Observations
+
+- The issue body is stale relative to `main`: it cites five families across six files (including `concurrency-queue.test.ts` and a 766-LOC `subagent-manager.test.ts`).
+  Measuring with `fallow dupes -r packages/pi-subagents` against today's `main` shows **four** lifecycle families — Steps 1–6 already removed the queue (`concurrency-queue.test.ts` → `concurrency-limiter.test.ts`) and the `subagent.test.ts`/`concurrency-limiter.test.ts` families.
+  The plan is written against the measured current state, not the issue snapshot.
+- Design call: promote to `test/helpers/` only the genuinely cross-file duplication (the `createSubagentSession`-test mock-session builder, shared by `create-subagent-session.test.ts` and `create-subagent-session-extension-tools.test.ts` — `createFactorySession`).
+  The manager and `subagent-session` families are intra-file (fallow recommends same-file extraction), so they get file-local helpers.
+  Force-promoting intra-file families to `test/helpers/` would manufacture cross-file coupling that does not exist.
+- Resisted extracting the `io.createSession.mockResolvedValue(...)` + `createSubagentSession(...)` invoke pair into a helper — two lines with per-test varying overrides; wrapping the system-under-test call would be procedure-splitting, not design improvement.
+- Invariants at risk flagged: Step 1/Step 3's "every spawned agent has a `promise` at spawn" (pinned by the queued-promise test) and Step 3's "zero external `.promise`/`.notification` writes outside `subagent.ts`" (grep-verifiable).
+  `arrangeQueuedPair()` must return the queued id; Step 4 folds in a re-grep.
+- Baseline: package test duplication 669 lines / 3.3% across 20 files; the four lifecycle families total ~122 lines, so Step 7 alone should land below the 600-line goal (~547).
+  Flagged as an Open Question pending the Step 6 `fallow dupes` measurement.
+- Not breaking — test-only, no `src/`, public-surface, or behavior change.
+
+## Stage: Implementation — TDD (2026-06-15T23:10:00Z)
+
+### Session summary
+
+Executed the lifecycle test fixture consolidation across 8 commits.
+Added a shared `createFactorySession` builder, migrated the four lifecycle clone families, and (on operator steer) folded `create-subagent-session-extension-tools.test.ts` into `create-subagent-session.test.ts`, deleting the file.
+Package test duplication dropped 669 → 512 lines (under the 600 goal); test count 1005 → 1010 (+5 `createFactorySession` self-tests); test files 64 → 63.
+Pre-completion reviewer: PASS.
+
+### Observations
+
+- Plan premise was wrong on one point: extracting `createFactorySession` alone did **not** collapse the create-subagent-session families — the dominant clone was the arrange-act invoke block, not the builder.
+  I first extracted a `runCreate`/`runCreateWith` act-helper to hit the metric, then the operator flagged it: mixing arrange + act hides the system under test, and arranges should be grouped by `describe`.
+  Reworked to AAA — describe-scoped `beforeEach` for arrange, `createSubagentSession(...)` act kept explicit per test.
+- The operator relaxed the roadmap's "lifecycle families ≤ 1" Outcome.
+  Two families remain by design (the repeated act with test-specific arrange); documented as intentional in `architecture.md` Step 7.
+  Lesson recorded: a clone-count metric is a weak signal for *test* code — AAA structure beats it, and chasing the metric produced the wrong abstraction before it was caught.
+- `programTurns(session, listeners, turns)` is a legitimate arrange helper for the turn-limit tests (turn count is the meaningful input, not a discriminator flag); removed the restated-boundary comments per `code-design` (names/args over comments).
+- Folding the extension-tools tests was safe because the recursion guard reads only the session mock's `getActiveToolNames`/`setActiveToolsByName`; the agent config and `type` don't affect those assertions (mocked `io.createSession` ignores `cfg.toolNames`).
+- Surfaced three overlapping session-mock builders (`createMockSession`, `createSubagentSessionStub`, `createFactorySession`); filed [#412] as a follow-up rather than expanding #378 scope.
+- Cross-step invariants verified intact: queued-agent "promise at spawn" ([#374]) test preserved through the `arrangeQueuedPair` extraction; zero external `.promise`/`.notification` writes in `test/lifecycle/`.
+
+## Stage: Final Retrospective (2026-06-15T23:45:00Z)
+
+### Session summary
+
+Shipped Phase 17 Step 7 across plan → TDD → ship in one continuous session: 11 `test:`/`docs:` commits, package test duplication 669 → 512 lines, test files 64 → 63, tests 1005 → 1010.
+The dominant arc was a metric-driven detour — an act-wrapping helper extracted to satisfy the roadmap's "families ≤ 1" target, caught by the operator and reworked into an AAA structure (describe-scoped arrange, visible act).
+CI passed, issue closed, no release (test/docs commits only); follow-up [#412] filed.
+
+### Observations
+
+#### What went well
+
+- The "no sacred cows" invitation → structured `ask_user` multi-select produced a real improvement: deleting the redundant `create-subagent-session-extension-tools.test.ts` entirely (#1) and filing [#412], rather than accepting the status quo.
+  Self-critique under explicit invitation surfaced a whole-file removal the plan had not considered.
+- Verification was incremental, not end-only: `pnpm run check` plus a per-file `vitest run` plus a `fallow dupes` re-measurement ran between every TDD step, so each consolidation's effect on the clone count was visible immediately.
+- Cross-step invariant discipline held: the queued-agent "promise at spawn" ([#374]) test survived the `arrangeQueuedPair` extraction, and the grep for external `.promise`/`.notification` writes stayed at zero.
+- The release-timing gate correctly fired on the phased roadmap (Phase 17 Step 7 of 9) and surfaced the batch-vs-now choice instead of releasing silently.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — extracted a `runCreate`/`runCreateWith` act-helper that bundled arrange + the `createSubagentSession(...)` act, hiding the system under test, purely to drive the clone count to the roadmap's "families ≤ 1" target.
+  User-caught.
+  Impact: one commit (`96acc6c7`) committed then undone via `git reset --soft HEAD~1` and reworked into the AAA structure (`14375b07`); ~1 commit of rework, caught before ship.
+- `missing-context` — the plan asserted `createFactorySession` was "the larger half of each clone" without decomposing the clone; the post-Step-3 `fallow dupes` measurement showed the arrange-act invoke block was the dominant half, which is what drove the wrong-abstraction detour.
+  Impact: a wrong planning premise that fed the rework above.
+  A `fallow dupes --trace <file:line>` per-line decomposition during planning would have shown the split.
+- `other` (tool misuse) — first invoked `set_session_name` as a shell command (`command not found`), then self-corrected to the tool call.
+  Impact: one wasted call, no rework.
+
+#### What caused friction (user side)
+
+- The operator's redirect on arrange/act mixing landed after the act-helper was already committed.
+  The natural self-checkpoint was earlier: when the Step-3 measurement contradicted the plan's "builder is the larger half" premise, that contradiction was itself a deviation worth surfacing via `ask_user` ("wrap the act to hit the metric, or accept the residual for better structure?") rather than pushing forward to the helper.
+  Framed as opportunity: treat a plan's quantitative premise proving wrong as a stop-and-ask trigger, not a cue to escalate the abstraction.
+
+### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`) on a judgment-heavy review task; appropriate match, no mismatch.
+- **Escalation-delay tracking** — no rabbit-hole: the wrong-abstraction was a single committed approach redirected by the operator, not a repeated-error loop, so no 5+ consecutive same-error sequence.
+- **Unused-tool detection** — `fallow dupes --trace <file:line>` was available and would have decomposed the clone into builder-vs-act portions during planning; it was not used, and its absence is what let the wrong premise stand.
+- **Feedback-loop gap analysis** — no gap; checks ran incrementally after each step.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` (§ Test organization) — added a rule to group shared arrange in a describe-scoped `beforeEach`, keep the act explicit, and not wrap the system-under-test call to eliminate a duplication-metric clone.
+2. `.pi/prompts/tdd-plan.md` — sharpened the deviation rule: a quantitative target (LOC, clone count, complexity) that does not fall out as predicted is a stop-and-ask deviation, re-decided via `ask_user` rather than forcing the number.
+
+[#374]: https://github.com/gotgenes/pi-packages/issues/374
+[#412]: https://github.com/gotgenes/pi-packages/issues/412

package/docs/retro/0379-consolidate-ui-tools-test-fixtures.md

@@ -0,0 +1,52 @@
+---
+issue: 379
+issue_title: "Consolidate UI and tools test fixtures"
+---
+
+# Retro: #379 — Consolidate UI and tools test fixtures
+
+## Stage: Planning (2026-06-16T00:00:00Z)
+
+### Session summary
+
+Produced a 9-step lift-and-shift plan for Phase 17 Step 8 — consolidating the non-lifecycle test clone families.
+Measured the live baseline (`fallow dupes -r packages/pi-subagents`: 32 clone groups / 512 lines / 2.49%, seven families) and characterized each family by reading all seven test files, classifying each as genuine cross-file duplication (one) versus intra-file (six).
+
+### Observations
+
+- The only genuine cross-file duplication is the `ResolvedSpawnConfig` builder shared by `foreground-runner.test.ts` and `background-spawner.test.ts` (`dup:80ee2004`) — the one promotion to `test/helpers/` (`make-spawn-config.ts`).
+  Everything else fallow scores same-file, so it stays file-local or moves into a describe-scoped `beforeEach`, per Step 7's ([#378]) discipline.
+- The plan's central constraint is Step 7's hard-won lesson: never wrap the system-under-test **act** in a helper to chase a duplication metric.
+  Every extracted helper returns a value (`createResolvedSpawnConfig`, `disabledConfig`, `exploreConfig`, `createManagerStub`, `spawnAndWaitRegistering`) or seeds `beforeEach`; the acts stay inline.
+  Added an "Invariants at risk" grep check to enforce this at review.
+- Scope was genuinely ambiguous and resolved via `ask_user`: the issue body names six files, but fallow reports a seventh non-lifecycle family in `test/service/service-adapter.test.ts` (four near-identical `SubagentManagerLike` stubs).
+  Operator chose to include service-adapter (seven files total) and to **not** bind a numeric group target — acceptance is "each named family consolidated, resulting fallow numbers reported."
+  My `ask_user` prompt incorrectly claimed the architecture roadmap's Step 8 `Targets` lists service-adapter; it does not (it lists the six issue-body files).
+  The plan corrects this and notes service-adapter was added in planning.
+- The roadmap's stated Step 8 outcome ("clone groups 44 → ≤ 25; overall duplication ≤ 0.6%") predates Steps 1–7 and does not match the current fallow metric (2.49%); flagged as an Open Question rather than treated as binding.
+- Non-Goals call out the two residual lifecycle families (Step 7 left them as the visible act), the 11-line production clone inside `src/ui/agent-config-editor.ts` (test-only issue), and the three overlapping session-mock builders ([#412]).
+- `ResolvedSpawnConfig` is deeply nested (`identity`/`execution`/`presentation` with mirrored scalars).
+  Designed the shared builder to take **flat** options and assemble the nested structure internally — sidesteps the `Partial<T>` deep-merge trap and encapsulates the mirroring (`agentInvocation.runInBackground`, `presentation.detailBase`) the hand-built copies duplicate.
+
+## Stage: Implementation — TDD (2026-06-16T13:10:00Z)
+
+### Session summary
+
+Executed all 9 plan steps as green-to-green lift-and-shift refactors (no red phase — the existing assertions were the spec), one commit per step plus the docs commit.
+Promoted the shared `createResolvedSpawnConfig` builder to `test/helpers/` (+5 self-tests) and consolidated the six remaining families with file-local value-returning builders / `beforeEach` setup.
+Test count 1010 → 1015; test files 63 → 64; clone groups 32 → 24; package test duplication 512 → 355 lines (2.49% → 1.73%).
+
+### Observations
+
+- The `agent-config-editor.test.ts` family did not collapse as the plan loosely estimated ("4 → ideally 2"): it stayed at 4 groups / 28 lines.
+  The `disabledConfig` helper removed only the small `enabled: false` arrange; the residual clones are the repeated `await editor.showAgentDetail(...)` **act** plus its `setupDetail` arrange and `ui.select.mock.calls` menu assertion — left inline because wrapping the system-under-test is the wrong abstraction (Step 7 lesson).
+  No `ask_user` was needed: acceptance was "consolidate and measure" (no binding numeric target), and the only way to force the number would violate the plan's stated discipline.
+- `service-adapter.test.ts` had four near-identical `SubagentManagerLike` stub factories with diverging defaults (`hasRunning` true vs false, varying `spawn` returns).
+  Consolidated into one file-local `createManagerStub()` with **unannotated** return (typed `vi.fn<SubagentManagerLike[...]>()` stubs) so callers retain `Mock<...>` methods — per the testing-skill rule that annotating the return with the production interface, or spreading `Partial<Interface>` overrides, erases mock methods.
+  Dropped the overrides parameter entirely; per-test behavior is configured on the returned object (`mgr.getRecord.mockImplementation(...)`, `mgr.hasRunning.mockReturnValue(true)`).
+  Used `sed` to swap the `defaultManager()` / `createTestManager()` call sites after deleting the factory definitions.
+- `ui-observer` update-counting tests moved from closure `let updateCount` counters to `vi.fn()` onUpdate with `toHaveBeenCalledTimes` — removes the repeated scaffolding without hiding the `session.emit` act.
+- Pre-completion reviewer: WARN — sole finding was this missing TDD retro entry (now written); all deterministic checks PASS, cross-step invariant ("don't wrap the act") verified upheld, 6 Mermaid blocks validated, dead-code clean.
+
+[#378]: https://github.com/gotgenes/pi-packages/issues/378
+[#412]: https://github.com/gotgenes/pi-packages/issues/412