@gotgenes/pi-subagents 13.1.0 → 13.2.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [13.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.1.0...pi-subagents-v13.2.0) (2026-05-30)
+
+
+### Features
+
+* add delegate methods to SubagentSession for session encapsulation ([#277](https://github.com/gotgenes/pi-packages/issues/277)) ([038e906](https://github.com/gotgenes/pi-packages/commit/038e906312b00d18ff617caf68bce980db70a243))
+* add session-encapsulation methods to Agent ([#277](https://github.com/gotgenes/pi-packages/issues/277)) ([03b4382](https://github.com/gotgenes/pi-packages/commit/03b43820aa7bd4ab4f9a4cd15ae09a1217c317d4))
+
 ## [13.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.0.0...pi-subagents-v13.1.0) (2026-05-30)
 
 

package/docs/architecture/architecture.md

@@ -123,8 +123,12 @@ classDiagram
         +run()
         +resume(prompt, signal)
         +abort(): boolean
-        +queueSteer(message)
-        +flushPendingSteers()
+        +steer(message): Promise<boolean>
+        +isSessionReady(): boolean
+        +getConversation(): string | undefined
+        +getContextPercent(): number | null
+        +subscribeToUpdates(fn): unsub | undefined
+        +messages: readonly unknown[]
         +completeRun(result)
         +failRun(err)
         +disposeSession()
@@ -330,7 +334,7 @@ Record statistics (tool uses, token usage, compaction counts) are updated by `re
 UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
 Neither observer wraps or forwards the other — both subscribe directly to the session.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes directly to `AgentSession` objects.
+The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Agent.subscribeToUpdates()` and reads messages via `Agent.messages` — no direct `AgentSession` reference (#277).
 
 ## Cross-extension architecture
 
@@ -589,21 +593,21 @@ The prior clone group between `agent-runner.ts` and `message-formatters.ts` was
 The 20-line clone group between `agent-config-editor.ts` and `agent-creation-wizard.ts` was resolved in #217 — extracted into `ui/agent-file-writer.ts` (`writeAgentFile`).
 One 11-line internal clone group remains within `agent-config-editor.ts` (lines 135–145 / 173–183).
 
-### Session encapsulation debt (Law of Demeter) — [#277]
-
-Discovered while planning [#265].
-Consumers reach the raw SDK `AgentSession` through the `Agent.session` getter (`this.subagentSession?.session`) and operate on it directly, instead of telling the owning agent what they want.
-These are Law of Demeter / Tell-Don't-Ask reach-throughs; the fix is intent-revealing methods on the owning object (`Subagent` / `SubagentSession`, introduced by [#265]).
-
-| Reach-through                         | Sites                                               | Missing method                                   |
-| ------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
-| Steer (buffer-or-deliver, duplicated) | `service-adapter.ts` (~L93), `steer-tool.ts` (~L43) | `Subagent.steer(message)`                        |
-| Conversation viewing                  | `get-result-tool.ts:84`, `agent-menu.ts:255`        | `Subagent.getConversation()`                     |
-| Session-readiness guard               | `agent-tool.ts:111`, `agent-manager.ts:203`         | `Subagent.isSessionReady()`                      |
-| Session disposal                      | `agent-manager.ts:235,309`                          | `SubagentSession.dispose()` — resolved by [#265] |
-
-[#265] introduces `SubagentSession` and routes the run / resume / dispose path (and steering during a run) through it; the consumer-facing reach-throughs above are deferred to [#277].
-The steer buffer-or-deliver decision is duplicated across two call sites — two callers performing the same reach-through plus the same decision is the signal for the missing method.
+### Session encapsulation debt (Law of Demeter) — resolved by [#277] ✔️
+
+All consumer reach-throughs to the raw SDK `AgentSession` via `Agent.session` have been eliminated.
+`Agent.session` is removed; `SubagentSession.session` is marked `@internal` (lifecycle use only).
+The intent-revealing replacements added by [#277]:
+
+| Reach-through                            | Sites                                                                              | Replacement                                      |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Steer buffer-or-deliver (was duplicated) | `service-adapter.ts`, `steer-tool.ts`                                              | `Agent.steer(message)`                           |
+| Conversation viewing                     | `get-result-tool.ts`, `agent-menu.ts`, `conversation-viewer.ts`                    | `Agent.getConversation()` / `Agent.messages`     |
+| Session-readiness guard                  | `agent-tool.ts`, `agent-manager.ts`                                                | `Agent.isSessionReady()`                         |
+| Context-window stats                     | `steer-tool.ts`, `get-result-tool.ts`, `notification.ts`, `conversation-viewer.ts` | `Agent.getContextPercent()`                      |
+| Live updates (subscription)              | `conversation-viewer.ts`                                                           | `Agent.subscribeToUpdates(fn)`                   |
+| Observer callback session param          | `background-spawner.ts`, `foreground-runner.ts`                                    | `agent.subagentSession` (narrowed callback)      |
+| Session disposal                         | `agent-manager.ts`                                                                 | `SubagentSession.dispose()` — resolved by [#265] |
 
 ### Proposed bag decompositions
 

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,39 @@
+---
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "13.1.0",
+  "version": "13.2.0",
   "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>` : "";
 

package/src/service/service-adapter.ts

@@ -90,13 +90,7 @@ export class SubagentsServiceAdapter implements SubagentsService {
     if (record?.status !== "running") {
       return false;
     }
-    const session = record.session;
-    if (!session) {
-      // Session not ready yet — buffer on the agent for delivery once initialized
-      record.queueSteer(message);
-      return true;
-    }
-    await session.steer(message);
+    await record.steer(message);
     return true;
   }
 

package/src/tools/agent-tool.ts

@@ -108,7 +108,7 @@ export class AgentTool {
 					`Agent not found: "${params.resume}". It may have been cleaned up.`,
 				);
 			}
-			if (!existing.session) {
+			if (!existing.isSessionReady()) {
 				return textResult(
 					`Agent "${params.resume}" has no active session to resume.`,
 				);

package/src/tools/background-spawner.ts

@@ -53,9 +53,10 @@ export function spawnBackground(
       isBackground: true,
       invocation: execution.agentInvocation,
       observer: {
-        onSessionCreated: (_agent, session) => {
-          bgState.setSession(session);
-          subscribeUIObserver(session, bgState);
+        onSessionCreated: (agent) => {
+          const sub = agent.subagentSession!;
+          bgState.setSession(sub);
+          subscribeUIObserver(sub, bgState);
         },
       },
     });

package/src/tools/foreground-runner.ts

@@ -108,10 +108,11 @@ export async function runForeground(
         signal,
         parentSession: params.parentSession,
         observer: {
-          onSessionCreated: (agent, session) => {
-            fgState.setSession(session);
+          onSessionCreated: (agent) => {
+            const sub = agent.subagentSession!;
+            fgState.setSession(sub);
             recordRef = agent;
-            unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+            unsubUI = subscribeUIObserver(sub, fgState, streamUpdate);
             fgId = agent.id;
             agentActivity.set(agent.id, fgState);
             widget.ensureTimer();

package/src/tools/get-result-tool.ts

@@ -1,8 +1,6 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import { getSessionContextPercent } from "#src/lifecycle/usage";
-import { getAgentConversation } from "#src/session/conversation";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import type { Agent } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";
@@ -53,7 +51,7 @@ export class GetResultTool {
 		const displayName = getDisplayName(record.type, this.registry);
 		const duration = formatDuration(record.startedAt, record.completedAt);
 		const tokens = formatLifetimeTokens(record);
-		const contextPercent = getSessionContextPercent(record.session);
+		const contextPercent = record.getContextPercent();
 		const statsParts = [`Tool uses: ${record.toolUses}`];
 		if (tokens) statsParts.push(tokens);
 		if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
@@ -80,11 +78,9 @@ export class GetResultTool {
 		}
 
 		// Verbose: include full conversation
-		if (params.verbose && record.session) {
-			const conversation = getAgentConversation(record.session);
-			if (conversation) {
-				output += `\n\n--- Agent Conversation ---\n${conversation}`;
-			}
+		const conversation = params.verbose ? record.getConversation() : undefined;
+		if (conversation) {
+			output += `\n\n--- Agent Conversation ---\n${conversation}`;
 		}
 
 		return textResult(output);

package/src/tools/steer-tool.ts

@@ -1,6 +1,5 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { getSessionContextPercent } from "#src/lifecycle/usage";
 import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
 import type { Agent } from "#src/types";
 
@@ -40,21 +39,16 @@ export class SteerTool {
 				`Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
 			);
 		}
-		const session = record.session;
-		if (!session) {
-			// Session not ready yet — buffer on the agent for delivery once initialized
-			record.queueSteer(params.message);
-			this.events.emit("subagents:steered", { id: record.id, message: params.message });
-			return textResult(
-				`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
-			);
-		}
-
 		try {
-			await session.steer(params.message);
+			const delivered = await record.steer(params.message);
 			this.events.emit("subagents:steered", { id: record.id, message: params.message });
+			if (!delivered) {
+				return textResult(
+					`Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+				);
+			}
 			const tokens = formatLifetimeTokens(record);
-			const contextPercent = getSessionContextPercent(session);
+			const contextPercent = record.getContextPercent();
 			const stateParts: string[] = [];
 			if (tokens) stateParts.push(tokens);
 			stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);

package/src/ui/agent-menu.ts

@@ -252,8 +252,7 @@ export class AgentsMenuHandler {
   }
 
   private async viewAgentConversation(ui: MenuUI, record: Agent): Promise<void> {
-    const session = record.session;
-    if (!session) {
+    if (!record.isSessionReady()) {
       ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,
         "info",
@@ -270,7 +269,6 @@ export class AgentsMenuHandler {
       (tui: any, theme: any, _keybindings: any, done: any) => {
         return new ConversationViewer({
           tui,
-          session,
           record,
           activity,
           theme,

package/src/ui/conversation-viewer.ts

@@ -5,10 +5,9 @@
  * Subscribes to session events for real-time streaming updates.
  */
 
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-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";
 import { buildInvocationTags, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "#src/ui/display";
@@ -24,7 +23,6 @@ export const VIEWPORT_HEIGHT_PCT = 70;
 
 export interface ConversationViewerOptions {
   tui: TUI;
-  session: AgentSession;
   record: Agent;
   activity: AgentActivityTracker | undefined;
   theme: Theme;
@@ -41,7 +39,6 @@ export class ConversationViewer implements Component {
   private closed = false;
 
   private tui: TUI;
-  private session: AgentSession;
   private record: Agent;
   private activity: AgentActivityTracker | undefined;
   private theme: Theme;
@@ -51,7 +48,6 @@ export class ConversationViewer implements Component {
 
   constructor({
     tui,
-    session,
     record,
     activity,
     theme,
@@ -60,14 +56,13 @@ export class ConversationViewer implements Component {
     wrapText,
   }: ConversationViewerOptions) {
     this.tui = tui;
-    this.session = session;
     this.record = record;
     this.activity = activity;
     this.theme = theme;
     this.done = done;
     this.registry = registry;
     this.wrapText = wrapText;
-    this.unsubscribe = session.subscribe(() => {
+    this.unsubscribe = record.subscribeToUpdates(() => {
       if (this.closed) return;
       this.tui.requestRender();
     });
@@ -142,7 +137,7 @@ export class ConversationViewer implements Component {
     if (toolUses > 0) headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`);
     const tokens = getLifetimeTotal(this.record.lifetimeUsage);
     if (tokens > 0) {
-      const percent = getSessionContextPercent(this.record.session);
+      const percent = this.record.getContextPercent();
       headerParts.push(formatSessionTokens(tokens, percent, th, this.record.compactionCount));
     }
 
@@ -220,7 +215,7 @@ export class ConversationViewer implements Component {
 
     const th = this.theme;
     const ctx = { theme: th, wrapText: this.wrapText };
-    const messages = this.session.messages;
+    const messages = this.record.messages;
 
     if (messages.length === 0) {
       return [th.fg("dim", "(waiting for first message...)")];
@@ -229,7 +224,7 @@ export class ConversationViewer implements Component {
     const lines: string[] = [];
     let needsSeparator = false;
     for (const msg of messages) {
-      const formatted = formatMessage(msg as unknown as { role: string; [key: string]: unknown }, width, ctx);
+      const formatted = formatMessage(msg as { role: string; [key: string]: unknown }, width, ctx);
       if (!formatted) continue;
       if (needsSeparator) lines.push(th.fg("dim", "───"));
       lines.push(...formatted);