@gotgenes/pi-subagents 13.2.0 → 13.2.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.2.0...pi-subagents-v13.2.1) (2026-05-30)
+
+
+### Documentation
+
+* **pi-subagents:** refresh permission-integration and architecture sections ([#267](https://github.com/gotgenes/pi-packages/issues/267)) ([4096f83](https://github.com/gotgenes/pi-packages/commit/4096f83c343250b4d2cb5a522bbb140e1e023ed3))
+
 ## [13.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v13.1.0...pi-subagents-v13.2.0) (2026-05-30)
 
 

package/README.md

@@ -427,10 +427,10 @@ When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permissio
 - **Tool filtering** — the permission system's `before_agent_start` handler removes denied tools from the child session before the agent starts.
 - **`ask`-state forwarding** — when a child session triggers an `ask` permission, the prompt forwards to the parent session's UI.
   The parent approves or denies, and the child resumes.
-- **Deterministic child detection** — every child session registers with the permission system's `SubagentSessionRegistry` before `bindExtensions()` fires, so detection does not rely on env vars or filesystem heuristics.
+- **Deterministic child detection** — this extension publishes `subagents:child:session-created` before `bindExtensions()` fires; the permission system subscribes and registers the child session synchronously, so detection does not rely on env vars or filesystem heuristics.
 
 No configuration is required.
-When `@gotgenes/pi-permission-system` is not installed, the registration calls are silent no-ops.
+When `@gotgenes/pi-permission-system` is not installed, the lifecycle events have no subscriber — a harmless no-op.
 
 ## Architecture
 
@@ -451,19 +451,27 @@ src/
     session-config.ts               # Session configuration assembler
     prompts.ts                      # Config-driven system prompt builder
     context.ts                      # Parent conversation context for inherit_context
-    skill-loader.ts                 # Preload skills from Pi-standard + Agent Skills spec
+    conversation.ts                 # Render a session's messages as formatted text
+    content-items.ts                # Shared message content parsing
     env.ts                          # Environment detection (git, platform)
     model-resolver.ts               # Fuzzy model matching
+    session-dir.ts                  # Session directory derivation
   lifecycle/                        # Agent execution and state tracking
-    agent-manager.ts                # Spawn, queue, abort, resume, concurrency
-    agent-runner.ts                 # Session creation, turn loop, tool filtering
-    agent-record.ts                 # Status state machine
+    agent-manager.ts                # Collection manager + observer wiring
+    agent.ts                        # Full execution lifecycle (run, abort, steer, workspace)
+    create-subagent-session.ts      # Assembly factory: session creation, binding, tool filtering
+    subagent-session.ts             # Born-complete child session: turn loop, steer, dispose
+    child-lifecycle.ts              # Child-execution lifecycle event publisher
+    concurrency-queue.ts            # Background agent scheduling
     parent-snapshot.ts              # Immutable spawn-time parent state
-    permission-bridge.ts            # Optional bridge to pi-permission-system registry
-    worktree.ts                     # Git worktree isolation
+    turn-limits.ts                  # Turn-count policy (normalizeMaxTurns)
+    workspace.ts                    # Workspace provider seam
+    usage.ts                        # Token usage tracking
   observation/                      # Progress tracking and notification
     record-observer.ts              # Session-event stats observer
     notification.ts                 # Completion nudges
+    notification-state.ts           # Notification state tracking
+    renderer.ts                     # Notification rendering
   service/                          # Cross-extension API boundary
     service.ts                      # SubagentsService interface + Symbol.for() accessors
     service-adapter.ts              # SubagentsService wrapper around AgentManager
@@ -484,8 +492,9 @@ Each has a corresponding upstream PR:
 3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes).
    Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.
    Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
-4. **Permission-system registration** (`src/lifecycle/permission-bridge.ts`) — `runAgent` registers every child session with `@gotgenes/pi-permission-system`'s `SubagentSessionRegistry` before `bindExtensions()` and unregisters in the `finally` block.
-   This enables deterministic child detection and `ask`-state forwarding to the parent UI.
+4. **Child-execution lifecycle events** (`src/lifecycle/child-lifecycle.ts`) — the child-session execution lifecycle is published as ordered events on `pi.events` (`subagents:child:spawning`, `session-created`, `completed`, `disposed`).
+   `session-created` fires synchronously before `bindExtensions()` so consumers (e.g. `@gotgenes/pi-permission-system`) can register the child session before binding proceeds.
+   This inverts the former outbound `permission-bridge` pattern (ADR 0002 / [#261]) — the core publishes, consumers subscribe.
    No upstream equivalent — this feature is specific to the `@gotgenes` fork.
 
 The upstream `vitest` suite plus tests added for each patch all pass on every commit.

package/docs/architecture/architecture.md

@@ -755,106 +755,15 @@ After Phase 15, Agent is born complete with all dependencies and configuration,
 All six steps are closed: [#227], [#228], [#231], [#229], [#230], [#232].
 See [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md) for details.
 
-## Improvement roadmap (Phase 16 — invert dependencies: extensions on a minimal core)
+## Phase 16 (complete)
 
-Phase 16 reclaims its original intent — invert the core's outbound dependencies — and extends it: worktree isolation joins permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
+Phase 16 inverted the core's outbound dependencies: worktree isolation joined permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
+The core now attaches extensions through exactly two surfaces — observational lifecycle events (unlimited) and rationed generative provider seams (today only the workspace provider) — and has zero knowledge of its consumers.
+The "runner" concept is gone: `createSubagentSession()` returns a born-complete `SubagentSession` that owns turn driving, steering, and disposal, and `Agent.run()` is coordination, not assembly.
 The decision and the full reasoning chain are recorded in [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md); the two-surface extension model is described under [Target architecture](#target-architecture).
-
-### Abandoned exploration: agent collaborator architecture
-
-An earlier Phase 16 plan ("agent collaborator architecture") proposed giving `Agent` three collaborators — a session factory, a `WorktreeIsolation`, and a lifecycle observer — and dissolving the runner.
-That framing was abandoned.
-Pulling on a single late-bound `create(cwd?)` parameter on the planned `ChildSessionFactory` exposed deeper problems:
-
-- `WorktreeIsolation.setup()` is a two-phase `construct-then-setup()` that violates "Construct complete" (principle 8) — the worktree is only *ready* at dequeue.
-- The worktree and the child session share one lifespan, so they are one run-scoped resource, not sibling collaborators that `Agent` must sequence; the `cwd` parameter only existed because the worktree was split out and `Agent` relayed its output back in.
-- Worktrees are not intrinsic to subagents — they are one *workspace strategy* and belong outside the core, exactly as Phase 14 evicted tool/extension policy.
-
-Issue #256 (`WorktreeIsolation` as a collaborator) shipped under the abandoned plan and is now superseded by #263; issue #257 (`ChildSessionFactory` extraction) was parked.
-The structural win the collaborator plan chased — a born-complete child execution and the dissolution of the runner — is recovered by a cleaner route once the workspace seam exists (Step 5).
-
-### Steps
-
-#### Step 1: Child-execution lifecycle events; retire permission-bridge — [#261] ✅ Delivered
-
-Emit ordered child-execution events (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) carrying child identity (session directory, agent name, parent session id).
-Migrate `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disposed` for registration instead of being looked up by the core; delete `permission-bridge.ts`.
-
-- Cross-package: pi-subagents (emit + remove bridge) and pi-permission-system (subscribe).
-- Investigation (resolved): `pi.events` is a Node `EventEmitter`, so `emit()` dispatches listeners synchronously on the same call stack — a synchronous subscriber completes before `emit()` returns.
-  Emitting `session-created` immediately before `bindExtensions()` therefore guarantees the registry entry lands pre-bind, with no new SDK hook.
-  The synchronous-handler constraint is encoded as a real-bus test in pi-permission-system.
-- Outcome: the core stops reaching out to a named consumer; permission detection rides events.
-- Deferred: removing the now-caller-less `registerSubagentSession`/`unregisterSubagentSession` from `PermissionsService` → #267; registry-detected resume ("executing now" → "exists" semantics) → #265.
-
-#### Step 2: Define the `WorkspaceProvider` seam — [#262] ✅ Delivered
-
-Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
-All five workspace types are named-re-exported from `service.ts`: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` (added in #272).
-At run-start `Agent.run()` consults the registered provider for the child's cwd and a disposal handle; with no provider the child runs in the parent's cwd (the legacy worktree-collaborator fallback was removed when worktrees left the core in #263).
-On completion the core calls `Workspace.dispose({ status, description })` and appends the returned `resultAddendum` verbatim — the provider owns the wording.
-
-- The seam is additive and non-breaking: the existing `isolation: "worktree"` path is untouched (its eviction is Step 3).
-- Land alongside its first consumer (Step 3) to avoid a vacant hook — the "no vacant hooks" rule.
-  Within #262 the seam is exercised only by test fakes; do not cut a release containing the seam without `@gotgenes/pi-subagents-worktrees`.
-- Outcome: a single generative seam; the core no longer knows what an "isolation strategy" is.
-
-#### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263] ✅ Delivered
-
-New package implementing `WorkspaceProvider`: prepares a git worktree at run-start (born complete), tears it down after (saving the branch), and owns the "changes saved to branch" result.
-Worktree isolation is opt-in per agent type via the package's own `worktreeAgents` config; creation failure for an opted-in agent throws (strict, no silent fallback).
-Removed `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; dropped `isolation` from the spawn API and `SubagentsService`, and `worktreeResult` from `SubagentRecord`.
-
-- Supersedes #256.
-  New package registered in `release-please-config.json` and `.pi/settings.json` (after pi-subagents); consumes the published `@gotgenes/pi-subagents` from the registry (`linkWorkspacePackages: false`), since `exports.types` resolves to the shipped declaration bundle.
-  From the release carrying #272, all five workspace types are importable by name: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult`.
-- Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
-
-#### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264] ✅ Delivered
-
-Children always load the parent's extensions and skills; the recursion guard is now unconditional.
-Deny-at-use (the in-child permission layer) covers tool restriction; prevent-load is left as a latent provider seam (not shipped).
-The `skills` curation axis collapsed symmetrically with `extensions`: `AgentConfig.skills`, the skill-preload path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`), `SessionConfig.{extensions,noSkills,extras}`, and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are all gone.
-
-- Depended on: Step 1 (deny-at-use over events).
-- Outcome: the `isolated`/`extensions`/`noSkills`/`skills` axis is gone; the guard is unconditional.
-
-#### Step 5: Born-complete child execution; dissolve the runner — [#265] ✅ Delivered
-
-`createSubagentSession()` is an assembly factory that returns a born-complete `SubagentSession` (session created, extensions bound, recursion guard applied).
-`SubagentSession` owns turn driving (`runTurnLoop`/`resumeTurnLoop`), steering, and disposal.
-`Agent.run()` is coordination, not assembly; `runAgent` / `resumeAgent` / `ConcreteAgentRunner` / `AgentRunner` / `RunOptions` / `RunResult` / `ExecutionState` dissolved.
-`getAgentConversation()` relocated to `session/conversation.ts`; `normalizeMaxTurns()` to `lifecycle/turn-limits.ts`.
-`disposed` now fires at true session disposal (cleanup), so resume executions are registry-detected (closing the gap deferred from #261).
-
-- Depends on: Steps 2–4.
-- Outcome: the "runner" concept is gone; `Agent.run()` is coordination, not assembly — the structural goal of the abandoned collaborator plan, reached cleanly.
-
-### Step dependency diagram
-
-```mermaid
-flowchart LR
-    S1["Step 1<br/>Lifecycle events<br/>(retire bridge)"]
-    S2["Step 2<br/>WorkspaceProvider seam"]
-    S3["Step 3<br/>Extract worktrees pkg"]
-    S4["Step 4<br/>Remove isolated"]
-    S5["Step 5<br/>Born-complete execution"]
-
-    S2 --> S3
-    S1 --> S4
-    S2 --> S5
-    S3 --> S5
-    S4 --> S5
-```
-
-### Tracks
-
-1. **Track A — Inversion seams** (Steps 1, 2): lifecycle events and the workspace seam.
-   Independent of each other — can proceed in parallel.
-2. **Track B — Eviction** (Steps 3, 4): worktrees and `isolated` leave the core.
-   Step 3 depends on Step 2.
-3. **Track C — Consolidation** (Step 5): dissolve the runner around the new seam.
-   Depends on Tracks A and B.
+All five steps are closed: [#261], [#262], [#263], [#264], [#265].
+The earlier "agent collaborator architecture" framing (#256 superseded, #257 parked, #258 and #259 closed not-planned) was abandoned; its structural win was reached cleanly via the workspace seam.
+See [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md) for details.
 
 ## Improvement roadmap (Phase 17 — extract UI)
 
@@ -864,8 +773,8 @@ By this point the core is minimal and stable — the API boundary has been prove
 
 ## Refactoring history
 
-Phases 1–5, 7–14 are complete.
-Phase 6 (UI extraction to a separate package) is deferred.
+Phases 1–5, 7–16 are complete.
+Phase 6 (UI extraction to a separate package) is deferred → Phase 17.
 Detailed records are preserved in per-phase history files:
 
 | Phase | Title                                               | Status              | History                                                                              |
@@ -885,7 +794,7 @@ Detailed records are preserved in per-phase history files:
 | 13    | Remaining structural smells                         | Complete            | [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md)                 |
 | 14    | Strip policy from core                              | Complete            | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
 | 15    | Domain model evolution                              | Complete            | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
-| 16    | Invert dependencies (extensions on a minimal core)  | Planned             | [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md)                        |
+| 16    | Invert dependencies (extensions on a minimal core)  | Complete            | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
 | 17    | Extract UI to separate package                      | Planned             | —                                                                                    |
 
 ### Structural refactoring issues
@@ -907,7 +816,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 14             | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                                 |
 | Phase 15             | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                                 |
 | Phase 16             | #261, #262, #263, #264, #265                               | Lifecycle events (retire permission-bridge), WorkspaceProvider seam, extract worktrees package, remove isolated, born-complete execution / dissolve runner |
-| Phase 16 (abandoned) | #256 (superseded), #257 (parked)                           | Agent collaborator architecture — replaced by the inversion approach above (ADR 0002)                                                                      |
+| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above (ADR 0002)                                                                      |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 

package/docs/architecture/history/phase-16-invert-dependencies.md

@@ -0,0 +1,143 @@
+# Phase 16: Invert dependencies — extensions on a minimal core
+
+## Summary
+
+Phase 16 reclaimed its original intent — invert the core's outbound dependencies — and extended it: worktree isolation joined permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
+The decision and the full reasoning chain are recorded in [ADR 0002](../../decisions/0002-extensions-on-a-minimal-core.md); the two-surface extension model is described under [Target architecture](../architecture.md#target-architecture).
+
+All five steps are closed: [#261], [#262], [#263], [#264], [#265].
+
+## Two extension surfaces
+
+Extensions attach through exactly two surfaces, distinguished by the direction of information flow.
+
+1. **Lifecycle events (observational) — unlimited.**
+   The core emits awaited, ordered events for the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`).
+   Any number of extensions subscribe; handlers return nothing.
+   Reactive concerns live here: permission detection, telemetry, UI, notifications.
+   Adding a reactive concern never modifies the core.
+2. **Provider seams (generative) — rationed.**
+   The rare concern that must *inject* a value the core consumes synchronously registers a provider the core consults.
+   Today there is exactly one: the **workspace provider** (returns the child's working directory plus bracketed setup/teardown).
+   A provider seam is the only place the core is "open," so the list is kept as small as possible.
+
+The discriminator when deciding how a concern attaches:
+
+- It only needs to **know** what happened → subscribe to a lifecycle event (observational, unlimited).
+- It must **return a value the core consumes** → register a provider (generative, rationed).
+
+The governing rule — **no vacant hooks**: the architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
+A provider seam with no consumer is a speculative abstraction that taxes every reader and that `fallow` flags as dead.
+Latent extensibility is the deliverable; a vacant hook is not.
+
+## Abandoned exploration: agent collaborator architecture
+
+An earlier Phase 16 plan ("agent collaborator architecture") proposed giving `Agent` three collaborators — a session factory, a `WorktreeIsolation`, and a lifecycle observer — and dissolving the runner.
+That framing was abandoned.
+Pulling on a single late-bound `create(cwd?)` parameter on the planned `ChildSessionFactory` exposed deeper problems:
+
+- `WorktreeIsolation.setup()` is a two-phase `construct-then-setup()` that violates "Construct complete" (principle 8) — the worktree is only *ready* at dequeue.
+- The worktree and the child session share one lifespan, so they are one run-scoped resource, not sibling collaborators that `Agent` must sequence; the `cwd` parameter only existed because the worktree was split out and `Agent` relayed its output back in.
+- Worktrees are not intrinsic to subagents — they are one *workspace strategy* and belong outside the core, exactly as Phase 14 evicted tool/extension policy.
+
+Issue #256 (`WorktreeIsolation` as a collaborator) shipped under the abandoned plan and was superseded by #263; issue #257 (`ChildSessionFactory` extraction) was parked.
+Issues #258 (Agent owns session lifecycle via factory) and #259 (dissolve runner concept) belonged to the same abandoned plan — both depended on #256/#257 and were closed as not planned; their structural goals were recovered by Step 5 (#265) via a cleaner route.
+The structural win the collaborator plan chased — a born-complete child execution and the dissolution of the runner — is recovered once the workspace seam exists (Step 5).
+
+## Steps
+
+### Step 1: Child-execution lifecycle events; retire permission-bridge — [#261]
+
+Emit ordered child-execution events (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) carrying child identity (session directory, agent name, parent session id).
+Migrated `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disposed` for registration instead of being looked up by the core; deleted `permission-bridge.ts`.
+
+- Cross-package: pi-subagents (emit + remove bridge) and pi-permission-system (subscribe).
+- Investigation (resolved): `pi.events` is a Node `EventEmitter`, so `emit()` dispatches listeners synchronously on the same call stack — a synchronous subscriber completes before `emit()` returns.
+  Emitting `session-created` immediately before `bindExtensions()` therefore guarantees the registry entry lands pre-bind, with no new SDK hook.
+  The synchronous-handler constraint is encoded as a real-bus test in pi-permission-system.
+- Outcome: the core stops reaching out to a named consumer; permission detection rides events.
+- Deferred: removing the now-caller-less `registerSubagentSession`/`unregisterSubagentSession` from `PermissionsService` → #267; registry-detected resume ("executing now" → "exists" semantics) → #265.
+
+### Step 2: Define the `WorkspaceProvider` seam — [#262]
+
+Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
+All five workspace types are named-re-exported from `service.ts`: `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` (added in #272).
+At run-start `Agent.run()` consults the registered provider for the child's cwd and a disposal handle; with no provider the child runs in the parent's cwd.
+On completion the core calls `Workspace.dispose({ status, description })` and appends the returned `resultAddendum` verbatim — the provider owns the wording.
+
+- The seam is additive and non-breaking.
+- Landed alongside its first consumer (Step 3) to avoid a vacant hook — the "no vacant hooks" rule.
+- Outcome: a single generative seam; the core no longer knows what an "isolation strategy" is.
+
+### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263]
+
+New package implementing `WorkspaceProvider`: prepares a git worktree at run-start (born complete), tears it down after (saving the branch), and owns the "changes saved to branch" result.
+Worktree isolation is opt-in per agent type via the package's own `worktreeAgents` config; creation failure for an opted-in agent throws (strict, no silent fallback).
+Removed `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; dropped `isolation` from the spawn API and `SubagentsService`, and `worktreeResult` from `SubagentRecord`.
+
+- Supersedes #256.
+  New package registered in `release-please-config.json` and `.pi/settings.json` (after pi-subagents); consumes the published `@gotgenes/pi-subagents` from the registry (`linkWorkspacePackages: false`).
+- Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
+
+### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264]
+
+Children always load the parent's extensions and skills; the recursion guard is now unconditional.
+Deny-at-use (the in-child permission layer) covers tool restriction; prevent-load is left as a latent provider seam (not shipped).
+The `skills` curation axis collapsed symmetrically with `extensions`: `AgentConfig.skills`, the skill-preload path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`), `SessionConfig.{extensions,noSkills,extras}`, and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are all gone.
+
+- Depended on: Step 1 (deny-at-use over events).
+- Outcome: the `isolated`/`extensions`/`noSkills`/`skills` axis is gone; the guard is unconditional.
+
+### Step 5: Born-complete child execution; dissolve the runner — [#265]
+
+`createSubagentSession()` is an assembly factory that returns a born-complete `SubagentSession` (session created, extensions bound, recursion guard applied).
+`SubagentSession` owns turn driving (`runTurnLoop`/`resumeTurnLoop`), steering, and disposal.
+`Agent.run()` is coordination, not assembly; `runAgent` / `resumeAgent` / `ConcreteAgentRunner` / `AgentRunner` / `RunOptions` / `RunResult` / `ExecutionState` dissolved.
+`getAgentConversation()` relocated to `session/conversation.ts`; `normalizeMaxTurns()` to `lifecycle/turn-limits.ts`.
+`disposed` now fires at true session disposal (cleanup), so resume executions are registry-detected (closing the gap deferred from #261).
+
+- Depends on: Steps 2–4.
+- Outcome: the "runner" concept is gone; `Agent.run()` is coordination, not assembly — the structural goal of the abandoned collaborator plan, reached cleanly.
+
+## Step dependency diagram
+
+```mermaid
+flowchart LR
+    S1["Step 1<br/>Lifecycle events<br/>(retire bridge)"]
+    S2["Step 2<br/>WorkspaceProvider seam"]
+    S3["Step 3<br/>Extract worktrees pkg"]
+    S4["Step 4<br/>Remove isolated"]
+    S5["Step 5<br/>Born-complete execution"]
+
+    S2 --> S3
+    S1 --> S4
+    S2 --> S5
+    S3 --> S5
+    S4 --> S5
+```
+
+## Tracks
+
+1. **Track A — Inversion seams** (Steps 1, 2): lifecycle events and the workspace seam.
+   Independent of each other — proceeded in parallel.
+2. **Track B — Eviction** (Steps 3, 4): worktrees and `isolated` leave the core.
+   Step 3 depends on Step 2.
+3. **Track C — Consolidation** (Step 5): dissolve the runner around the new seam.
+   Depends on Tracks A and B.
+
+## Composition model
+
+In the post-Phase-16 state, pi-subagents publishes events and a provider seam; other packages hook in:
+
+- **pi-permission-system** (observational) subscribes to child-session lifecycle events, detects subagent execution context in the child, and gates tool calls at runtime.
+- **pi-subagents-worktrees** (generative) registers a `WorkspaceProvider` that prepares a git worktree at run-start and tears it down after, supplying the child's cwd.
+- **pi-subagents-ui** (future, Phase 17) subscribes to the service API, renders the widget, conversation viewer, and `/agents` menu.
+- **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
+
+Composition test: install neither extension, only permissions, only workspaces, or both — the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
+
+[#261]: https://github.com/gotgenes/pi-packages/issues/261
+[#262]: https://github.com/gotgenes/pi-packages/issues/262
+[#263]: https://github.com/gotgenes/pi-packages/issues/263
+[#264]: https://github.com/gotgenes/pi-packages/issues/264
+[#265]: https://github.com/gotgenes/pi-packages/issues/265

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

@@ -37,3 +37,44 @@ Test count went from 960 → 973 (+13 net: +18 new tests, −5 removed tests for
 - The `get-result-tool.test.ts` verbose conversation test needed updating: previously built a mock session with messages and passed it directly; now the stub's `getConversation` must return the expected text via `mockReturnValue`.
 - Pre-completion reviewer returned **WARN** for two stale `architecture.md` passages: (1) conversation-viewer description still said "subscribes directly to `AgentSession`"; (2) `Agent` classDiagram still listed `queueSteer`/`flushPendingSteers` as public and omitted the 6 new public members.
   Both fixed in a `docs:` commit before closing.
+
+## Stage: Final Retrospective (2026-05-30T16:00:00Z)
+
+### Session summary
+
+Issue #277 shipped across three sessions (planning, TDD, ship) in a single day.
+All 8 TDD steps completed cleanly, 13 implementation commits landed, and `pi-subagents-v13.2.0` released.
+
+### Observations
+
+#### What went well
+
+- Planning correctly identified scope beyond the issue's three proposed methods: `getContextPercent()`, `subscribeToUpdates()`, and `messages` were needed to satisfy the "no production module outside `lifecycle/` references `AgentSession`" acceptance criterion.
+  This prevented mid-TDD design revisions.
+- The discovery that `subscribeAgentObserver` already accepted `SubscribableSession` meant adding `subscribe()` to `SubagentSession` was sufficient for observer wiring — no type cast or adapter needed.
+- Lift-and-shift execution was precise: new methods added first (steps 1-2), callers migrated by concern (steps 3-6), old getter removed last (step 7).
+  No step broke any other step's tests.
+- Pre-completion reviewer caught two stale `architecture.md` passages (classDiagram with removed public methods, conversation-viewer description) that the implementation steps missed.
+  Both fixed in a `docs:` commit before closing.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — `MockSession` interface lacked `messages`.
+   The field existed at runtime (via `createMockSession`'s spread + `Record<string, unknown>` return type) but the `MockSession` interface didn't declare it.
+   Adding `messages` to `createSubagentSessionStub` triggered a type error.
+   Impact: 2 extra edits to `mock-session.ts` (add field to interface, add to `base` object), no rework.
+2. `missing-context` — `get-result-tool.test.ts` conversation test relied on raw mock session messages.
+   After migrating to `record.getConversation()`, the stub's `getConversation` returned `""` by default.
+   The test needed `stub.getConversation.mockReturnValue("...")` instead.
+   Impact: 1 test update, caught immediately by `pnpm vitest run`.
+3. `missing-context` — `foreground-runner.test.ts` called `onSessionCreated(record, mockSess)` with 2 args.
+   After narrowing the callback to `(agent: Agent)`, the first test lacked `record.subagentSession` setup.
+   Impact: 2 test blocks updated, caught by `pnpm vitest run`.
+4. `missing-context` — First `get-result-tool.ts` edit left a double-nested `if (conversation)` block.
+   The multi-edit replaced the outer `if (params.verbose && record.session)` but preserved the inner guard, creating `if (conversation) { if (conversation) { ... } }`.
+   Impact: Self-caught on immediate read-back; fixed in the same commit, no rework.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's involvement was limited to the `/plan-issue`, `/tdd-plan`, `/ship-issue`, and `/retro` prompts — no mid-session corrections or redirections were needed.

package/package.json

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