@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0403-abort-subagents-on-interrupt.md

@@ -1,180 +0,0 @@
----
-issue: 403
-issue_title: "Pressing Escape does not stop subagent/background agent"
----
-
-# Abort subagents on parent interrupt (ESC)
-
-## Problem Statement
-
-A user reports that pressing Escape in the Pi terminal to cancel the current work does not stop a running subagent — the agent keeps going despite the cancel request.
-The reporter is a third party (`khalid244`); the operator confirmed the direction is to implement ESC-to-abort for both foreground and background subagents, aborting all running and queued background agents on a single ESC.
-
-The root cause splits cleanly by execution mode:
-
-1. Foreground subagents already receive the parent's abort signal through the tool boundary (`tool.execute(signal)` → `Subagent.wireSignal` → `abort()` → child `session.abort()`), so they should already stop on ESC.
-2. Background subagents are detached by design: `spawnBackground()` never forwards the parent signal, and `manager.abortAll()` runs only on `session_shutdown`.
-   There is no wiring from a parent interrupt to background-agent abort, so ESC does nothing to them.
-   This is the reproducible bug.
-
-## Goals
-
-- Pressing ESC (the parent agent-loop interrupt) aborts all running and queued background subagents.
-- Add a regression guard test proving a foreground subagent's child session is aborted when the parent signal fires.
-- Reuse the existing `manager.abortAll()` semantics (abort running, mark queued stopped, clear the limiter) so ESC stops every active subagent in one action.
-
-This is an intentional behavior change: background subagents that previously survived ESC will now stop.
-It is a bug fix (`fix:`), not a breaking change — no config key, default value, or output shape changes, and detached-survives-ESC was a limitation rather than a contract.
-
-## Non-Goals
-
-- Selective or interactive abort (choosing which agent to stop) — out of scope.
-- A dedicated `abortBackground()` that excludes foreground agents — `abortAll()` is reused; foreground agents are already aborted by their own signal wiring, so the overlap is redundant-but-harmless.
-- Changing background-agent detachment for any path other than the ESC interrupt (e.g., the tool still returns immediately on spawn).
-- Confirmation prompts or status messaging on abort.
-
-## Background
-
-Relevant modules and the verified runtime facts behind the design:
-
-- `src/tools/foreground-runner.ts` — `runForeground(..., signal, ...)` forwards the parent `signal` into `manager.spawnAndWait({ signal })`.
-- `src/lifecycle/subagent.ts` — `run()` calls `this.wireSignal(this.execution.signal, () => this.abort())`; `abort()` fires `abortController.abort()` and marks the record stopped.
-- `src/lifecycle/subagent-session.ts` — `runTurnLoop` calls `forwardAbortSignal(session, opts.signal)`, which calls `session.abort()` when the signal fires.
-- `src/tools/background-spawner.ts` — `spawnBackground()` omits `signal` entirely; background agents are detached.
-- `src/lifecycle/subagent-manager.ts` — `abortAll()` aborts running, marks queued stopped, and clears the limiter; currently called only from `src/handlers/lifecycle.ts` on shutdown.
-- `src/handlers/tool-start.ts`, `src/handlers/lifecycle.ts`, `src/handlers/index.ts` — the existing `handlers/` pattern: small classes with a narrow injected interface, registered in `index.ts`.
-
-Verified SDK facts (from the pinned peer deps under `node_modules/@earendil-works/`):
-
-- The interactive ESC handler calls `agent.abort()` while streaming (`pi-coding-agent` `interactive-mode.js`, `restoreQueuedMessagesToEditor({ abort: true })`).
-- `pi-agent-core` `agent.js`: each run creates a fresh `AbortController`; `agent.abort()` calls `activeRun.abortController.abort()`; on normal completion `finishRun()` discards the controller **without** aborting it.
-  Therefore the parent signal's `abort` event fires only on a real interrupt, never on normal turn completion — latching `abortAll()` to it will not spuriously kill background agents at turn end.
-- The signal passed to `tool.execute(...)` (`agent-loop.js` line ~419) is that same per-run signal.
-- Extensions read the live per-run parent signal via `ctx.signal` (`ExtensionContext.signal: AbortSignal | undefined`, undefined when idle).
-- `pi.on("turn_start", (event, ctx) => ...)` is a registered event whose handler receives `ExtensionContext`; `turn_start` fires once at the start of every turn while streaming, so its `ctx.signal` is always the current run's signal.
-
-AGENTS.md constraint: pi-subagents is a minimal core with dependency arrows pointing inward.
-The new handler depends only on a narrow manager interface; no consumer knowledge leaks into the manager.
-
-## Design Overview
-
-Add a small `InterruptHandler` that latches the current parent abort signal and, on abort, tells the manager to abort all subagents.
-Drive it from `turn_start` so the latch always tracks the live per-run signal — including across runs and turns that execute no tools.
-
-Why `turn_start` rather than `tool_execution_start`: a background agent can outlive the run that spawned it.
-If the user later interrupts a turn that ran no subagent tool, only a turn-level latch still holds that run's signal.
-`turn_start` fires every turn with the current `ctx.signal`, so the latch is always current.
-
-The latch dedups by reference: most turns reuse the same signal (no-op); a new run's signal triggers a detach-and-rewire.
-The `abort` listener is `{ once: true }`; on normal completion the run's `AbortController` is discarded and garbage-collected with its listener, and the next `turn_start` detaches the stale reference.
-
-### Manager interface (narrow, Tell-Don't-Ask)
-
-```typescript
-/** Narrow manager interface — only the method the interrupt handler calls. */
-export interface InterruptManager {
-  abortAll(): number;
-}
-
-/** Minimal context shape — only the field the handler reads. */
-interface InterruptCtx {
-  signal: AbortSignal | undefined;
-}
-```
-
-### Handler
-
-```typescript
-export class InterruptHandler {
-  private latched?: AbortSignal;
-  private detach?: () => void;
-
-  constructor(private readonly manager: InterruptManager) {}
-
-  handleTurnStart(ctx: InterruptCtx): void {
-    const signal = ctx.signal;
-    if (signal === this.latched) return;
-    this.detach?.();
-    this.detach = undefined;
-    this.latched = signal;
-    if (!signal) return;
-    const onAbort = (): void => {
-      this.manager.abortAll();
-    };
-    signal.addEventListener("abort", onAbort, { once: true });
-    this.detach = () => signal.removeEventListener("abort", onAbort);
-  }
-}
-```
-
-### Consumer call site (`index.ts`)
-
-```typescript
-const interrupt = new InterruptHandler(manager);
-pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx));
-```
-
-The handler talks to `manager` through a one-method interface, reads one field of `ctx`, and performs no chained access — no Law-of-Demeter or output-argument smells.
-The latch state (current signal, detach handle) is owned by the handler.
-
-### Edge cases
-
-- Same signal across consecutive turns → reference equality short-circuits; no listener churn.
-- `ctx.signal` undefined (idle, defensive) → detach the old listener and hold no signal.
-- Signal already aborted when latched → `{ once: true }` listener does not fire; the prior signal's listener already ran `abortAll()`, so no agent is missed.
-- ESC during a foreground subagent → the foreground agent is aborted twice (once via its own `wireSignal`, once via `abortAll`); `abort()` is guarded by status and `markStopped` is idempotent, so this is harmless.
-
-## Module-Level Changes
-
-- `src/handlers/interrupt.ts` (new) — `InterruptHandler` class and `InterruptManager` interface.
-- `src/handlers/index.ts` — add `export { InterruptHandler } from "#src/handlers/interrupt";`.
-- `src/index.ts` — instantiate `new InterruptHandler(manager)` and register `pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx))`.
-- `src/lifecycle/subagent-manager.ts` — no code change; `abortAll()` is reused.
-  Its `// fallow-ignore-next-line unused-class-member` comment stays (it is still reached only through narrow interfaces that fallow does not trace); the pre-completion `fallow dead-code` check will confirm.
-- `docs/architecture/architecture.md` — extend the `handlers/` directory listing (around line 354) with `interrupt.ts` (turn_start handler → abort all subagents on interrupt).
-  Check the same file for any handler file-count or complexity row that names the `handlers/` domain and update if present.
-
-No exports are removed or renamed.
-Grep confirms `.pi/skills/package-pi-subagents/SKILL.md` does not mention `abortAll`, interrupt, or ESC, so no skill update is required.
-
-## Test Impact Analysis
-
-This is a feature/fix addition, not an extraction, so no existing tests become redundant.
-
-1. New unit tests enabled — `InterruptHandler`: latches the current signal, fires `abortAll()` on abort, dedups the same signal reference, re-wires on a new signal, and handles an undefined signal.
-2. New integration guard — foreground abort: aborting the parent signal passed to `runTurnLoop` invokes the child `session.abort()`.
-   This pins the currently-untested foreground link in `forwardAbortSignal`.
-3. Existing tests stay as-is — `test/lifecycle/subagent.test.ts` (`wireSignal`, `abort`), `test/lifecycle/subagent-session.test.ts` (max-turns abort path), and `test/handlers/lifecycle.test.ts` (`abortAll` on shutdown) continue to exercise their layers unchanged.
-
-## TDD Order
-
-1. Foreground guard — `test/lifecycle/subagent-session.test.ts`.
-   Add a test: when the `signal` passed to `runTurnLoop` aborts while `session.prompt` is in flight, `session.abort()` is called.
-   Expected to pass immediately (proving the foreground chain already works); if the trace is wrong and it fails, fix `forwardAbortSignal` in `src/lifecycle/subagent-session.ts`.
-   Commit `test: guard foreground subagent abort on parent signal (#403)` (or `fix:` if a code fix is needed).
-2. Interrupt handler + wiring — `test/handlers/interrupt.test.ts` (new) → `src/handlers/interrupt.ts`, `src/handlers/index.ts`, `src/index.ts`.
-   Red: write the handler unit tests (latch, abort→abortAll, dedup, re-wire, undefined signal) against the not-yet-existing class.
-   Green: implement `InterruptHandler` + `InterruptManager`, export from the barrel, and register `pi.on("turn_start", ...)` in `index.ts`.
-   The handler, its test, and the composition-root wiring land together because the handler is inert without the registration.
-   Commit `fix: abort all subagents on parent interrupt (#403)`.
-3. Architecture doc — `docs/architecture/architecture.md`.
-   Add `interrupt.ts` to the `handlers/` directory listing and update any handler-domain count/row if present.
-   Commit `docs: note interrupt handler in subagents architecture (#403)`.
-
-## Risks and Mitigations
-
-- ESC now stops background agents the user might have wanted to keep running.
-  Mitigation: this is the operator's explicit choice (abort all running + queued); the behavior is documented in the plan and reflected in the `fix:` commit body.
-- Re-latching on every `turn_start` could add overhead.
-  Mitigation: the latch is a single reference comparison and short-circuits on the common same-signal case.
-- A `{ once: true }` listener lingers on a signal that completes normally.
-  Mitigation: the run's `AbortController` is discarded and GC'd with its listener; the next `turn_start` detaches the stale handle.
-- Non-interactive modes (print/rpc) may not emit `turn_start` the same way.
-  Mitigation: ESC interrupt is an interactive concern; the handler is a no-op when no signal is present.
-
-## Open Questions
-
-- Should a dedicated `abortBackground()` (excluding foreground) replace `abortAll()` here?
-  Deferred: `abortAll()` is simpler and foreground is already signal-aborted; revisit only if the redundant double-abort proves problematic.
-- Should ESC abort surface a confirmation or status message?
-  Deferred: out of scope for this fix.

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

@@ -1,146 +0,0 @@
----
-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

@@ -1,228 +0,0 @@
----
-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