@gotgenes/pi-subagents 11.2.0 → 11.3.0

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).
 
+## [11.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.2.0...pi-subagents-v11.3.0) (2026-05-29)
+
+
+### Features
+
+* **pi-subagents:** add WorktreeIsolation collaborator ([ee7ab73](https://github.com/gotgenes/pi-packages/commit/ee7ab73a53f8643b5887856c33d53786a5a5a9cc))
+
 ## [11.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.1.0...pi-subagents-v11.2.0) (2026-05-28)
 
 

package/docs/architecture/architecture.md

@@ -112,7 +112,7 @@ classDiagram
         +toolUses: number
         +lifetimeUsage: LifetimeUsage
         +execution?: ExecutionState
-        +worktreeState?: WorktreeState
+        +worktree?: WorktreeIsolation
         +notification?: NotificationState
         +markRunning()
         +markCompleted()
@@ -126,9 +126,8 @@ classDiagram
         +abort(): boolean
         +queueSteer(message)
         +flushPendingSteers(session)
-        +setupWorktree(worktrees, isolation)
-        +completeRun(result, worktrees)
-        +failRun(err, worktrees)
+        +completeRun(result)
+        +failRun(err)
         +wireSignal(signal, onAbort)
         +attachObserver(unsub)
         +releaseListeners()
@@ -277,7 +276,7 @@ src/
 │   ├── execution-state.ts          session/output phase state
 │   ├── permission-bridge.ts        optional bridge to pi-permission-system registry
 │   ├── worktree.ts                 git worktree isolation
-│   ├── worktree-state.ts           worktree phase state
+│   ├── worktree-isolation.ts       worktree lifecycle collaborator
 │   └── usage.ts                    token usage tracking
 │
 ├── observation/                    progress tracking and notification
@@ -490,13 +489,13 @@ This is achieved across three phases: Phase 14 (strip policy), Phase 16 (invert
 | Metric                     | Value                             |
 | -------------------------- | --------------------------------- |
 | Health score               | 78/100 (B)                        |
-| Total LOC                  | 8,382 (56 files)                  |
+| Total LOC                  | 7,778 (57 files)                  |
 | Dead code                  | 0 files, 0 exports                |
 | Maintainability index      | 90.8 (good)                       |
 | Avg cyclomatic complexity  | 1.4                               |
 | P90 cyclomatic complexity  | 2                                 |
 | Production duplication     | 11 lines (1 internal clone group) |
-| Test duplication           | 38 clone groups, 634 lines        |
+| Test duplication           | 42 clone groups, 661 lines        |
 | Fallow refactoring targets | 0                                 |
 
 ### Dependency bag inventory
@@ -687,185 +686,252 @@ See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
 [#239]: https://github.com/gotgenes/pi-packages/issues/239
 [#242]: https://github.com/gotgenes/pi-packages/issues/242
 
-## Improvement roadmap (Phase 15 — domain model evolution)
+## Improvement roadmap (Phase 16 — agent collaborator architecture)
 
-Phase 15 evolves `Agent` from a passive state machine into an object that **owns its entire execution lifecycle**.
+Phase 16 gives Agent proper collaborators so it can do its work without accumulating raw materials.
 
-Steps 1–2 (complete) moved per-agent behavior from `AgentManager` onto `Agent`: abort, steer buffering, worktree setup, and run lifecycle methods (`completeRun`, `failRun`).
-However, Agent still cannot *run itself*.
-`AgentManager.startAgent()` orchestrates the entire execution: calling the runner, handling session creation, wiring observers, and cleaning up worktrees.
-The manager reaches into Agent 10 times across `spawn()` + `startAgent()` — writing to `notification`, `execution`, and `promise` after construction, passing its own `worktrees` and `runner` as method arguments, and threading `onSessionCreated` callbacks through three layers.
+Phase 15 established the principle: Agent owns its lifecycle, not a manager.
+But in practice, Agent received 9 raw config fields and a shared generic runner, then assembled the runner call itself.
+The runner (`ConcreteAgentRunner`) is a stateless service — one instance shared across all agents — so every per-agent concern (snapshot, prompt, model, maxTurns, etc.) had to live on Agent as private fields.
+The result: `AgentInit` has ~20 optional fields, and Agent stores ~87 `this._` references.
 
-The remaining steps address this by making **Agent born complete**: constructed with all dependencies and configuration, owning its entire execution lifecycle.
+The deeper issue: the "runner" conflates two concerns.
+Session *creation* (platform plumbing — resource loaders, extension binding, tool filtering, env detection) is genuinely separate from session *interaction* (prompt, steer, abort, resume).
+Pi's own `Agent` class (in `packages/agent/`) already handles the interaction — it owns the transcript, runs the turn loop, executes tools, manages steering queues.
+Our extension's novel value is **child session orchestration within a parent session**: creating child sessions with config derived from the parent, managing concurrency, wiring lifecycle across sessions, and enabling resume.
+We should leverage the Pi session for interaction and focus on what's novel.
 
-### Architecture target
+### Target architecture
 
-Agent receives three concerns at construction:
+Agent receives three collaborators at construction, each ready to go:
 
-| Concern     | Fields                                                                        | Lifetime                  |
-| ----------- | ----------------------------------------------------------------------------- | ------------------------- |
-| Identity    | id, type, description, invocation                                             | Immutable                 |
-| Run config  | snapshot, prompt, model, isolation, maxTurns, thinking, signal, parentSession | Immutable per-run         |
-| Shared deps | runner, worktrees                                                             | Shared service references |
+| Collaborator           | Absorbs                                                                                                            | Agent tells it                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| Session factory        | runner + snapshot + prompt + model + maxTurns + isolated + thinkingLevel + parentSession + getRunConfig (9 fields) | "create me a configured child session"                          |
+| WorktreeIsolation      | worktrees + isolation + worktreeState (3 fields)                                                                   | `setup()`, `cleanup(description)`                               |
+| AgentLifecycleObserver | (already exists, 0 new fields)                                                                                     | `onStarted`, `onSessionCreated`, `onRunFinished`, `onCompacted` |
 
-`Agent.run()` encapsulates the full execution lifecycle:
+After the session factory creates a session, Agent owns it directly — prompt, steer, abort, resume are Agent's verbs, not a collaborator's.
+The shared `ConcreteAgentRunner` becomes a factory that produces per-agent session factories.
+The "runner" concept dissolves.
 
-1. Set up worktree internally (knows its own isolation mode, has worktrees).
-2. Call `this.runner.run()` (has the runner).
-3. Handle session creation internally: set `execution`, flush pending steers, attach record-observer.
-4. Notify lifecycle observer (started, session created, completed, compacted).
-5. Clean up worktree on completion or error.
-6. Transition status.
+`AgentInit` shrinks from ~20 to ~10 fields:
 
-`AgentManager` becomes a collection manager + observer wiring:
+- 4 identity (`id`, `type`, `description`, `invocation`)
+- 2 status (`status`, `startedAt` — for tests/restore)
+- 3 collaborators (`sessionFactory`, `worktree`, `observer`)
+- 1 wiring (`signal`)
 
-- Creates complete Agent objects, stores them in the map.
-- Decides when to run (immediate or queue) and calls `agent.run()`.
-- Provides high-level actions: abort, list, cleanup.
-- Does *not* own the runner, worktrees, or any run-orchestration logic.
+Agent's `run()` becomes coordination, not assembly:
 
-The queue stores agent IDs, not `SpawnArgs`.
-When capacity opens, the manager looks up the agent and calls `agent.run()` — the agent already has everything.
+```text
+mark running → notify observer → wire signal
+→ tell worktree to setup
+→ tell session factory to create session
+→ own the session: flush steers, subscribe observers, prompt, track turns
+→ on completion: tell worktree to cleanup, transition status, notify observer
+```
+
+Agent's `resume()` is trivially Agent's work — it already has the session:
+
+```text
+reset status → re-subscribe observer → prompt the existing session → transition status
+```
 
-The `onSessionCreated` callback that currently threads through `AgentSpawnConfig` → `startAgent` → `RunOptions` → runner disappears.
-Agent handles session creation internally during `run()` and notifies external observers via the lifecycle observer pattern.
+### What we can commit to
 
-The synchronous-throw contract for worktree failure (introduced in Step 2's hoist) is replaced by a uniform async error surface.
-Worktree failures inside `agent.run()` propagate through the promise.
-For background agents, errors surface via `get_subagent_result` and appear in `/agents`.
-For foreground agents, `spawnAndWait` awaits the promise naturally.
+1. **The runner is not a collaborator — it's Agent's core behavior conflated with a session factory.**
+   The shared `ConcreteAgentRunner` becomes a factory.
+   Each agent receives a per-agent session factory with config already bound.
+   Once the session exists, Agent interacts with it directly.
 
-The scheduling concern (queue, concurrency counter, drain) is tangled into `AgentManager` alongside collection management and run orchestration.
-`notifyConcurrencyChanged()` is a scheduling method exposed as a public API so settings can poke the queue — a cross-concern leak.
+2. **WorktreeIsolation is a genuine collaborator.**
+   Created by the factory (AgentManager) only when `isolation === "worktree"`.
+   Agent tells it `setup()` and `cleanup()` instead of managing worktree internals.
+   The null check (`this.worktree?.setup()`) replaces the mode check (`this._isolation !== "worktree"`).
 
-### Findings summary
+3. **AgentLifecycleObserver is already a well-designed collaborator.**
+   No changes needed — Agent tells it about lifecycle events.
 
-| Finding                                                                | Category     | Impact | Risk | Priority |
-| ---------------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
-| ~~`AgentRecord` is anemic — no behavior, manager reaches in 37×~~      | B: Oversized | 5      | 3    | ✅       |
-| ~~Agent cannot run itself — manager orchestrates 10 external touches~~ | C: Coupling  | 5      | 3    | ✅       |
-| ~~Scheduling tangled into `AgentManager` (3 fields, 3 methods)~~       | A: Coupling  | 4      | 2    | ✅       |
-| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~      | C: Callbacks | 3      | 2    | ✅       |
-| ~~`onSessionCreated` callback flows through 3 layers~~                 | C: Callbacks | 3      | 2    | subsumed |
-| ~~`resume()` duplicates observer subscribe/unsubscribe pattern~~       | A: Redundant | 2      | 1    | ✅       |
-| ~~`exec`/`registry` relay-only deps on `AgentManager`~~                | C: Coupling  | 2      | 1    | ✅       |
+4. **AgentInit must shrink dramatically.**
+   ~20 optional fields → ~10, with clear grouping: identity + collaborators + wiring.
 
-### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
+### Resolved investigations
 
-Rename `AgentRecord` → `Agent` (or wrap it).
-Move per-agent behavior from `AgentManager` into the agent:
+All five investigations have been resolved by examining Pi's `AgentSession` SDK interface (source: `@earendil-works/pi-coding-agent` + Pi's `packages/agent/src/agent.ts`).
 
-1. `Agent.abort()` — absorbs status-check + controller.abort + markStopped.
-2. `Agent.queueSteer(message)` / `Agent.flushPendingSteers(session)` — moves pending steers from manager map to per-agent array.
-3. `Agent.setupWorktree(worktrees, isolation)` — moves worktree creation into the agent.
+#### 1. `AgentSession` SDK interface — resolved
 
-- Target: `src/lifecycle/agent-record.ts` → `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`
-- Smell: B (anemic domain model) + C (manager reaching into records)
-- Outcome: `AgentManager` delegates via Tell-Don't-Ask; per-agent state lives on the agent
+AgentSession provides everything Agent needs for direct session interaction:
 
-### Step 2: Convert startAgent to async/await — [#228] ✅ Complete
+| What Agent needs          | AgentSession provides                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------ |
+| Prompt (initial + resume) | `session.prompt(text)` — works for both; calling it again on an existing session IS resume |
+| Steer                     | `session.steer(text)`                                                                      |
+| Abort                     | `session.abort()` — async, waits for idle                                                  |
+| Subscribe to events       | `session.subscribe(listener)` — turn_end, message_end, tool_execution_end, compaction_end  |
+| Read messages             | `session.messages`                                                                         |
+| Get session file          | `session.sessionManager.getSessionFile()`                                                  |
+| Dispose                   | `session.dispose()`                                                                        |
 
-Converted `startAgent` to `async` with `try/catch` and dissolved `RunHandle` into `Agent` methods.
-`spawn()` assigns `record.promise = this.startAgent(...)` instead of calling `startAgent()` synchronously.
-`Agent` gained run lifecycle methods: `completeRun`, `failRun`, `wireSignal`, `attachObserver`, `releaseListeners`, `setOnRunFinished`.
-Worktree setup was hoisted to callers (`spawn`, `drainQueue`) to preserve the synchronous-throw contract.
+Key finding: `session.prompt(text)` handles both initial run and resume — our current `resumeAgent()` already just calls this.
+The core Pi `Agent` (accessible via `session.agent`) owns the transcript, turn loop, tool execution, and steering/follow-up queues.
+Our Agent should call `session.prompt()` directly and subscribe to events for turn-limit enforcement.
 
-- Depends on: #227
-- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent.ts`
-- Smell: C (raw promise callbacks)
-- Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`; `RunHandle` deleted; Agent owns run lifecycle
+#### 2. Session factory boundary — resolved
 
-### Step 3: Push exec/registry relay deps to runner construction — [#231] ✅
+The factory encapsulates everything *before* Agent starts using the session.
+The seam is clean: factory produces a ready-to-use `AgentSession`, Agent operates it.
 
-`exec` and `registry` moved from `AgentManager` to `ConcreteAgentRunner` via a new `RunnerDeps` interface.
-`RunContext` shrunk from 4 to 2 per-call fields (`cwd`, `parentSession`).
-`AgentManagerOptions` shrunk from 7 to 5 fields.
+```text
+Factory creates (platform plumbing):
+  detect env → assemble config → create resource loader → reload
+  → create session manager → new session
+  → createAgentSession() → bindExtensions() → filter tools (recursion guard)
+  → register with permission bridge
+  → return { session, outputFile, cleanup }
+
+Agent takes over (novel orchestration):
+  → subscribe for turn tracking (maxTurns + graceTurns)
+  → session.prompt(text)
+  → collect response from session.messages
+  → session.steer() / session.abort() for turn limits
+  → call cleanup() when done
+```
+
+Factory input: per-agent config (snapshot, prompt, model, maxTurns, isolated, thinkingLevel, parentSession) bound at construction, plus per-call `cwd` from worktree.
+Factory output: `{ session: AgentSession, outputFile?: string, cleanup: () => void }`.
+
+#### 3. Turn-limit enforcement — Agent's job via session subscription
+
+Agent subscribes to session events and enforces turn limits — this is novel orchestration that Pi's Agent doesn't provide:
+
+```typescript
+session.subscribe((event) => {
+    if (event.type === "turn_end") {
+        turnCount++;
+        if (turnCount >= maxTurns) session.steer("wrap up");
+        if (turnCount >= maxTurns + graceTurns) session.abort();
+    }
+});
+```
 
-- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent-runner.ts`, `src/index.ts`
-- Smell: C (relay-only dependencies)
-- Outcome: `AgentManager` loses 2 fields; `AgentManagerOptions` shrinks from 7 to 5 fields; runner is self-contained
+This uses `session.subscribe()`, `session.steer()`, and `session.abort()` directly.
+No runner involvement needed.
 
-### Step 4: Agent born complete — Agent.run() absorbs startAgent — [#229] ✅
+#### 4. Response collection — Agent's job, simplified
 
-Agent receives `runner`, `worktrees`, and a lifecycle observer at construction.
-Agent creates its own `AbortController` and `NotificationState` from `parentSession.toolCallId` — no external writes.
-`Agent.run()` encapsulates the entire execution lifecycle: worktree setup, runner invocation, session-creation handling, observer wiring, worktree cleanup, and status transitions.
-`startAgent` is deleted from `AgentManager`.
-The `onSessionCreated` callback is removed from `AgentSpawnConfig` — replaced by `AgentLifecycleObserver` passed at construction.
-`SpawnArgs` is deleted — Agent has its config from construction.
-The queue is simplified from `{ id, args }[]` to `string[]` (agent IDs only).
+Agent collects the response directly from `session.messages` after `prompt()` completes.
+The existing `getLastAssistantText()` helper (which reads `session.messages`) already works as a fallback.
+The streaming `collectResponseText()` subscriber can move onto Agent for real-time text collection during the run.
 
-`AgentManager.spawn()` becomes: create complete Agent, put in map, call `agent.run()` or queue the agent ID.
+#### 5. Permission bridge — factory-internal
 
-- Depends on: #228, #231
-- Target: `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`, `src/tools/background-spawner.ts`, `src/tools/foreground-runner.ts`
-- Smell: C (manager orchestrates 10 external touches on Agent) + C (callback flowing through 3 layers)
-- Outcome: Agent owns its entire execution lifecycle; `startAgent`, `SpawnArgs`, `onSessionCreated` callback deleted; zero post-construction writes from `AgentManager`
+The bridge calls (`registerChildSession` / `unregisterChildSession`) bracket `bindExtensions()` inside the factory.
+Since the factory owns `createAgentSession()` and `bindExtensions()`, both bridge calls become factory-internal.
+The factory returns a `cleanup()` function that Agent calls on completion; `cleanup()` handles `unregisterChildSession()` along with any other teardown.
+Agent never sees or imports the permission bridge.
+This naturally resolves the original Phase 16 dependency-inversion concern.
 
-### Step 5: Extract ConcurrencyQueue from AgentManager — [#230]
+### Steps
 
-Extract `queue[]`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()` into a `ConcurrencyQueue` class.
-The queue stores agent IDs — not `SpawnArgs`.
-Drain calls `agent.run()` directly — no worktree setup, no args threading.
-`SettingsManager` talks to the queue directly — `notifyConcurrencyChanged()` is eliminated from `AgentManager`.
+#### Step 1: Extract `WorktreeIsolation` collaborator — [#256]
 
-- Depends on: #229
-- Target: new `src/lifecycle/concurrency-queue.ts`, `src/lifecycle/agent-manager.ts`, `src/index.ts`
-- Smell: A (tangled concerns) + C (cross-concern leak via `notifyConcurrencyChanged`)
-- Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable; queue interface is trivial (agent has everything)
+Create a collaborator that owns the worktree lifecycle: setup, path access, and cleanup.
+Agent receives `worktree?: WorktreeIsolation` instead of `_worktrees` + `_isolation` + managing `worktreeState` internally.
+The null check (`this.worktree?.setup()`) replaces the mode check (`this._isolation !== "worktree"`).
+AgentManager creates the collaborator only when `isolation === "worktree"` and passes it to Agent ready to go.
 
-### Step 6: Agent.resume() with internal observer lifecycle — [#232] ✅
+- Target: new `src/lifecycle/worktree-isolation.ts`, `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`
+- Smell: C (Ask-Don't-Tell — Agent checks `_isolation !== "worktree"` and orchestrates `_worktrees.create()` + `worktreeState.performCleanup()` instead of telling a collaborator)
+- Outcome: Agent loses `_worktrees`, `_isolation` fields + `setupWorktree()` method; `completeRun()`/`failRun()` simplify from 4-line null-check blocks to `this.worktree?.cleanup()`; AgentInit loses 2 fields
 
-Agent has the runner from construction.
-`Agent.resume(prompt, signal)` manages its own observer subscription lifecycle using the same internal wiring as `run()`.
-`AgentManager.resume()` becomes a one-liner delegation to `agent.resume(prompt, signal)` — no manual `subscribeRecordObserver` / try-finally.
+#### Step 2: Extract `ChildSessionFactory` from runner — [#257]
 
-- Depends on: #229
-- Target: `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`
-- Smell: A (duplicated observer subscribe/unsubscribe pattern)
-- Outcome: `AgentManager.resume()` is a 4-line delegation; observer lifecycle is Agent-internal
+Define the factory interface and extract session creation logic from `runAgent()` into a factory class.
+The factory is per-agent: constructed by AgentManager with config (snapshot, prompt, model, maxTurns, isolated, thinkingLevel, parentSession, getRunConfig) already bound.
+The shared `ConcreteAgentRunner` gains a `createFactory(config)` method that produces per-agent factories.
+`runAgent()` delegates to the factory internally during this step (lift-and-shift — Agent is not changed yet).
+Permission bridge calls (`registerChildSession` / `unregisterChildSession`) move inside the factory.
+
+```typescript
+interface ChildSessionFactory {
+    create(cwd?: string): Promise<ChildSessionResult>;
+}
+
+interface ChildSessionResult {
+    session: AgentSession;
+    outputFile?: string;
+    cleanup: () => void;
+}
+```
+
+- Target: new `src/lifecycle/child-session-factory.ts`, `src/lifecycle/agent-runner.ts`
+- Smell: B (conflated concerns — `runAgent()` mixes session creation with session interaction)
+- Outcome: session creation is independently testable; `permission-bridge.ts` imports move from runner to factory; factory interface is narrow (one method)
+
+#### Step 3: Agent owns session lifecycle — run + resume via factory — [#258]
+
+The central step: Agent's `run()` calls `this.factory.create()` to get a session, then interacts with it directly.
+Agent absorbs turn-limit enforcement (subscribe to `turn_end`, steer/abort on limits), response collection (read `session.messages` after prompt), and abort forwarding (wire parent signal to `session.abort()`).
+Agent's `resume()` calls `session.prompt()` directly — the session already exists from the initial run.
+`AgentInit` shrinks: loses `_runner`, `_snapshot`, `_prompt`, `_model`, `_maxTurns`, `_isolated`, `_thinkingLevel`, `_parentSession`, `_getRunConfig` (9 fields); gains `factory` (1 field).
+Combined with Step 1, AgentInit goes from ~20 to ~10 fields.
+
+- Depends on: Step 1 (worktree is a collaborator), Step 2 (factory exists)
+- Target: `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`, `src/tools/foreground-runner.ts`, `src/tools/background-spawner.ts`
+- Smell: C (Agent assembles 9 raw fields into a runner call instead of telling a collaborator) + B (runner conflates creation and interaction)
+- Outcome: Agent owns session interaction; `run()` is coordination not assembly; `resume()` is trivially `session.prompt()`; AgentInit has ~10 fields
+
+#### Step 4: Dissolve runner concept — [#259]
+
+Delete `AgentRunner` interface, `ConcreteAgentRunner` class, `runAgent()` function, `resumeAgent()` function.
+The shared service that creates per-agent factories gets a clean interface (e.g., `SessionFactoryProvider`).
+Clean up dead types: `RunOptions`, `RunResult`, `ResumeOptions` — replaced by the factory interface and direct session interaction.
+Retain `getAgentConversation()` (used by conversation viewer) and `normalizeMaxTurns()` (used by spawn-config).
+
+- Depends on: Step 3
+- Target: `src/lifecycle/agent-runner.ts`, `src/lifecycle/agent.ts`, `src/index.ts`
+- Smell: A (dead code after runner dissolution)
+- Outcome: `agent-runner.ts` shrinks from 467 to ~50 lines (retained helpers only) or is deleted with helpers relocated; the "runner" concept is gone from the architecture
 
 ### Step dependency diagram
 
 ```mermaid
 flowchart LR
-    S1["Step 1<br/>Agent with behavior"]
-    S2["Step 2<br/>async startAgent"]
-    S3["Step 3<br/>runner self-contained"]
-    S4["Step 4<br/>Agent.run()"]
-    S5["Step 5<br/>ConcurrencyQueue"]
-    S6["Step 6<br/>Agent.resume()"]
-
-    S1 --> S2
-    S2 --> S4
+    S1["Step 1<br/>WorktreeIsolation"]
+    S2["Step 2<br/>ChildSessionFactory"]
+    S3["Step 3<br/>Agent owns session"]
+    S4["Step 4<br/>Dissolve runner"]
+
+    S1 --> S3
+    S2 --> S3
     S3 --> S4
-    S4 --> S5
-    S4 --> S6
 ```
 
 ### Tracks
 
-1. **Track A — Foundation** (Step 3): Runner becomes self-contained.
-   No dependencies on other Phase 15 steps; can start immediately.
-2. **Track B — Agent lifecycle** (Steps 4, 6): Agent born complete, owns run + resume.
-   Step 4 depends on Track A + Step 2.
-   Step 6 depends on Step 4.
-3. **Track C — Scheduling** (Step 5): ConcurrencyQueue extraction.
-   Depends on Step 4 (queue drains via `agent.run()`).
+1. **Track A — Foundation** (Steps 1, 2): Extract collaborators.
+   Independent of each other — can proceed in parallel.
+2. **Track B — Integration** (Steps 3, 4): Agent uses collaborators, runner dissolves.
+   Sequential; depends on Track A completing.
 
-## Improvement roadmap (Phase 16 — invert dependencies)
+### Relationship to the original Phase 16 plan
 
-Phase 16 completes the architectural inversion by removing the outbound permission bridge and the `extensions: false` / `isolated` concepts.
-It depends on Phase 15's lifecycle observer (#229) as the replacement mechanism.
+The original Phase 16 ("invert dependencies") targeted permission-bridge removal, `extensions: false` removal, and `isolated` dissolution.
+The permission-bridge concern is resolved by Step 2 — the factory handles registration internally, and Agent never imports the bridge.
+The `extensions`/`isolated` concerns are secondary and may move to a later phase once the collaborator architecture is in place.
 
-Phase 16 is scoped but not yet broken into steps.
-Key changes:
+### Fallow health snapshot (2026-05-28)
 
-1. Remove `permission-bridge.ts` — the outbound coupling to pi-permission-system.
-2. Emit child session lifecycle events via the observer — pi-permission-system and other consumers listen for these events instead of being called.
-3. Remove `extensions: false` — all child sessions load all extensions.
-4. Dissolve or redefine `isolated` — without extension control and tool filtering, the concept either disappears or becomes purely about prompt composition (no skill preloading, no parent context inheritance).
-5. Update pi-permission-system to listen for child session events instead of being registered by the bridge.
+| Metric                 | Value                                                               |
+| ---------------------- | ------------------------------------------------------------------- |
+| Health score           | 78/100 (B) — deductions: hotspots -10, unit size -10, coupling -2.5 |
+| Dead code              | 0 files, 0 exports                                                  |
+| Production duplication | 11 lines (1 internal clone in `agent-config-editor.ts`)             |
+| Test duplication       | 42 clone groups, 661 lines (3.1%)                                   |
+| Hotspot #1             | `index.ts` — 70.0, accelerating (128 commits)                       |
+| Refactoring targets    | 0                                                                   |
 
 ## Improvement roadmap (Phase 17 — extract UI)
 
@@ -879,25 +945,25 @@ Phases 1–5, 7–14 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
-| Phase    | Title                                               | Status                                                                           | History                                                                              |
-| -------- | --------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| 1        | Export SubagentsService API boundary                | Complete                                                                         | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
-| 2        | Remove scheduling subsystem                         | Complete                                                                         | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
-| 3        | Remove group-join, RPC; replace output-file         | Complete                                                                         | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
-| 4        | Implement and publish SubagentsService              | Complete                                                                         | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
-| 5        | Decompose index.ts                                  | Complete                                                                         | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
-| 6        | Extract UI to separate package                      | Deferred → Phase 17                                                              | —                                                                                    |
-| 7        | Encapsulation and dependency narrowing              | Complete                                                                         | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
-| 8        | Testability, display extraction, menu decomposition | Complete                                                                         | [phase-8-testability.md](history/phase-8-testability.md)                             |
-| 9        | Observation consolidation, ctx elimination          | Complete                                                                         | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
-| 10       | Domain organization, bag decomposition, complexity  | Complete                                                                         | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
-| 11       | Closure factories to classes                        | Complete                                                                         | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
-| 12       | Complexity reduction and test fixture extraction    | Complete                                                                         | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
-| 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                              | Planned                                                                          | —                                                                                    |
-| 16       | Invert dependencies                                 | Planned                                                                          | —                                                                                    |
-| 17       | Extract UI to separate package                      | Planned                                                                          | —                                                                                    |
+| Phase | Title                                               | Status              | History                                                                              |
+| ----- | --------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------ |
+| 1     | Export SubagentsService API boundary                | Complete            | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
+| 2     | Remove scheduling subsystem                         | Complete            | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
+| 3     | Remove group-join, RPC; replace output-file         | Complete            | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
+| 4     | Implement and publish SubagentsService              | Complete            | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
+| 5     | Decompose index.ts                                  | Complete            | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
+| 6     | Extract UI to separate package                      | Deferred → Phase 17 | —                                                                                    |
+| 7     | Encapsulation and dependency narrowing              | Complete            | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
+| 8     | Testability, display extraction, menu decomposition | Complete            | [phase-8-testability.md](history/phase-8-testability.md)                             |
+| 9     | Observation consolidation, ctx elimination          | Complete            | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
+| 10    | Domain organization, bag decomposition, complexity  | Complete            | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
+| 11    | Closure factories to classes                        | Complete            | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
+| 12    | Complexity reduction and test fixture extraction    | Complete            | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
+| 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    | Agent collaborator architecture                     | Planned             | —                                                                                    |
+| 17    | Extract UI to separate package                      | Planned             | —                                                                                    |
 
 ### Structural refactoring issues
 
@@ -917,6 +983,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 13           | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                 |
 | 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           | #256, #257, #258, #259                                     | WorktreeIsolation, ChildSessionFactory, Agent owns session, dissolve runner                                                                              |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -949,9 +1016,8 @@ The upstream test suite is run periodically as a regression canary for the agent
 [#217]: https://github.com/gotgenes/pi-packages/issues/217
 [#218]: https://github.com/gotgenes/pi-packages/issues/218
 [#219]: https://github.com/gotgenes/pi-packages/issues/219
-[#227]: https://github.com/gotgenes/pi-packages/issues/227
-[#228]: https://github.com/gotgenes/pi-packages/issues/228
-[#229]: https://github.com/gotgenes/pi-packages/issues/229
-[#230]: https://github.com/gotgenes/pi-packages/issues/230
 [#231]: https://github.com/gotgenes/pi-packages/issues/231
-[#232]: https://github.com/gotgenes/pi-packages/issues/232
+[#256]: https://github.com/gotgenes/pi-packages/issues/256
+[#257]: https://github.com/gotgenes/pi-packages/issues/257
+[#258]: https://github.com/gotgenes/pi-packages/issues/258
+[#259]: https://github.com/gotgenes/pi-packages/issues/259

package/docs/architecture/history/phase-15-domain-model-evolution.md

@@ -0,0 +1,73 @@
+# Phase 15: Domain model evolution
+
+## Summary
+
+Phase 15 evolved `Agent` from a passive state machine (`AgentRecord`) into an object that **owns its entire execution lifecycle**.
+Before Phase 15, `AgentManager` orchestrated everything: calling the runner, handling session creation, wiring observers, and cleaning up worktrees — reaching into Agent 10+ times across `spawn()` and `startAgent()`.
+After Phase 15, Agent is born complete with all dependencies and configuration, owns `run()` and `resume()`, and manages its own observer and worktree lifecycle.
+
+All six steps are closed: [#227], [#228], [#231], [#229], [#230], [#232].
+
+## Key changes
+
+- `AgentRecord` renamed to `Agent` with full behavioral surface.
+- `Agent.run()` encapsulates the entire execution lifecycle: worktree setup, runner invocation, session-creation handling, observer wiring, worktree cleanup, and status transitions.
+- `Agent.resume()` manages its own observer subscription lifecycle.
+- `startAgent` deleted from `AgentManager` — replaced by `agent.run()`.
+- `ConcurrencyQueue` extracted from `AgentManager` — scheduling is independently testable.
+- `SpawnArgs` deleted — the queue stores agent IDs, not config objects.
+- `onSessionCreated` callback replaced by `AgentLifecycleObserver` passed at construction.
+- `exec` and `registry` relay-only dependencies moved from `AgentManager` to `ConcreteAgentRunner`.
+- `AgentManagerOptions` shrunk from 7 to 5 fields.
+
+## Steps
+
+### Step 1: Evolve AgentRecord into Agent with behavior — [#227]
+
+Renamed `AgentRecord` → `Agent`.
+Moved per-agent behavior from `AgentManager` into the agent: `abort()`, `queueSteer()` / `flushPendingSteers()`, `setupWorktree()`.
+
+### Step 2: Convert startAgent to async/await — [#228]
+
+Converted `startAgent` to `async` with `try/catch` and dissolved `RunHandle` into `Agent` methods.
+Agent gained run lifecycle methods: `completeRun`, `failRun`, `wireSignal`, `attachObserver`, `releaseListeners`.
+
+### Step 3: Push exec/registry relay deps to runner construction — [#231]
+
+`exec` and `registry` moved from `AgentManager` to `ConcreteAgentRunner` via `RunnerDeps`.
+`RunContext` shrunk from 4 to 2 per-call fields.
+
+### Step 4: Agent born complete — Agent.run() absorbs startAgent — [#229]
+
+Agent receives `runner`, `worktrees`, and a lifecycle observer at construction.
+`Agent.run()` encapsulates the entire execution lifecycle.
+`startAgent`, `SpawnArgs`, `onSessionCreated` callback deleted.
+
+### Step 5: Extract ConcurrencyQueue from AgentManager — [#230]
+
+Extracted `queue[]`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()` into `ConcurrencyQueue`.
+`AgentManager` lost 3 fields and 3 methods (~40 lines).
+
+### Step 6: Agent.resume() with internal observer lifecycle — [#232]
+
+`Agent.resume(prompt, signal)` manages its own observer subscription lifecycle.
+`AgentManager.resume()` became a one-liner delegation.
+
+## Findings summary
+
+| Finding                                                            | Category     | Status                |
+| ------------------------------------------------------------------ | ------------ | --------------------- |
+| `AgentRecord` anemic — no behavior, manager reaches in 37×         | B: Oversized | ✅ Resolved           |
+| Agent cannot run itself — manager orchestrates 10 external touches | C: Coupling  | ✅ Resolved           |
+| Scheduling tangled into `AgentManager` (3 fields, 3 methods)       | A: Coupling  | ✅ Resolved           |
+| `startAgent` uses `.then()`/`.catch()` instead of async/await      | C: Callbacks | ✅ Resolved           |
+| `onSessionCreated` callback flows through 3 layers                 | C: Callbacks | ✅ Subsumed by Step 4 |
+| `resume()` duplicates observer subscribe/unsubscribe pattern       | A: Redundant | ✅ Resolved           |
+| `exec`/`registry` relay-only deps on `AgentManager`                | C: Coupling  | ✅ Resolved           |
+
+[#227]: https://github.com/gotgenes/pi-packages/issues/227
+[#228]: https://github.com/gotgenes/pi-packages/issues/228
+[#229]: https://github.com/gotgenes/pi-packages/issues/229
+[#230]: https://github.com/gotgenes/pi-packages/issues/230
+[#231]: https://github.com/gotgenes/pi-packages/issues/231
+[#232]: https://github.com/gotgenes/pi-packages/issues/232