@gotgenes/pi-subagents 11.2.0 → 11.4.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.3.0...pi-subagents-v11.4.0) (2026-05-29)
+
+
+### Features
+
+* add child-execution lifecycle event publisher ([4d27c13](https://github.com/gotgenes/pi-packages/commit/4d27c130b4782b7fffb9b61a37e151f8500c55ea))
+* emit child-execution lifecycle events and retire permission-bridge ([c8daee4](https://github.com/gotgenes/pi-packages/commit/c8daee4bcf21f6720d9dbc164282fb6a04e552b1))
+
+## [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()
@@ -275,9 +274,9 @@ src/
 │   ├── concurrency-queue.ts        background agent scheduling with configurable concurrency limit
 │   ├── 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
+│   ├── child-lifecycle.ts          child-execution lifecycle event publisher
 │   ├── 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
@@ -353,15 +352,16 @@ They declare this package as an optional peer dependency and use dynamic import
 - `AgentManager` — spawn, abort, resume, collection management, observer wiring.
 - `ConcurrencyQueue` — background agent scheduling with configurable concurrency limit.
 - `agent-runner` — session creation, turn loop, extension binding.
-- `permission-bridge` — optional cross-extension bridge to `@gotgenes/pi-permission-system`; registers each child session with `SubagentSessionRegistry` before `bindExtensions()` so the permission system detects in-process children deterministically.
-  Scheduled for removal in Phase 16 — replaced by lifecycle events that consumers listen for.
+- `child-lifecycle` — publishes the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) on `pi.events`.
+  Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
+  This replaced the former outbound `permission-bridge` (#261, ADR 0002) — the core no longer looks up a named consumer.
 - `session-config` — pure configuration assembler (extracted from `agent-runner`).
 - `SubagentRuntime` — session-scoped state bag with methods.
 - `ParentSnapshot` — immutable snapshot of parent session state, captured once at spawn time.
 - `record-observer` — session-event observer that updates record statistics without callback threading.
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, skills, environment.
-- Worktree isolation.
+- Worktree isolation — moving to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (ADR 0002).
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
@@ -450,9 +450,34 @@ These are fire-and-forget broadcast events — no request IDs, no reply channels
 
 ## Target architecture
 
-The long-term architectural direction is to make pi-subagents a **minimal core** with inverted dependencies.
-Today, pi-subagents reaches outward to pi-permission-system via a bridge module and owns tool/extension filtering logic that duplicates permission-system responsibilities.
-The target state eliminates this overlap and flips the dependency direction.
+The long-term architectural direction is to make pi-subagents a **minimal orchestrator** with inverted dependencies.
+The core spawns a child session derived from the parent, runs the turn loop, tracks and streams and collects the result, gates concurrency, supports resume, and **publishes its lifecycle**.
+Everything else — permissions, worktree/workspace isolation, UI, telemetry — is an extension that attaches through one of two surfaces and never reaches into the core.
+
+The rationale and the full reasoning chain that led here are recorded in [`docs/decisions/0002-extensions-on-a-minimal-core.md`](../decisions/0002-extensions-on-a-minimal-core.md).
+
+### 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` pre-`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.
 
 ### Core responsibilities (keep)
 
@@ -461,27 +486,34 @@ The target state eliminates this overlap and flips the dependency direction.
 - **Session lifecycle** — create child sessions, bind extensions, run conversation loop, track results.
 - **Concurrency management** — queue, abort, resume, max concurrency.
 - **Recursion guard** — remove pi-subagents' own three tools from child sessions (prevent infinite nesting).
-- **Lifecycle events** — emit events on `pi.events` when child sessions are created, completed, etc.
+  With `isolated` removed, children always load the parent's resources, so the guard becomes unconditional rather than gated on `cfg.extensions`.
+  This is the core defending its own invariant, keyed off its own tool names — not policy.
+- **Lifecycle events** — emit awaited, ordered events when child sessions spawn, are created, complete, and are disposed.
+- **Workspace provider seam** — accept a registered `WorkspaceProvider` and consult it for the child's cwd; default to the parent's cwd when none is registered.
 - **Service API** — publish `SubagentsService` via `Symbol.for()` for cross-extension access.
 
 ### Responsibilities to remove
 
 - **Tool policy** (`disallowed_tools`) — access control belongs in pi-permission-system's `permission:` frontmatter.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
-- **Permission bridge** (`permission-bridge.ts`) — outbound coupling to pi-permission-system.
-  Replaced by lifecycle events that pi-permission-system listens for.
-- **Extension lifecycle control** (`extensions: false`, `isolated`) — extensions provide behavioral layers (permissions, formatting, context management) that benefit all agents.
-  Blanket-disabling them is a blunt instrument with no clear use case; tool restrictions belong in the permission system.
+- **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
+  Git worktrees are one *strategy* for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
+  These move to `@gotgenes/pi-subagents-worktrees`, the first consumer of the workspace provider seam.
+- **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
+  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
 
 ### Composition model
 
-In the target state, pi-subagents publishes events and other packages hook in:
+In the target state, pi-subagents publishes events and a provider seam; other packages hook in:
 
-- **pi-permission-system** listens for child session lifecycle events, applies per-agent policy (allow/ask/deny), gates tool calls at runtime.
+- **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) subscribes to the service API, renders the widget, conversation viewer, and `/agents` menu.
-- **Any future extension** (OTel, auditing, cost tracking) hooks into the same events without pi-subagents knowing.
+- **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
 
-This is achieved across three phases: Phase 14 (strip policy), Phase 16 (invert dependencies), and Phase 17 (extract UI).
+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.
+
+This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert dependencies — extensions on a minimal core), and Phase 17 (extract UI).
 
 ## Current structural analysis
 
@@ -490,13 +522,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 +719,97 @@ 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)
-
-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 |
+## Improvement roadmap (Phase 16 — invert dependencies: extensions on a minimal core)
 
-`Agent.run()` encapsulates the full execution lifecycle:
+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.
+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).
 
