@gotgenes/pi-subagents 10.2.0 → 11.0.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.2.1...pi-subagents-v11.0.0) (2026-05-28)
+
+
+### ⚠ BREAKING CHANGES
+
+* AgentSpawnConfig.onSessionCreated is replaced by AgentSpawnConfig.observer (AgentLifecycleObserver). Callers that used onSessionCreated must use observer.onSessionCreated instead.
+
+### Features
+
+* add Agent.run() encapsulating full execution lifecycle ([#229](https://github.com/gotgenes/pi-packages/issues/229)) ([780cb72](https://github.com/gotgenes/pi-packages/commit/780cb72ea7a6981ee283a9de791d5fb65cabaa28))
+* add AgentLifecycleObserver interface ([#229](https://github.com/gotgenes/pi-packages/issues/229)) ([c0f08a4](https://github.com/gotgenes/pi-packages/commit/c0f08a40ce36afa3a7876345709db56e192a893b))
+* AgentManager.spawn() creates complete Agent, deletes startAgent ([#229](https://github.com/gotgenes/pi-packages/issues/229)) ([4d83c6d](https://github.com/gotgenes/pi-packages/commit/4d83c6d583df905054066ed841a67795753928d4))
+* expand AgentInit with run-config, deps, and self-created AbortController ([#229](https://github.com/gotgenes/pi-packages/issues/229)) ([e522f23](https://github.com/gotgenes/pi-packages/commit/e522f23232e4b447ffa39e36a19cf70c7e5cbaae))
+
+
+### Documentation
+
+* mark Phase 15 Step 4 complete, update architecture ([#229](https://github.com/gotgenes/pi-packages/issues/229)) ([29b0da8](https://github.com/gotgenes/pi-packages/commit/29b0da8435aaa5be51fc073612fc09d9a22004bc))
+* plan Agent born complete — Agent.run() absorbs startAgent ([#229](https://github.com/gotgenes/pi-packages/issues/229)) ([c1588b5](https://github.com/gotgenes/pi-packages/commit/c1588b58ae697d22db1bf30b8997e5502626c33b))
+* **retro:** add planning stage notes for issue [#229](https://github.com/gotgenes/pi-packages/issues/229) ([21243d5](https://github.com/gotgenes/pi-packages/commit/21243d564691daab5dcddff23809a82db56c0660))
+* **retro:** add retro notes for issue [#231](https://github.com/gotgenes/pi-packages/issues/231) ([249cce0](https://github.com/gotgenes/pi-packages/commit/249cce0e1c7642d8c85da67e8f3c92f210735e7b))
+* **retro:** add TDD stage notes for issue [#229](https://github.com/gotgenes/pi-packages/issues/229) ([047cd9e](https://github.com/gotgenes/pi-packages/commit/047cd9e2816f6a25d93bbba33fc93b228989f272))
+
+## [10.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.2.0...pi-subagents-v10.2.1) (2026-05-27)
+
+
+### Documentation
+
+* **pi-subagents:** renumber Phase 15 steps to match execution order ([598bb65](https://github.com/gotgenes/pi-packages/commit/598bb653ac8b63756e8c00dfcf19d3167e2dbc37))
+* **pi-subagents:** revise Phase 15 roadmap for Agent-born-complete vision ([e04583e](https://github.com/gotgenes/pi-packages/commit/e04583e75bfc1314674a6f3181762a26733fb830))
+* plan push exec/registry relay deps to runner construction ([#231](https://github.com/gotgenes/pi-packages/issues/231)) ([646b4d5](https://github.com/gotgenes/pi-packages/commit/646b4d5085e0f7d36a397b43b3b46e0537c3141f))
+* **retro:** add planning stage notes for issue [#231](https://github.com/gotgenes/pi-packages/issues/231) ([dc0daee](https://github.com/gotgenes/pi-packages/commit/dc0daee634c17cf2a40336e27f551bfa2ce0e249))
+* **retro:** add retro notes for issue [#228](https://github.com/gotgenes/pi-packages/issues/228) ([d5b563b](https://github.com/gotgenes/pi-packages/commit/d5b563b6484cbd6a89cd7e9e87ebd431aed128fc))
+* **retro:** add TDD stage notes for issue [#231](https://github.com/gotgenes/pi-packages/issues/231) ([28094ae](https://github.com/gotgenes/pi-packages/commit/28094ae812141ea1c93a22be50ed29d31b7a979a))
+* update architecture for runner self-contained ([#231](https://github.com/gotgenes/pi-packages/issues/231)) ([80dd339](https://github.com/gotgenes/pi-packages/commit/80dd339d7dee9b312b52af2b74756c5748619a49))
+
 ## [10.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.1.0...pi-subagents-v10.2.0) (2026-05-27)
 
 

package/docs/architecture/architecture.md

@@ -266,9 +266,9 @@ src/
 │   └── session-dir.ts              session directory derivation
 │
 ├── lifecycle/                      agent execution and state tracking
-│   ├── agent-manager.ts            spawn, queue, abort, resume, concurrency
+│   ├── agent-manager.ts            collection manager + concurrency controller
 │   ├── agent-runner.ts             session creation, turn loop, tool filtering
-│   ├── agent.ts                    status state machine, per-agent behavior (abort, steer, worktree)
+│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, worktree)
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
 │   ├── permission-bridge.ts        optional bridge to pi-permission-system registry
@@ -599,23 +599,21 @@ export interface ParentSessionInfo {
 
 `AgentSpawnConfig` now carries `parentSession?: ParentSessionInfo` instead of three flat optional fields.
 
-#### RunOptions (12 fields → extract RunContext) — done ([#169][169])
+#### RunOptions (12 fields → extract RunContext) — done ([#169][169]), updated by [#231]
 
-The `RunOptions` bag mixes execution parameters with context information.
-`RunContext` was extracted and nested as `RunOptions.context`:
+`RunContext` was extracted and nested as `RunOptions.context` in #169.
+Issue #231 moved the two static dependencies (`exec`, `registry`) to `RunnerDeps` on `ConcreteAgentRunner`, leaving `RunContext` with only per-call fields:
 
 ```typescript
-/** Parent execution context — where/who is running. */
+/** Per-call execution context — fields that vary per spawn. */
 export interface RunContext {
-  exec: ShellExec;
-  registry: AgentConfigLookup;
   cwd?: string;
   parentSession?: ParentSessionInfo;
 }
 ```
 
 The remaining `RunOptions` fields (`model`, `maxTurns`, `signal`, `isolated`, `thinkingLevel`, `defaultMaxTurns`, `graceTurns`, `onSessionCreated`) are genuine execution parameters.
-`RunOptions` now has 9 fields: 1 nested `context: RunContext` plus 8 flat execution fields.
+`RunOptions` now has 9 fields: 1 nested `context: RunContext` (2 per-call fields) plus 8 flat execution fields.
 
 #### SessionConfig (11 fields → extract ToolFilterConfig) — done ([#168][168])
 
@@ -686,25 +684,66 @@ See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
 
 ## Improvement roadmap (Phase 15 — domain model evolution)
 
-Phase 15 addresses the anemic domain model in the lifecycle layer.
-`AgentRecord` is a data bag — identity, status transitions, and stats — but no behavior.
-`AgentManager` reaches into records 37 times, doing work that belongs on the agent.
-Per-agent state (pending steers, abort logic, run lifecycle) was scattered across the manager, `RunHandle`, and a manager-level Map.
-`RunHandle` has been dissolved into `Agent` methods — see Step 2.
+Phase 15 evolves `Agent` from a passive state machine into an object that **owns its entire execution lifecycle**.
+
+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.
+
+The remaining steps address this by making **Agent born complete**: constructed with all dependencies and configuration, owning its entire execution lifecycle.
+
+### Architecture target
+
+Agent receives three concerns at construction:
+
+| 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 |
+
+`Agent.run()` encapsulates the full execution lifecycle:
+
+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.
+
+`AgentManager` becomes a collection manager + concurrency controller:
+
+- 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.
+
+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.
+
+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.
+
+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.
 
 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.
 
 ### Findings summary
 
-| Finding                                                           | Category     | Impact | Risk | Priority |
-| ----------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
-| `AgentRecord` is anemic — no behavior, manager reaches in 37×     | B: Oversized | 5      | 3    | 15       |
-| Scheduling tangled into `AgentManager` (3 fields, 3 methods)      | A: Coupling  | 4      | 2    | 12       |
-| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~ | C: Callbacks | 3      | 2    | ✅       |
-| `onSessionCreated` callback flows through 3 layers                | C: Callbacks | 3      | 2    | 10       |
-| `resume()` duplicates observer subscribe/unsubscribe pattern      | A: Redundant | 2      | 1    | 8        |
-| `exec`/`registry` relay-only deps on `AgentManager`               | C: Coupling  | 2      | 1    | 6        |
+| 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    | 15       |
+| Scheduling tangled into `AgentManager` (3 fields, 3 methods)       | A: Coupling  | 4      | 2    | 12       |
+| ~~`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    | 8        |
+| `exec`/`registry` relay-only deps on `AgentManager`                | C: Coupling  | 2      | 1    | 6        |
 
 ### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
 
@@ -731,43 +770,55 @@ Worktree setup was hoisted to callers (`spawn`, `drainQueue`) to preserve the sy
 - Smell: C (raw promise callbacks)
 - Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`; `RunHandle` deleted; Agent owns run lifecycle
 
-### Step 3: Replace onSessionCreated callback with observer method — [#229]
+### Step 3: Push exec/registry relay deps to runner construction — [#231] ✅
 
-Add `onSessionCreated(agent, session)` to `AgentManagerObserver`.
-Remove the `onSessionCreated` callback from `AgentSpawnConfig`.
-Tool-layer code subscribes via the observer pattern instead of passing callbacks through the spawn config.
+`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.
 
-- Target: `src/lifecycle/agent-manager.ts`, `src/tools/background-spawner.ts`, `src/tools/foreground-runner.ts`
-- Smell: C (callback flowing through 3 layers)
-- Outcome: `AgentSpawnConfig` loses one callback field; session notification uses the observer pattern
+- 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
+
+### Step 4: Agent born complete — Agent.run() absorbs startAgent — [#229] ✅
+
+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).
+
+`AgentManager.spawn()` becomes: create complete Agent, put in map, call `agent.run()` or queue the agent ID.
+
+- 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`
 
-### Step 4: Extract ConcurrencyQueue from AgentManager — [#230]
+### Step 5: Extract ConcurrencyQueue from AgentManager — [#230]
 
 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`.
 
+- 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
-
-### Step 5: Push exec/registry relay deps to runner construction — [#231]
-
-`AgentManager` receives `exec` and `registry` in its constructor but only relays them to `runner.run()` via `context`.
-Move them to `ConcreteAgentRunner` construction.
-
-- 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
+- Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable; queue interface is trivial (agent has everything)
 
-### Step 6: Unify resume() with Agent run lifecycle methods — [#232]
+### Step 6: Agent.resume() with internal observer lifecycle — [#232]
 
-After #228 dissolved `RunHandle` into Agent methods (`completeRun`, `failRun`, `releaseListeners`), `resume()` on `AgentManager` becomes a short delegation to `agent.resume(runner, prompt, signal)`.
-The agent manages its own observer subscription lifecycle using the same methods that `startAgent` uses.
+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.
 
-- Depends on: #227, #228
-- Target: `src/lifecycle/agent-manager.ts`
+- Depends on: #229
+- Target: `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`
 - Smell: A (duplicated observer subscribe/unsubscribe pattern)
-- Outcome: no manual `subscribeRecordObserver` / try-finally in the manager
+- Outcome: `AgentManager.resume()` is a 4-line delegation; observer lifecycle is Agent-internal
 
 ### Step dependency diagram
 
@@ -775,28 +826,32 @@ The agent manages its own observer subscription lifecycle using the same methods
 flowchart LR
     S1["Step 1<br/>Agent with behavior"]
     S2["Step 2<br/>async startAgent"]
-    S3["Step 3<br/>onSessionCreated observer"]
-    S4["Step 4<br/>ConcurrencyQueue"]
-    S5["Step 5<br/>relay deps"]
-    S6["Step 6<br/>resume unification"]
+    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
-    S1 --> S6
-    S2 --> S6
-    S3 ~~~ S4
-    S4 ~~~ S5
+    S2 --> S4
+    S3 --> S4
+    S4 --> S5
+    S4 --> S6
 ```
 
 ### Tracks
 
-1. **Track A — Domain model** (Steps 1, 2, 6): Agent with behavior, async runs, resume unification.
-   Sequential — each depends on the previous.
-2. **Track B — Decoupling** (Steps 3, 4, 5): independent, can proceed in parallel with Track A.
+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()`).
 
 ## Improvement roadmap (Phase 16 — invert dependencies)
 
 Phase 16 completes the architectural inversion by removing the outbound permission bridge and the `extensions: false` / `isolated` concepts.
-It depends on Phase 15's observer pattern (#229) as the replacement mechanism.
+It depends on Phase 15's lifecycle observer (#229) as the replacement mechanism.
 
 Phase 16 is scoped but not yet broken into steps.
 Key changes:
@@ -856,7 +911,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 12           | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                  |
 | 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, #229, #230, #231, #232                         | Agent domain model, async startAgent, onSessionCreated observer, ConcurrencyQueue, relay deps, resume unification                                        |
+| Phase 15           | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                               |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.