@gotgenes/pi-subagents 13.1.0 → 13.2.1

package/docs/plans/0277-encapsulate-agent-session.md

@@ -0,0 +1,304 @@
+---
+issue: 277
+issue_title: "Encapsulate AgentSession behind SubagentSession; retire the remaining agent.session reach-throughs"
+---
+
+# Encapsulate AgentSession behind SubagentSession
+
+## Problem Statement
+
+Callers outside the `lifecycle/` domain reach through `Agent.session` (which returns the raw SDK `AgentSession` via `this.subagentSession?.session`) and operate on the session object directly.
+This violates Law of Demeter and Tell-Don't-Ask — the missing abstractions are intent-revealing methods on `Agent` and `SubagentSession` that delegate internally.
+
+Issue #265 introduced `SubagentSession` and routed the run/resume/dispose path through it.
+The remaining consumer-facing reach-throughs were deferred to this issue.
+
+## Goals
+
+- Add intent-revealing methods to `Agent` and `SubagentSession` that replace every raw `AgentSession` access outside `lifecycle/`.
+- Collapse the duplicated steer buffer-or-deliver logic into a single `Agent.steer()` method.
+- Narrow the `onSessionCreated` observer callback to stop delivering the raw `AgentSession` to spawners.
+- Remove the `Agent.session` getter.
+- After this change, no production module outside `lifecycle/` references the raw `AgentSession`.
+
+## Non-Goals
+
+- The `Agent` → `Subagent` class rename — independent of this issue, can land in either order.
+- Changing the public `SubagentsService` API surface in `service/service.ts` — it already uses `SubagentRecord` (no live session objects).
+- Refactoring the conversation viewer's rich-rendering internals — only its session reference changes.
+- Architecture doc updates for the file-layout listing — `SubagentSession` and `Agent` files are not being added, moved, or removed.
+
+## Background
+
+### Affected reach-through sites
+
+Every site reaches the raw `AgentSession` exposed by the `Agent.session` getter.
+
+| Reach-through                          | Production files                                                                                                           | Current pattern                                                                                               |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Steer buffer-or-deliver (duplicated)   | `service/service-adapter.ts:93`, `tools/steer-tool.ts:43`                                                                  | `record.session` → `session.steer()` or `record.queueSteer()`                                                 |
+| Context-percent stats                  | `tools/get-result-tool.ts:56`, `tools/steer-tool.ts:57`, `observation/notification.ts:49`, `ui/conversation-viewer.ts:145` | `getSessionContextPercent(record.session)`                                                                    |
+| Conversation viewing                   | `tools/get-result-tool.ts:83-84`, `ui/agent-menu.ts:255`, `ui/conversation-viewer.ts:63,223`                               | `getAgentConversation(record.session)` / `session.messages`                                                   |
+| Session-readiness guard                | `tools/agent-tool.ts:111`, `lifecycle/agent-manager.ts:205`                                                                | `!record.session` / `!agent?.session`                                                                         |
+| Observer callback delivers raw session | `tools/background-spawner.ts:56`, `tools/foreground-runner.ts:111`                                                         | `onSessionCreated(_agent, session)` → `tracker.setSession(session)` + `subscribeUIObserver(session, tracker)` |
+| Activity-tracker session stats         | `ui/widget-renderer.ts:106`                                                                                                | `activity?.session` → `getSessionContextPercent(activity.session)` (via `AgentActivityTracker.session`)       |
+
+### Existing delegate methods
+
+`SubagentSession` already has `steer(message)`, `runTurnLoop()`, `resumeTurnLoop()`, and `dispose()`.
+The `session` getter is marked "retired by #277" in its JSDoc.
+
+`subscribeAgentObserver` in `observation/record-observer.ts` already accepts `SubscribableSession` (not `AgentSession`), so it can accept `SubagentSession` directly once `SubagentSession` implements the `subscribe()` delegate.
+
+### Public API surface
+
+The public API (`SubagentsService` + `SubagentRecord` in `service/service.ts`) does not expose `Agent` or `AgentSession`.
+Removing `Agent.session` is not a breaking change for cross-extension consumers.
+
+## Design Overview
+
+### New delegate methods on `SubagentSession`
+
+```typescript
+// Delegates to getAgentConversation(this._session)
+getConversation(): string
+
+// Delegates to getSessionContextPercent(this._session)
+getContextPercent(): number | null
+
+// Delegates to this._session.subscribe(fn) — satisfies SubscribableSession
+subscribe(fn: (event: AgentSessionEvent) => void): () => void
+
+// Delegates to this._session.getSessionStats() — satisfies SessionLike
+getSessionStats(): SessionStatsLike
+
+// Delegates to this._session.messages
+get messages(): readonly unknown[]
+```
+
+With `subscribe()` and `getSessionStats()`, `SubagentSession` structurally satisfies both `SubscribableSession` and `SessionLike`.
+This lets spawners pass a `SubagentSession` directly to `subscribeUIObserver()` and `tracker.setSession()` without exposing the raw `AgentSession`.
+
+### New intent-revealing methods on `Agent`
+
+```typescript
+// Buffer-or-deliver: returns true if delivered, false if buffered
+async steer(message: string): Promise<boolean>
+
+// Returns true when a SubagentSession is available
+isSessionReady(): boolean
+
+// Delegates to SubagentSession.getConversation(), returns undefined if no session
+getConversation(): string | undefined
+
+// Delegates to SubagentSession.getContextPercent(), returns null if no session
+getContextPercent(): number | null
+
+// Delegates to SubagentSession.subscribe() for conversation-viewer live updates
+subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined
+
+// Delegates to SubagentSession.messages for conversation-viewer rendering
+get messages(): readonly unknown[]
+```
+
+The `steer()` method replaces the duplicated buffer-or-deliver logic:
+
+```typescript
+async steer(message: string): Promise<boolean> {
+  if (!this.subagentSession) {
+    this.queueSteer(message);
+    return false;
+  }
+  await this.subagentSession.steer(message);
+  return true;
+}
+```
+
+### Observer callback narrowing
+
+`AgentLifecycleObserver.onSessionCreated` changes from `(agent: Agent, session: AgentSession)` to `(agent: Agent)`.
+Spawners access `agent.subagentSession!` (already public) which satisfies `SubscribableSession & SessionLike`:
+
+```typescript
+// tools/background-spawner.ts — after
+onSessionCreated: (agent) => {
+  const sub = agent.subagentSession!;
+  bgState.setSession(sub);         // SubagentSession satisfies SessionLike
+  subscribeUIObserver(sub, bgState); // SubagentSession satisfies SubscribableSession
+},
+```
+
+### Internal lifecycle wiring
+
+`Agent.run()` already passes the session to `subscribeAgentObserver()`, which accepts `SubscribableSession`.
+After the change, it passes `this.subagentSession` directly instead of `this.subagentSession.session`:
+
+```typescript
+// lifecycle/agent.ts — Agent.run(), after
+this.attachObserver(subscribeAgentObserver(this.subagentSession, this, { ... }));
+this.observer?.onSessionCreated?.(this);
+```
+
+### Removals
+
+- `Agent.session` getter — removed entirely.
+- `SubagentSession.session` getter — marked `@internal`, kept for lifecycle-internal uses (the `getLastAssistantText()` private helper reads `this._session.messages`).
+- `Agent.queueSteer()` — becomes private (called only from `Agent.steer()` and `Agent.flushPendingSteers()`).
+- `Agent.flushPendingSteers()` — becomes private (called only from `Agent.run()`).
+
+## Module-Level Changes
+
+### `src/lifecycle/subagent-session.ts`
+
+- Add `getConversation()`, `getContextPercent()`, `subscribe()`, `getSessionStats()`, `messages` getter.
+- Import `getAgentConversation` from `#src/session/conversation` and `getSessionContextPercent`, `SessionStatsLike` from `#src/lifecycle/usage`.
+- Mark the `session` getter with `@internal` JSDoc.
+
+### `src/lifecycle/agent.ts`
+
+- Add `steer()`, `isSessionReady()`, `getConversation()`, `getContextPercent()`, `subscribeToUpdates()`, `messages` getter.
+- Remove the `session` getter.
+- Make `queueSteer()` and `flushPendingSteers()` private.
+- In `run()`: pass `this.subagentSession` (not `this.subagentSession.session`) to `subscribeAgentObserver()` and fire `onSessionCreated(this)` without the session param.
+- In `resume()`: pass `subagentSession` (not `subagentSession.session`) to `subscribeAgentObserver()`.
+- Remove the `AgentSession` import.
+- Update `AgentLifecycleObserver.onSessionCreated` to `(agent: Agent)` — no session param.
+
+### `src/service/service-adapter.ts`
+
+- Replace the 6-line steer reach-through with `await record.steer(message)`.
+- Remove the `!session` guard — `Agent.steer()` owns it.
+
+### `src/tools/steer-tool.ts`
+
+- Replace the buffer-or-deliver dance with `const delivered = await record.steer(message)`.
+- Use `record.getContextPercent()` instead of `getSessionContextPercent(session)`.
+- Remove the `getSessionContextPercent` import.
+
+### `src/tools/get-result-tool.ts`
+
+- Use `record.getContextPercent()` instead of `getSessionContextPercent(record.session)`.
+- Use `record.getConversation()` instead of `getAgentConversation(record.session)`.
+- Remove the `getSessionContextPercent` and `getAgentConversation` imports.
+
+### `src/tools/agent-tool.ts`
+
+- Use `existing.isSessionReady()` instead of `!existing.session`.
+
+### `src/lifecycle/agent-manager.ts`
+
+- Use `agent.isSessionReady()` instead of `agent?.session`.
+- Update the `onSessionCreated` relay to `(agent) => options.observer!.onSessionCreated!(agent)` — no session param.
+
+### `src/observation/notification.ts`
+
+- Use `record.getContextPercent()` instead of `getSessionContextPercent(record.session)`.
+- Remove the `getSessionContextPercent` import.
+
+### `src/ui/conversation-viewer.ts`
+
+- Remove `session: AgentSession` from `ConversationViewerOptions`.
+- Remove the `private session: AgentSession` field.
+- Use `this.record.subscribeToUpdates(() => ...)` instead of `session.subscribe(...)`.
+- Use `this.record.messages` instead of `this.session.messages`.
+- Use `this.record.getContextPercent()` instead of `getSessionContextPercent(this.record.session)`.
+- Remove the `AgentSession` and `getSessionContextPercent` imports.
+
+### `src/ui/agent-menu.ts`
+
+- Use `record.isSessionReady()` instead of `record.session` check.
+- Remove the `session` variable and stop passing it to `ConversationViewer`.
+
+### `src/tools/background-spawner.ts`
+
+- Update `onSessionCreated` callback: `(agent) => { const sub = agent.subagentSession!; ... }`.
+- Pass `sub` instead of `session` to `bgState.setSession()` and `subscribeUIObserver()`.
+
+### `src/tools/foreground-runner.ts`
+
+- Same pattern as `background-spawner.ts`.
+
+### `test/helpers/mock-session.ts`
+
+- Update `createSubagentSessionStub` to include the new delegate methods (`getConversation`, `getContextPercent`, `subscribe`, `getSessionStats`, `messages`).
+- The stub's `subscribe` can delegate to the underlying mock session's `subscribe`.
+
+### Test files requiring updates
+
+- `test/lifecycle/subagent-session.test.ts` — add tests for new delegate methods.
+- `test/lifecycle/agent.test.ts` — add tests for `steer()`, `isSessionReady()`, `getConversation()`, `getContextPercent()`; update `queueSteer` and `flushPendingSteers` tests (now private, tested through `steer()`); update `session` getter tests to `isSessionReady()`.
+- `test/service/service-adapter.test.ts` — update steer tests (no more session reach-through).
+- `test/tools/steer-tool.test.ts` — update to use `Agent.steer()` semantics.
+- `test/tools/get-result-tool.test.ts` — update context-percent and conversation assertions.
+- `test/tools/agent-tool.test.ts` — update resume guard to use `isSessionReady()`.
+- `test/tools/background-spawner.test.ts` — update `onSessionCreated` callback assertions.
+- `test/tools/foreground-runner.test.ts` — update `onSessionCreated` callback assertions.
+- `test/observation/notification.test.ts` — update context-percent assertions.
+- `test/conversation-viewer.test.ts` — remove `session` from viewer options, update to use `record` methods.
+- `test/ui/agent-menu.test.ts` — update session guard assertions.
+- `test/lifecycle/agent-manager.test.ts` — update resume guard + observer relay tests.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:** Direct testing of `SubagentSession.getConversation()`, `getContextPercent()`, `subscribe()`, `getSessionStats()`, `messages` — these were previously only testable by reaching through the raw session.
+   Direct testing of `Agent.steer()` buffer-or-deliver logic — previously scattered across consumer tests.
+2. **Existing tests that become simpler:** `steer-tool.test.ts` and `service-adapter.test.ts` no longer need to set up the session-present/session-absent dance — they test through `Agent.steer()`.
+   `get-result-tool.test.ts` no longer needs mock sessions for context-percent assertions.
+3. **Existing tests that stay as-is:** `SubagentSession.runTurnLoop()` and `resumeTurnLoop()` tests — they exercise turn driving, which is unrelated.
+   `Agent.run()` integration tests — they verify the full lifecycle including observer wiring.
+
+## TDD Order
+
+1. Add delegate methods to `SubagentSession` (`getConversation`, `getContextPercent`, `subscribe`, `getSessionStats`, `messages`).
+   Update `createSubagentSessionStub` test helper to include the new methods.
+   Test: unit tests for each delegate method in `subagent-session.test.ts`.
+   Commit: `feat: add delegate methods to SubagentSession for session encapsulation (#277)`.
+
+2. Add intent-revealing methods to `Agent` (`steer`, `isSessionReady`, `getConversation`, `getContextPercent`, `subscribeToUpdates`, `messages`).
+   Test: unit tests for each method in `agent.test.ts`.
+   Commit: `feat: add session-encapsulation methods to Agent (#277)`.
+
+3. Migrate steer callers: replace the buffer-or-deliver reach-through in `service-adapter.ts` and `steer-tool.ts` with `record.steer()`.
+   Replace `getSessionContextPercent(session)` in `steer-tool.ts` with `record.getContextPercent()`.
+   Make `queueSteer()` and `flushPendingSteers()` private on `Agent`.
+   Update tests in `service-adapter.test.ts`, `steer-tool.test.ts`, `agent.test.ts` (the `queueSteer`/`flushPendingSteers` tests become tests for `Agent.steer()`; existing tests from step 2 may cover this).
+   Commit: `refactor: use Agent.steer for buffer-or-deliver (#277)`.
+
+4. Migrate context-percent, conversation, and readiness callers: `get-result-tool.ts`, `agent-tool.ts`, `agent-manager.ts`, `notification.ts`.
+   Update corresponding test files.
+   Commit: `refactor: replace session reach-throughs in tools and observation (#277)`.
+
+5. Refactor conversation viewer and agent-menu: remove `session: AgentSession` from `ConversationViewerOptions`, use `record` methods for subscribe/messages/contextPercent.
+   Update `conversation-viewer.test.ts` and `agent-menu.test.ts`.
+   Commit: `refactor: remove raw session from conversation viewer (#277)`.
+
+6. Narrow `onSessionCreated` callback: change `AgentLifecycleObserver.onSessionCreated` to `(agent: Agent)` — no session param.
+   Update `Agent.run()` and `Agent.resume()` to pass `SubagentSession` (not raw session) to `subscribeAgentObserver`.
+   Update spawners (`background-spawner.ts`, `foreground-runner.ts`) and `agent-manager.ts` relay.
+   Update corresponding test files.
+   Commit: `refactor: narrow onSessionCreated to hide raw AgentSession (#277)`.
+
+7. Remove `Agent.session` getter.
+   Mark `SubagentSession.session` getter as `@internal`.
+   Remove `AgentSession` import from `agent.ts`.
+   Update any remaining tests that reference `Agent.session` (use `agent.isSessionReady()` or `agent.subagentSession`).
+   Verify with `pnpm run check` and `pnpm -r run test`.
+   Commit: `refactor: remove Agent.session getter (#277)`.
+
+8. Update the architecture doc's "Session encapsulation debt" section to reflect completion.
+   Commit: `docs: mark session encapsulation debt resolved (#277)`.
+
+## Risks and Mitigations
+
+| Risk                                                                                          | Mitigation                                                                                                                                                                 |
+| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SubagentSession` might not structurally satisfy `SubscribableSession` or `SessionLike`       | Verify with `pnpm run check` after step 1 — the delegate methods must match the expected signatures exactly.                                                               |
+| Making `queueSteer`/`flushPendingSteers` private breaks tests                                 | Step 3 explicitly migrates those tests to exercise `Agent.steer()` instead.                                                                                                |
+| The conversation viewer's `messages` accessor returns `readonly unknown[]` which loses typing | The viewer already casts messages to `{ role: string; [key: string]: unknown }` — the cast is unchanged, and the viewer's rendering is unaffected.                         |
+| Narrowing `onSessionCreated` could break the `agent-manager.ts` relay's non-null assertion    | The relay checks `options.observer?.onSessionCreated` before wiring — the narrowed signature is structurally compatible; the only change is dropping the second parameter. |
+| Large number of test files to update                                                          | Steps 3–6 group migrations by concern (steer, stats/conversation/readiness, viewer, observer) so each commit is self-contained and reviewable.                             |
+
+## Open Questions
+
+- None — the issue's proposed methods are unambiguous and the acceptance criteria are clear.
+  The only design addition beyond the issue is narrowing `onSessionCreated` and adding `messages`/`subscribeToUpdates` for the conversation viewer, both of which are required to satisfy the "no production module outside lifecycle/ references AgentSession" acceptance criterion.

package/docs/retro/0265-born-complete-subagent-session.md

@@ -56,3 +56,42 @@ Pre-completion reviewer: initial FAIL (MD060 table alignment in SKILL.md, auto-f
 - `print-mode.test.ts` now mocks `#src/lifecycle/create-subagent-session` (was `#src/lifecycle/agent-runner`); `index.ts` wraps the factory as `(params) => createSubagentSession(params, deps)`, so the module mock still intercepts it.
 - fallow stayed clean throughout — the transient duplication of IO interfaces + turn-loop helpers between `agent-runner.ts` and the new modules (steps 3–5) was removed in step 6 before the pre-completion gate ran.
 - Reviewer's two minor non-blocking notes: SKILL.md Session-domain count now lists `conversation.ts` but still omits the pre-existing `content-items.ts` (drift predates this issue); `create-subagent-session.ts` keeps an accurate "old runner's runAgent()" provenance comment.
