@gotgenes/pi-subagents 13.0.0 → 13.2.0

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/0264-remove-extension-lifecycle-control.md

@@ -46,3 +46,44 @@ Test count went 1016 → 951 (−65): deleted `skill-loader.test.ts` and `safe-f
 - The `spawn-config.test.ts` `agentInvocation` snapshot carried a stale `isolation: undefined` leftover (from the #263 worktree eviction) that `toEqual` had been silently ignoring; removed it alongside `isolated: false` for a clean exact-match assertion.
 - `verify:public-types` confirmed the breaking `SpawnOptions.isolated` removal type-checks against an external consumer; no lockfile changes; `dist/` correctly gitignored after the type-bundle build.
 - Pre-completion reviewer: **PASS** — both acceptance criteria code-verified, all deterministic checks green, 6 Mermaid diagrams render, docs accurate, zero dead code.
+
+## Stage: Final Retrospective (2026-05-30T01:13:26Z)
+
+### Session summary
+
+Shipped #264 end-to-end across three stages (Planning → TDD → Ship) in one conversation: planned the four-cycle removal, implemented it as three `feat!:` commits plus docs, and released `pi-subagents-v13.0.0` via the release-please PR (#276).
+The run had zero rework and a PASS pre-completion review; test count moved 1016 → 951.
+
+### Observations
+
+#### What went well
+
+- The planning-stage `ask-user` gate caught a real scope trap before any code was written.
+  The issue named three fields (`isolated`, `extensions: false`, `noSkills`), but `noSkills` turned out to be the single mechanism behind **two** skill-restriction modes (skill-disable and `skills: string[]` preload).
+  Removing it while keeping `AgentConfig.skills` would have left a field that silently stops restricting — a mid-cycle-3 wall.
+  Catching it at planning time expanded the clean scope to four collapsing fields and produced a symmetric, reviewable plan.
+- The four-cycle split (`isolated` → `extensions` + unconditional guard → `skills`/`noSkills`/preload → docs) held with no cross-cycle dangling references, validating the lift-and-shift discipline for shared-interface removal.
+- Verification ran incrementally (`pnpm run check` + `pnpm run test` after every cycle), so each commit landed green; the only end-of-run surprise was a pre-commit `end-of-file-fixer` hook touching `custom-agents.ts` (handled with a re-add, no rework).
+
+#### What caused friction (agent side)
+
+- `other` (tooling) — BSD `sed` on macOS does not support `\|` alternation in basic regex; the first bulk fixture-deletion attempt silently matched nothing.
+  Impact: one wasted tool call, no rework; resolved by switching to `sed -E`.
+
+#### What caused friction (user side)
+
+- The opening sequencing question ("is there work that should precede this") was first read literally as a prerequisite check (#261/#262/#263), and the user had to rephrase to get at the within-issue sequencing point that surfaced the `noSkills`/`skills` coupling.
+  Opportunity, not criticism: offering both readings of an ambiguous "what comes first" question up front would have reached the valuable discovery one turn sooner.
+
+#### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`, 325s, 43 tool uses) on a judgment-heavy review task; appropriate assignment.
+  No Explore/Plan subagents were needed — planning-stage exploration was direct file reads and targeted greps, efficient for this removal's scope.
+- **Escalation-delay tracking** — no rabbit-holes; the `sed` issue resolved in one retry.
+- **Feedback-loop gap analysis** — no gap; `check`/`test`/`lint` ran after each cycle, with `fallow dead-code` and `verify:public-types` at the end.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0264-remove-extension-lifecycle-control.md`.
+2. Considered but **declined** (user: "too narrow") a removal-coupling detection rule for `.pi/prompts/plan-issue.md` — the heuristic that a field named for removal may be the mechanism behind a separate surviving feature.
+   No prompt or `AGENTS.md` changes were made this retro.

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

@@ -0,0 +1,97 @@
+---
+issue: 265
+issue_title: "Born-complete child execution; dissolve the runner"
+---
+
+# Retro: #265 — Born-complete child execution; dissolve the runner
+
+## Stage: Planning (2026-05-30T02:30:00Z)
+
+### Session summary
+
+Produced the implementation plan for dissolving the `agent-runner` and introducing a born-complete `SubagentSession`.
+Most of the session was a design dialogue that resolved naming, the turn-loop home, a discovered Law-of-Demeter cluster, and the workspace-ownership fork before any plan text was written.
+Plan committed as `0265-born-complete-subagent-session.md`; a side-quest filed #277 and added an architecture-doc breadcrumb for discovered debt.
+
+### Observations
+
+- Vocabulary was pinned down explicitly because "execution" is overloaded: granular execution = one turn loop (one `session.prompt()`, run or resume); the born-complete object spans the whole session lifetime (run + resumes).
+  The object is named `SubagentSession` (matches the existing `SubagentType` / `SubagentSessionDir` / `SubagentSessionRegistry` family; cohesive with the deferred `Agent` → `Subagent` rename).
+  Turn driving is `runTurnLoop` / `resumeTurnLoop`; resume is *not* an SDK `session.resume()` — it is `session.prompt()` again on the retained session.
+- The turn-loop home is **on `SubagentSession`** (methods), not inline on `Agent` and not a free function.
+  The user caught that `subagent.driveTurnLoop(subagentSession.session, …)` is a Law-of-Demeter reach-through; putting the behavior on the object that owns the `AgentSession` is both LoD-correct and more testable (satisfying the user's conditional "inline only if straightforward to test").
+- Workspace ownership locked to **Option A** (session-only `SubagentSession`; `Agent` keeps workspace prepare/dispose).
+  Decisive reasoning: the workspace and the session have genuinely different lifetimes (workspace dies at run-completion to fold its `resultAddendum` into the result; session survives to cleanup for resume + the new registry boundary), so they are different resources.
+  Option B would fuse them into one object needing two teardown methods, and would thread the `WorkspaceProvider` + prepare-context through the factory just to call `prepare()` — a parameter-relay smell the user flagged.
+  The factory takes a resolved `cwd` value (used directly), never the provider.
+- Worktrees are already out of the core (#263) — confirmed zero git code in `pi-subagents/src/` (only doc comments).
+  The A/B fork is purely about how the core sequences its abstract `WorkspaceProvider` seam; `@gotgenes/pi-subagents-worktrees` is untouched.
+- Registry semantics: moving `disposed` from run-completion to true session disposal makes resume executions registry-detected (closes the gap deferred from #261).
+  The permission system's subscription code does not change; only *when* `disposed` fires moves.
+  Edge case planned: `createSubagentSession` must dispose on a post-`session-created` failure to avoid a registry leak.
+- Discovered debt captured (the user's "it is in doing the work that we discover the work to be done"): filed #277 for the remaining `agent.session` reach-throughs (steer buffer-or-deliver duplicated across `steer-tool` + `service-adapter`, conversation viewing, resume-readiness guards) and added a "Session encapsulation debt (Law of Demeter)" subsection to `architecture.md` (commit `038a1283`).
+  `SubagentSession` exposes a `.session` accessor in #265 so observer wiring + consumers keep working; #277 retires those.
+- Two follow-ups deliberately deferred and noted in the plan's Non-Goals / Open Questions: the `Agent` → `Subagent` class rename (mechanical, ~19 files — separate issue) and resume-aware workspaces (a worktree's lifetime is one turn loop; worktree + resume is degenerate today).
+- The change is non-breaking (no `feat!:`): the dissolved types (`RunOptions`, `RunResult`, `AgentRunner`) are internal, so `public.d.ts` is unaffected.
+  TDD order uses lift-and-shift across 7 steps to keep each commit compiling; transient duplication of the turn-loop helpers/assembly exists between steps 3–5 and is deleted in step 6.
+
+## Stage: Implementation — TDD (2026-05-29T22:18:00Z)
+
+### Session summary
+
+Executed all 7 TDD steps from the plan via lift-and-shift, one commit per step, each leaving the suite green.
+Introduced `SubagentSession` (`runTurnLoop`/`resumeTurnLoop`/`steer`/`dispose`) and the `createSubagentSession()` assembly factory, swapped `Agent`/`AgentManager`/`index.ts` onto them, then deleted `agent-runner.ts` + `execution-state.ts` and the three runner test files.
+Package test count went 951 → 960 (net +9: new `subagent-session`/`create-subagent-session`/`turn-limits` suites added, the redundant runner suites deleted).
+Pre-completion reviewer: initial FAIL (MD060 table alignment in SKILL.md, auto-fixed by `rumdl fmt`), PASS on re-check after fix + stale doc cleanup.
+
+### Observations
+
+- The plan sketch's `TurnLoopOptions` listed only `maxTurns`/`graceTurns`/`signal`, but preserving the old `runAgent` precedence `per-call ?? agentMaxTurns ?? defaultMaxTurns` required threading `defaultMaxTurns` through `TurnLoopOptions` and storing `agentMaxTurns` + `parentContext` in `SubagentSession` meta (both are session-level facts known at creation).
+  This is a correctness-preserving deviation, well covered by three precedence tests plus a parent-context-prepend test in `subagent-session.test.ts`.
+- The atomic call-site swap (step 5) touched more test files than the plan's step-5 list anticipated: every tool/service test that set `record.execution = { session, outputFile }` (`steer-tool`, `agent-tool`, `background-spawner`, `foreground-runner`, `get-result-tool`, `service-adapter`) had to migrate to `record.subagentSession = toSubagentSession(createSubagentSessionStub(...))`.
+  Added `createSubagentSessionStub`/`toSubagentSession` to `mock-session.ts` so the migration was a one-line change per call site; the stub's `steer`/`dispose` delegate to the underlying `MockSession` so existing session-spy assertions kept working unchanged.
+- `disposed` moved from `runAgent`'s `finally` (run-completion) to `SubagentSession.dispose()`, invoked by `AgentManager` via the new `Agent.disposeSession()` (routing both `record.session?.dispose?.()` call sites at `agent-manager.ts:235,309`).
+  The full cross-package suite confirms the permission system (1504 tests) is unaffected — its subscription code did not change, only *when* `disposed` fires.
+- Test-helper gotcha: `makeSubagentSession`'s `outputFile` default initially swallowed an explicit `undefined` via `?? default`; fixed with an `"outputFile" in metaOverrides` presence check (the testing-skill "Partial spread erases explicit undefined" family).
+- `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.0.0",
+  "version": "13.2.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -24,9 +24,9 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
-import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runner";
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
+import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
@@ -132,7 +132,7 @@ export default function (pi: ExtensionAPI) {
     },
   };
 