-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.
+### Abandoned exploration: agent collaborator architecture
 
-`AgentManager` becomes a collection manager + observer wiring:
+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:
 
-- 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.
+- `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.
 
-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.
+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).
 
-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.
+### Steps
 
-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.
+#### Step 1: Child-execution lifecycle events; retire permission-bridge — [#261] ✅ Delivered
 
-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.
+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`.
 
-### Findings summary
+- 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.
 
-| 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    | ✅       |
+#### Step 2: Define the `WorkspaceProvider` seam — [#262]
 
-### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
+Add the `WorkspaceProvider` / `Workspace` interfaces and `SubagentsService.registerWorkspaceProvider`.
+At run-start the core consults the registered provider (if any) for the child's cwd and a disposal handle; with no provider, the child runs in the parent's cwd.
 
-Rename `AgentRecord` → `Agent` (or wrap it).
-Move per-agent behavior from `AgentManager` into the agent:
+- Land 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.
 
-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.
+#### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263]
 
-- 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
+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.
+Remove `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; drop `isolation` from the spawn API and `SubagentsService`.
 
-### Step 2: Convert startAgent to async/await — [#228] ✅ Complete
+- Supersedes #256.
+  New package registered in `release-please-config.json`; peer-depends on `@gotgenes/pi-subagents`.
+- Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
 
-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.
+#### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264]
 
-- 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
+Children always load the parent's extensions and skills; the recursion guard becomes unconditional.
+Deny-at-use (the in-child permission layer) covers tool restriction; prevent-load is left as a latent provider seam (not shipped).
 
-### Step 3: Push exec/registry relay deps to runner construction — [#231] ✅
+- Depends on: Step 1 (deny-at-use over events).
+- Outcome: the `isolated`/`extensions`/`noSkills` axis is gone; one fewer conditional in the guard.
 
-`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.
+#### Step 5: Born-complete child execution; dissolve the runner — [#265]
 
-- 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
+With the cwd resolved through the provider seam (not relayed by `Agent`), child-session creation produces a born-complete execution (`{ session, outputFile?, dispose() }`).
+`Agent` owns session interaction directly (prompt, steer, abort, resume, turn limits, response collection); `runAgent` / `resumeAgent` / `ConcreteAgentRunner` / `RunOptions` / `RunResult` dissolve.
+Retain `getAgentConversation()` and `normalizeMaxTurns()`.
 
-### 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 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; queue interface is trivial (agent has everything)
-
-### Step 6: Agent.resume() with internal observer lifecycle — [#232] ✅
-
-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: #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
+- 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/>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
-    S3 --> S4
+    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
-    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()`).
-
-## 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 lifecycle observer (#229) as the replacement mechanism.
-
-Phase 16 is scoped but not yet broken into steps.
-Key changes:
-
-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.
+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.
 
 ## Improvement roadmap (Phase 17 — extract UI)
 
@@ -879,44 +823,46 @@ 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    | Invert dependencies (extensions on a minimal core)  | Planned             | [ADR 0002](../decisions/0002-extensions-on-a-minimal-core.md)                        |
+| 17    | Extract UI to separate package                      | Planned             | —                                                                                    |
 
 ### Structural refactoring issues
 
-| Phase              | Issue                                                      | Summary                                                                                                                                                  |
-| ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Foundation         | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                                                     |
-| Core decomposition | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                                                    |
-| Interface polish   | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                                              |
-| Features           | #61                                                        | JSONL session transcripts                                                                                                                                |
-| AgentManager       | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                                            |
-| Encapsulation      | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping                           |
-| Testability        | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                        |
-| Observation/ctx    | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                            |
-| Phase 10           | #164, #165, #166, #167, #168, #169, #170, #171, #172       | Domain directories, ResolvedSpawnConfig, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult, content-items |
-| Phase 11           | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                         |
-| 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, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                               |
+| Phase                | Issue                                                      | Summary                                                                                                                                                    |
+| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foundation           | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                                                       |
+| Core decomposition   | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                                                      |
+| Interface polish     | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                                                |
+| Features             | #61                                                        | JSONL session transcripts                                                                                                                                  |
+| AgentManager         | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                                              |
+| Encapsulation        | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping                             |
+| Testability          | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                          |
+| Observation/ctx      | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                              |
+| Phase 10             | #164, #165, #166, #167, #168, #169, #170, #171, #172       | Domain directories, ResolvedSpawnConfig, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult, content-items   |
+| Phase 11             | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                           |
+| 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, #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)                                                                      |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -949,9 +895,4 @@ 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