+
+## Stage: Final Retrospective (2026-05-30T13:37:00Z)
+
+### Session summary
+
+Shipped issue #265 (`pi-subagents-v13.1.0`) and ran the retrospective across all three stages (planning, TDD implementation, ship).
+The implementation landed cleanly in 7 TDD commits + 1 docs commit; test count 951 → 960.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift strategy (new modules alongside old, swap consumers, delete old) kept every intermediate commit compiling and the suite green — zero broken-baseline moments across 7 steps.
+- The `createSubagentSessionStub` pattern (steer/dispose delegate to the wrapped `MockSession`) let 6 tool/service test files migrate with a one-line change each, preserving all existing session-spy assertions.
+- Verification ran incrementally: `pnpm vitest run <file>` after every Red/Green, `pnpm run check` after every interface change, and `pnpm -r run test` (full cross-package) after step 6's deletion to confirm the permission system (1504 tests) was unaffected.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — The plan's step-5 file list omitted 6 tool/service test files (`steer-tool`, `agent-tool`, `background-spawner`, `foreground-runner`, `get-result-tool`, `service-adapter`) that directly set `record.execution = { session, outputFile }`.
+   The existing planning rule ("grep all test files for every removed symbol") was present but was not applied to the renamed `.execution` property — only to removed type imports.
+   Impact: step 5 took ~2× expected time; each file was discovered reactively via `tsc --noEmit` errors.
+2. `rabbit-hole` — Step 6's `sed` invocation for import-path renames failed silently on macOS BSD `sed` because the `#` delimiter clashed with `#test/helpers/...` paths. 3 consecutive tool calls were spent diagnosing and retrying before switching to per-file `sed` with `@` delimiters.
+   Impact: added ~3 minutes of friction; the `edit` tool would have been safer for targeted, known-file replacements.
+3. `other` (autoformat race) — The `pi-autoformat` extension ran concurrently with `git commit` twice during the docs phase, causing `.git/index.lock` conflicts.
+   Recovery was mechanical (remove lock, retry) but required user intervention once.
+   Impact: one user prompt to retry; no rework.
+4. `other` (markdown table alignment) — Replacing short table cells with long module lists in SKILL.md broke MD060's compact-table rule.
+   The pre-completion reviewer caught it (initial FAIL); `rumdl fmt` auto-fixed it.
+   Impact: one amend + re-lint cycle; self-identified after reviewer report.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The user's only intervention was a retry prompt after the autoformat/git-lock race — a timing issue, not a judgment or context gap.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added rule about `??` swallowing explicit `undefined` in factory overrides (under "Vitest mock patterns").
+2. `packages/pi-subagents/docs/retro/0265-born-complete-subagent-session.md` — appended Final Retrospective stage entry.