-  const runnerDeps: RunnerDeps = {
+  const subagentSessionDeps: SubagentSessionDeps = {
     io: {
       detectEnv,
       getAgentDir,
@@ -162,7 +162,7 @@ export default function (pi: ExtensionAPI) {
   );
 
   const manager = new AgentManager({
-    runner: new ConcreteAgentRunner(runnerDeps),
+    createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
     baseCwd: process.cwd(),
     observer,
     queue,

package/src/lifecycle/agent-manager.ts

@@ -10,9 +10,10 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import { debugLog } from "#src/debug";
 import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
-import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { SubagentSession } from "#src/lifecycle/subagent-session";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
@@ -28,7 +29,8 @@ export interface AgentManagerObserver {
 }
 
 export interface AgentManagerOptions {
-  runner: AgentRunner;
+  /** Assembly factory that produces a born-complete SubagentSession per spawn. */
+  createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
   queue: ConcurrencyQueue;
   /** Base working directory handed to a workspace provider (the parent cwd). */
@@ -64,7 +66,7 @@ export class AgentManager {
   private agents = new Map<string, Agent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: AgentManagerObserver;
-  private readonly runner: AgentRunner;
+  private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   private readonly queue: ConcurrencyQueue;
   private readonly baseCwd: string;
   private getRunConfig?: () => RunConfig;
@@ -76,7 +78,7 @@ export class AgentManager {
   }
 
   constructor(options: AgentManagerOptions) {
-    this.runner = options.runner;
+    this.createSubagentSession = options.createSubagentSession;
     this.queue = options.queue;
     this.baseCwd = options.baseCwd;
     this.observer = options.observer;
@@ -111,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) {
@@ -152,7 +154,7 @@ export class AgentManager {
       parentSession: options.parentSession,
       signal: options.signal,
       // Shared deps
-      runner: this.runner,
+      createSubagentSession: this.createSubagentSession,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
       baseCwd: this.baseCwd,
@@ -200,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;
   }
@@ -231,8 +233,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: Agent): void {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
-    record.session?.dispose?.();
+    record.disposeSession();
     this.agents.delete(id);
   }
 
@@ -306,7 +307,7 @@ export class AgentManager {
     // Clear queue
     this.queue.clear();
     for (const record of this.agents.values()) {
-      record.session?.dispose();
+      record.disposeSession();
     }
     this.agents.clear();
   }