package/docs/retro/0277-encapsulate-agent-session.md

@@ -0,0 +1,80 @@
+---
+issue: 277
+issue_title: "Encapsulate AgentSession behind SubagentSession; retire the remaining agent.session reach-throughs"
+---
+
+# Retro: #277 — Encapsulate AgentSession behind SubagentSession
+
+## Stage: Planning (2026-05-30T12:00:00Z)
+
+### Session summary
+
+Produced an 8-step TDD plan covering delegate methods on `SubagentSession`, intent-revealing methods on `Agent`, caller migration across tools/service/UI/observation, observer callback narrowing, and `Agent.session` getter removal.
+The plan extends the issue's three proposed methods with `getContextPercent()`, `subscribeToUpdates()`, and `messages` to fully satisfy the acceptance criterion that no production module outside `lifecycle/` references the raw `AgentSession`.
+
+### Observations
+
+- `subscribeAgentObserver` already accepts `SubscribableSession` (not `AgentSession`), so adding `subscribe()` to `SubagentSession` enables passing it directly — no `session` getter needed for observer wiring.
+- The `onSessionCreated` observer callback delivers raw `AgentSession` to spawners in `tools/`.
+  The plan narrows it to `(agent: Agent)` and has spawners use `agent.subagentSession!` which structurally satisfies both `SubscribableSession` and `SessionLike` via the new delegate methods.
+- The conversation viewer uses `session.messages` for rendering and `session.subscribe()` for live updates — both require delegate methods beyond the issue's three proposed methods.
+- `queueSteer()` and `flushPendingSteers()` become private after migration, which requires migrating existing tests that call them directly.
+- The public API surface (`SubagentsService` + `SubagentRecord`) is unaffected — `Agent` is internal.
+
+## Stage: Implementation — TDD (2026-05-30T15:10:00Z)
+
+### Session summary
+
+All 8 TDD steps completed in one session. 13 commits landed: 2 `feat:`, 5 `refactor:`, 2 `docs:`, 1 `style:`, plus the earlier plan and retro commits.
+Test count went from 960 → 973 (+13 net: +18 new tests, −5 removed tests for the retired `session` getter and `queueSteer`/`flushPendingSteers` private methods).
+
+### Observations
+
+- `subscribeAgentObserver` already accepted `SubscribableSession`, so `SubagentSession` (once it grew a `subscribe()` delegate) could be passed directly in `Agent.run()` and `Agent.resume()` — no cast needed.
+- Adding `messages` to `MockSession` interface was a minor unplanned step: the field existed at runtime (via `createMockSession`'s spread) but the interface didn't declare it, causing a type error when `createSubagentSessionStub` tried to forward it.
+- `onSessionCreated` tests in `foreground-runner.test.ts` called the callback with 2 args `(record, mockSess)`.
+  After narrowing, the first test case was missing a `subagentSession` setup; fixed by setting `record.subagentSession` before invoking the callback.
+- The `get-result-tool.test.ts` verbose conversation test needed updating: previously built a mock session with messages and passed it directly; now the stub's `getConversation` must return the expected text via `mockReturnValue`.
+- Pre-completion reviewer returned **WARN** for two stale `architecture.md` passages: (1) conversation-viewer description still said "subscribes directly to `AgentSession`"; (2) `Agent` classDiagram still listed `queueSteer`/`flushPendingSteers` as public and omitted the 6 new public members.
+  Both fixed in a `docs:` commit before closing.
+
+## Stage: Final Retrospective (2026-05-30T16:00:00Z)
+
+### Session summary
+
+Issue #277 shipped across three sessions (planning, TDD, ship) in a single day.
+All 8 TDD steps completed cleanly, 13 implementation commits landed, and `pi-subagents-v13.2.0` released.
+
+### Observations
+
+#### What went well
+
+- Planning correctly identified scope beyond the issue's three proposed methods: `getContextPercent()`, `subscribeToUpdates()`, and `messages` were needed to satisfy the "no production module outside `lifecycle/` references `AgentSession`" acceptance criterion.
+  This prevented mid-TDD design revisions.
+- The discovery that `subscribeAgentObserver` already accepted `SubscribableSession` meant adding `subscribe()` to `SubagentSession` was sufficient for observer wiring — no type cast or adapter needed.
+- Lift-and-shift execution was precise: new methods added first (steps 1-2), callers migrated by concern (steps 3-6), old getter removed last (step 7).
+  No step broke any other step's tests.
+- Pre-completion reviewer caught two stale `architecture.md` passages (classDiagram with removed public methods, conversation-viewer description) that the implementation steps missed.
+  Both fixed in a `docs:` commit before closing.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — `MockSession` interface lacked `messages`.
+   The field existed at runtime (via `createMockSession`'s spread + `Record<string, unknown>` return type) but the `MockSession` interface didn't declare it.
+   Adding `messages` to `createSubagentSessionStub` triggered a type error.
+   Impact: 2 extra edits to `mock-session.ts` (add field to interface, add to `base` object), no rework.
+2. `missing-context` — `get-result-tool.test.ts` conversation test relied on raw mock session messages.
+   After migrating to `record.getConversation()`, the stub's `getConversation` returned `""` by default.
+   The test needed `stub.getConversation.mockReturnValue("...")` instead.
+   Impact: 1 test update, caught immediately by `pnpm vitest run`.
+3. `missing-context` — `foreground-runner.test.ts` called `onSessionCreated(record, mockSess)` with 2 args.
+   After narrowing the callback to `(agent: Agent)`, the first test lacked `record.subagentSession` setup.
+   Impact: 2 test blocks updated, caught by `pnpm vitest run`.
+4. `missing-context` — First `get-result-tool.ts` edit left a double-nested `if (conversation)` block.
+   The multi-edit replaced the outer `if (params.verbose && record.session)` but preserved the inner guard, creating `if (conversation) { if (conversation) { ... } }`.
+   Impact: Self-caught on immediate read-back; fixed in the same commit, no rework.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's involvement was limited to the `/plan-issue`, `/tdd-plan`, `/ship-issue`, and `/retro` prompts — no mid-session corrections or redirections were needed.

package/package.json

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

package/src/lifecycle/agent-manager.ts

@@ -113,7 +113,7 @@ export class AgentManager {
         this.observer?.onAgentStarted(agent);
       },
       onSessionCreated: options.observer?.onSessionCreated
-        ? (agent, session) => options.observer!.onSessionCreated!(agent, session)
+        ? (agent) => options.observer!.onSessionCreated!(agent)
         : undefined,
       onRunFinished: (agent) => {
         if (options.isBackground) {
@@ -202,7 +202,7 @@ export class AgentManager {
     signal?: AbortSignal,
   ): Promise<Agent | undefined> {
     const agent = this.agents.get(id);
-    if (!agent?.session) return undefined;
+    if (!agent?.isSessionReady()) return undefined;
     await agent.resume(prompt, signal);
     return agent;
   }

package/src/lifecycle/agent.ts

@@ -19,7 +19,7 @@
  */
 
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
@@ -36,8 +36,8 @@ import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType,
 export interface AgentLifecycleObserver {
 	/** Fires when the agent transitions to running (inside run(), after markRunning). */
 	onStarted?(agent: Agent): void;
-	/** Fires once the session is created — delivers the session to external consumers. */
-	onSessionCreated?(agent: Agent, session: AgentSession): void;
+	/** Fires once the session is created — the agent's subagentSession is now available. */
+	onSessionCreated?(agent: Agent): void;
 	/** Fires once when the run completes or fails (for concurrency drain). */
 	onRunFinished?(agent: Agent): void;
 	/** Fires on compaction events during the run. */
@@ -154,16 +154,52 @@ export class Agent {
 	/** Number of steer messages waiting to be delivered. */
 	get pendingSteerCount(): number { return this._pendingSteers.length; }
 
-	/** The active agent session, or undefined before the session is created. */
-	get session(): AgentSession | undefined {
-		return this.subagentSession?.session;
-	}
-
 	/** Path to the agent's session JSONL file, or undefined if not yet available. */
 	get outputFile(): string | undefined {
 		return this.subagentSession?.outputFile;
 	}
 
+	/** Returns true when a SubagentSession is available (session is ready). */
+	isSessionReady(): boolean {
+		return this.subagentSession != null;
+	}
+
+	/**
+	 * Deliver or buffer a steer message.
+	 * Returns true when delivered immediately; false when buffered for later delivery.
+	 */
+	async steer(message: string): Promise<boolean> {
+		if (!this.subagentSession) {
+			this.queueSteer(message);
+			return false;
+		}
+		await this.subagentSession.steer(message);
+		return true;
+	}
+
+	/** Return the session conversation as formatted text, or undefined if no session. */
+	getConversation(): string | undefined {
+		return this.subagentSession?.getConversation();
+	}
+
+	/** Return the session context window utilization (0-100), or null if unavailable. */
+	getContextPercent(): number | null {
+		return this.subagentSession?.getContextPercent() ?? null;
+	}
+
+	/**
+	 * Subscribe to session events for live updates (e.g., conversation viewer).
+	 * Returns an unsubscribe function, or undefined if no session is available.
+	 */
+	subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined {
+		return this.subagentSession?.subscribe(fn);
+	}
+
+	/** The session's message history, or an empty array if no session. */
+	get messages(): readonly unknown[] {
+		return this.subagentSession?.messages ?? [];
+	}
+
 	constructor(init: AgentInit) {
 		// Identity
 		this.id = init.id;
@@ -264,12 +300,11 @@ export class Agent {
 			return;
 		}
 
-		const session = this.subagentSession.session;
 		this.flushPendingSteers();
-		this.attachObserver(subscribeAgentObserver(session, this, {
+		this.attachObserver(subscribeAgentObserver(this.subagentSession, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
-		this.observer?.onSessionCreated?.(this, session);
+		this.observer?.onSessionCreated?.(this);
 
 		const runConfig = this._getRunConfig?.();
 		try {
@@ -301,7 +336,7 @@ export class Agent {
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeAgentObserver(subagentSession.session, this, {
+		this.attachObserver(subscribeAgentObserver(subagentSession, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
 
@@ -404,17 +439,17 @@ export class Agent {
 
 	/**
 	 * Buffer a steer message for delivery once the session is ready.
-	 * Called when steer is requested before onSessionCreated fires.
+	 * Called internally from steer() before the session is ready.
 	 */
-	queueSteer(message: string): void {
+	private queueSteer(message: string): void {
 		this._pendingSteers.push(message);
 	}
 
 	/**
 	 * Flush all buffered steer messages to the session and clear the buffer.
-	 * Called once the session is available, delegating to SubagentSession.steer.
+	 * Called once the session is available (inside run()).
 	 */
-	flushPendingSteers(): void {
+	private flushPendingSteers(): void {
 		for (const msg of this._pendingSteers) {
 			this.subagentSession?.steer(msg).catch(() => {});
 		}

package/src/lifecycle/subagent-session.ts

@@ -16,7 +16,9 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
+import { getSessionContextPercent, type SessionStatsLike } from "#src/lifecycle/usage";
 import { extractText } from "#src/session/context";
+import { getAgentConversation } from "#src/session/conversation";
 
 /** Outcome of one turn loop. */
 export interface TurnLoopResult {
@@ -61,7 +63,10 @@ export class SubagentSession {
     private readonly meta: SubagentSessionMeta,
   ) {}
 
-  /** Wrapped session — exposed for observer wiring + consumers; retired by #277. */
+  /**
+   * Wrapped session — for lifecycle-internal use only.
+   * @internal consumers outside lifecycle/ use the delegate methods below.
+   */
   get session(): AgentSession {
     return this._session;
   }
@@ -146,6 +151,31 @@ export class SubagentSession {
     await this._session.steer(message);
   }
 
+  /** Return the session's conversation as formatted text. */
+  getConversation(): string {
+    return getAgentConversation(this._session);
+  }
+
+  /** Return the session context window utilization (0-100), or null when unavailable. */
+  getContextPercent(): number | null {
+    return getSessionContextPercent(this._session);
+  }
+
+  /** Subscribe to session events. Satisfies `SubscribableSession`. */
+  subscribe(fn: (event: AgentSessionEvent) => void): () => void {
+    return this._session.subscribe(fn);
+  }
+
+  /** Return session token statistics. Satisfies `SessionLike`. */
+  getSessionStats(): SessionStatsLike {
+    return this._session.getSessionStats();
+  }
+
+  /** The session's message history. */
+  get messages(): readonly unknown[] {
+    return this._session.messages as readonly unknown[];
+  }
+
   /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
   dispose(): void {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations

package/src/observation/notification.ts

@@ -1,5 +1,5 @@
 import { debugLog } from "#src/debug";
-import { getLifetimeTotal, getSessionContextPercent } from "#src/lifecycle/usage";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { Agent } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
@@ -46,7 +46,7 @@ export function formatTaskNotification(record: Agent, resultMaxLen: number): str
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.session);
+  const contextPercent = record.getContextPercent();
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";