@gotgenes/pi-subagents 11.2.0 → 11.4.0

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

package/docs/decisions/0002-extensions-on-a-minimal-core.md

@@ -0,0 +1,98 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0002 — Workspaces and permissions are extensions on a minimal core
+
+## Status
+
+Accepted.
+Supersedes the "agent collaborator architecture" framing of Phase 16 (an abandoned exploration) and the work shipped under it: issue #256 (`WorktreeIsolation` as an `Agent` collaborator) and issue #257 (`ChildSessionFactory` extraction, parked at planning).
+Reclaims Phase 16's original intent — "invert dependencies" — and extends it to evict worktree isolation from the core.
+
+## Context
+
+The core question that triggered this decision: a single-method `ChildSessionFactory` with a `create(cwd?)` method (planned for #257) looked like it wanted to be a function, and the `cwd` parameter was late-bound.
+Pulling that thread exposed progressively more rudimentary issues.
+
+1. `cwd` is late-bound because `WorktreeIsolation.setup()` is called lazily inside `Agent.run()`, after construction — a two-phase `construct-then-setup()` that violates design principle 8 ("Construct complete").
+2. The worktree is *ready* only at dequeue (a concurrency slot is held and `git worktree add` has run).
+   "Construct when ready" therefore means constructing the worktree at run-start, not at spawn — which dissolves the lazy `setup()` and makes `cwd` knowable at construction.
+3. The worktree and the child session share one lifespan: both are born at run-start and torn down at completion (the worktree's cleanup saves a branch; the session is disposed).
+   Resources with one lifetime are one resource, not sibling collaborators that `Agent` must sequence.
+   The `create(cwd?)` parameter only existed because we split one run-scoped resource (the worktree) out and made `Agent` relay its output back in.
+4. Worktrees are not intrinsic to what makes subagents useful.
+   The maintainer never uses them (WIP-of-1, trunk-based, CI/CD).
+   Git worktree isolation is one *strategy* for answering "where does this child run, and what brackets the run?"
+   — a container, a throwaway tmpdir, or a remote sandbox are others.
+   The core needs only *a working directory and a disposal hook*; the default (the parent's cwd, no setup/teardown) is always correct.
+5. This mirrors Phase 14, which evicted tool/extension *policy* (`disallowed_tools`, `extensions` filtering) to `@gotgenes/pi-permission-system`.
+   Worktrees are *environment* policy; they belong outside the core for the same reason.
+
+Permissions and workspaces are orthogonal concerns that must compose as independent extensions on the core, never knowing about each other.
+
+## Decision
+
+pi-subagents is a minimal orchestrator: it 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 attaches through exactly two extension surfaces, distinguished by the direction of information flow.
+
+### Two extension surfaces
+
+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** (it 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).
+
+Permissions are observational: the core does not enforce policy; it publishes the child's identity at the pre-bind instant so the permission extension (loaded in the child) can detect "am I a subagent?"
+and gate tool calls at runtime.
+Workspaces are generative: the core cannot default the cwd away when an isolation strategy is requested, so the provider hands it back.
+
+### 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 not extensibility — it is a speculative abstraction that taxes every reader, and `fallow` flags it as dead.
+Latent extensibility (the design can host the seam additively) is the deliverable; a vacant hook is not.
+
+### What leaves the core
+
+- **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) → a new package, `@gotgenes/pi-subagents-worktrees`, that implements the workspace provider and owns the git plumbing and the "saved to branch" result.
+- **`permission-bridge.ts`** → retired.
+  The core stops reaching *out* to `Symbol.for("@gotgenes/pi-permission-system:service")` and instead *emits* lifecycle events the permission system subscribes to.
+- **`isolated` / `extensions: false` / `noSkills`** → removed.
+  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 cannot be reduced to observation, so it is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
+
+### What stays in the core (not policy)
+
+- The **recursion guard** (stripping the core's own `subagent` / `get_subagent_result` / `steer_subagent` tools from children).
+  It defends the core's own invariant — a subagent must not recursively spawn — keyed off the core's own tool names.
+  With `isolated` gone, children always load the parent's resources, so the guard becomes unconditional rather than gated on `cfg.extensions`.
+
+### 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.
+Permissions depend only on the core's events; workspaces depend only on the core's provider seam; the core depends on neither.
+
+## Consequences
+
+- The "agent collaborator architecture" Phase 16 (give `Agent` a worktree collaborator + a session factory) is abandoned.
+  #256 is superseded (worktree was placed in the wrong layer); #257 is parked (it polished a subsystem slated for eviction).
+- A new package `@gotgenes/pi-subagents-worktrees` is introduced; the core spawn API drops `isolation` and `isolated`.
+- `permission-bridge.ts` is removed; `@gotgenes/pi-permission-system` migrates from a published-service lookup to lifecycle-event subscription, which requires the core to emit an awaited, ordered `session-created` event before `bindExtensions()`.
+  Confirming Pi's event model supports awaited pre-bind emission is the first investigation of the reclaimed phase.
+- Once the cwd is resolved through the provider seam rather than relayed by `Agent`, child-session creation can construct a born-complete execution and the "runner" concept dissolves — recovering the structural goal of the abandoned collaborator steps by a cleaner route.
+- The reclaimed Phase 16 roadmap and step issues live in [`docs/architecture/architecture.md`](../architecture/architecture.md).

package/docs/plans/0256-extract-worktree-isolation.md

@@ -0,0 +1,256 @@
+---
+issue: 256
+issue_title: "Extract WorktreeIsolation collaborator"
+---
+
+# Extract WorktreeIsolation collaborator
+
+## Problem Statement
+
+`Agent` currently holds three separate worktree-related members — `_worktrees` (a shared `WorktreeManager`), `_isolation` (the `IsolationMode`), and `worktreeState` (a `WorktreeState` phase object) — and orchestrates the worktree internals itself.
+It checks `this._isolation !== "worktree"`, calls `this._worktrees.create()`, constructs the `WorktreeState`, and drives `worktreeState.performCleanup(this._worktrees, ...)` from both `completeRun()` and `failRun()`.
+This is Ask-Don't-Tell: `Agent` asks its collaborators for raw materials and does the worktree work itself rather than telling a single collaborator to handle its own lifecycle.
+
+This is Phase 16, Step 1 of the agent-collaborator architecture (`docs/architecture/architecture.md`).
+
+## Goals
+
+- Introduce a `WorktreeIsolation` collaborator that owns the entire worktree lifecycle: `setup()`, `path` access, and `cleanup(description)`.
+- `AgentManager` constructs the collaborator only when `isolation === "worktree"` and passes it to `Agent` ready to go.
+- Replace `Agent`'s mode check (`this._isolation !== "worktree"`) with a null check (`this.worktree?.setup()`).
+- Fold the existing `WorktreeState` value object into `WorktreeIsolation` (delete `worktree-state.ts`), matching the architecture's target table which lists `WorktreeIsolation` as absorbing `worktrees` + `isolation` + `worktreeState`.
+- Shrink `Agent`: remove `_worktrees`, `_isolation`, `worktreeState`, and `setupWorktree()`; add a single `worktree?: WorktreeIsolation` collaborator.
+
+This change is **not** breaking to any published API — `WorktreeManager`, `WorktreeState`, and `AgentInit` are all internal to the package.
+
+## Non-Goals
+
+- No changes to the runner, session creation, or `ChildSessionFactory` — that is Step 2 (#257).
+- No changes to `Agent.run()`'s session-interaction logic, turn-limit enforcement, or response collection — that is Step 3 (#258).
+- No changes to the low-level git plumbing in `worktree.ts` (`createWorktree`, `cleanupWorktree`, `pruneWorktrees`, `GitWorktreeManager`) — those free functions and the `WorktreeManager` interface stay as-is.
+- No change to the `worktreeResult` shape exposed by `service-adapter.ts` — only the access path changes.
+
+## Background
+
+Relevant modules:
+
+- `src/lifecycle/agent.ts` — the `Agent` class.
+  Holds `_worktrees: WorktreeManager`, `_isolation: IsolationMode`, `worktreeState?: WorktreeState`; defines `setupWorktree()`; reads `this.worktreeState?.path` for the runner `cwd`; drives cleanup in `completeRun()` / `failRun()`.
+- `src/lifecycle/agent-manager.ts` — `AgentManager` holds the shared `WorktreeManager` (`this.worktrees`), passes `worktrees` + `isolation` into each `Agent` via `AgentInit`, and calls `this.worktrees.prune()` on `dispose()`.
+- `src/lifecycle/worktree.ts` — `WorktreeManager` interface + `GitWorktreeManager` impl + free functions.
+  `WorktreeManager.cleanup(wt, description)` mutates `wt.branch` in place (in `cleanupWorktree`), so the object passed must carry a writable `branch`.
+- `src/lifecycle/worktree-state.ts` — `WorktreeState`: holds `path`/`branch`, tracks `cleanupResult`, exposes `performCleanup(worktrees, description)`.
+  Re-exports `WorktreeCleanupResult` and `WorktreeInfo` (no external consumer imports those two from this path — verified by grep).
+- `src/service/service-adapter.ts:131` — reads `record.worktreeState?.cleanupResult` to populate `worktreeResult`.
+- `src/index.ts:167` — constructs `new GitWorktreeManager(process.cwd())` and passes it to `AgentManager`.
+
+AGENTS.md constraints that apply:
+
+- This package targets ES2024; Biome (not Prettier) formats.
+- Tests use `vi.hoisted(...)` patterns; the full vitest suite must pass before publishing.
+- When a barrel/module gains exports, verify a consumer imports them — fallow flags speculative re-exports.
+  Here we are removing a module, not adding one, so the risk is dangling imports rather than dead exports.
+
+## Design Overview
+
+### Decision model
+
+`AgentManager` owns the shared `WorktreeManager` (one instance, repo-root-bound).
+Per spawn, when `isolation === "worktree"`, it constructs a per-agent `WorktreeIsolation` bound to that `WorktreeManager` and the agent id, and hands it to `Agent`.
+When isolation is not requested, no collaborator is created and `Agent.worktree` is `undefined`.
+
+`Agent` no longer knows the isolation mode or the `WorktreeManager`.
+The presence/absence of the collaborator *is* the mode: `this.worktree?.setup()` and `this.worktree?.cleanup(...)`.
+
+### WorktreeIsolation shape
+
+```typescript
+// src/lifecycle/worktree-isolation.ts
+import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
+
+export class WorktreeIsolation {
+	private _info?: WorktreeInfo;
+	private _cleanupResult?: WorktreeCleanupResult;
+
+	constructor(
+		private readonly worktrees: WorktreeManager,
+		private readonly agentId: string,
+	) {}
+
+	/** Absolute worktree path — undefined before setup(). */
+	get path(): string | undefined {
+		return this._info?.path;
+	}
+
+	/** Cleanup outcome — undefined until cleanup() runs. */
+	get cleanupResult(): WorktreeCleanupResult | undefined {
+		return this._cleanupResult;
+	}
+
+	/**
+	 * Create the git worktree and store its info.
+	 * Throws on failure (strict isolation — no silent fallback).
+	 */
+	setup(): void {
+		const wt = this.worktrees.create(this.agentId);
+		if (!wt) {
+			throw new Error(
+				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+				"Initialize git and commit at least once, or omit `isolation`.",
+			);
+		}
+		this._info = wt;
+	}
+
+	/** Perform cleanup and record the result. No-op ({ hasChanges: false }) if setup never ran. */
+	cleanup(description: string): WorktreeCleanupResult {
+		if (!this._info) return { hasChanges: false };
+		const result = this.worktrees.cleanup(this._info, description);
+		this._cleanupResult = result;
+		return result;
+	}
+}
+```
+
+Notes:
+
+- `_info` is a mutable `WorktreeInfo`, so `WorktreeManager.cleanup` mutating `branch` in place keeps working (the same behavior `WorktreeState` relied on today).
+- The `missing worktrees dependency` error from `setupWorktree()` disappears: the collaborator is only ever created with a `WorktreeManager`, so that defensive branch is structurally impossible.
+- `cleanup()` returns `{ hasChanges: false }` when `setup()` never ran, so `Agent`'s `completeRun()`/`failRun()` can call it unconditionally via the optional-chain without a separate guard.
+
+### Agent call sites (Tell-Don't-Ask)
+
+`Agent.run()` setup:
+
+```typescript
+try {
+	this.worktree?.setup();   // was: this.setupWorktree() with internal mode check
+} catch (err) {
+	this.markError(err);
+	this.releaseListeners();
+	this.observer?.onRunFinished?.(this);
+	return;
+}
+// ...
+cwd: this.worktree?.path,   // was: this.worktreeState?.path
+```
+
+`Agent.completeRun()`:
+
+```typescript
+let finalResult = result.responseText;
+const wtResult = this.worktree?.cleanup(this.description);
+if (wtResult?.hasChanges && wtResult.branch) {
+	finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+}
+```
+
+`Agent.failRun()`:
+
+```typescript
+try {
+	this.worktree?.cleanup(this.description);
+} catch (cleanupErr) {
+	debugLog("cleanupWorktree on agent error", cleanupErr);
+}
+```
+
+`AgentManager.spawn()`:
+
+```typescript
+const worktree = options.isolation === "worktree"
+	? new WorktreeIsolation(this.worktrees, id)
+	: undefined;
+const record = new Agent({ /* ... */, worktree /* was: worktrees + isolation */ });
+```
+
+The reach-through `agent.worktreeState.cleanupResult` in `service-adapter.ts` becomes `agent.worktree?.cleanupResult` — the collaborator owns the result, so this is a single-hop access, not a reach-through into a phase object.
+
+### Edge cases
+
+- Isolation not requested → `worktree` is `undefined` → `setup()`/`cleanup()` are skipped via optional chaining; behavior identical to today's `_isolation !== "worktree"` early-return.
+- `create()` returns `undefined` (not a git repo) → `setup()` throws; `Agent.run()` catches, marks error, releases listeners, fires `onRunFinished`.
+  The existing AgentManager regression test (worktree fails loud, no silent fallback) is preserved.
+- Cleanup throws in `failRun()` → caught and logged best-effort, identical to today.
+
+## Module-Level Changes
+
+- New: `src/lifecycle/worktree-isolation.ts` — the `WorktreeIsolation` class (shape above).
+- Changed: `src/lifecycle/agent.ts`
+  - Remove imports of `WorktreeManager` (type) and `WorktreeState`; add import of `WorktreeIsolation`.
+  - `AgentInit`: remove `worktrees?: WorktreeManager` and `isolation?: IsolationMode`; add `worktree?: WorktreeIsolation`.
+    (`IsolationMode` may remain imported if still referenced elsewhere in the file; grep confirms it is only used for the removed field — remove the now-unused import.)
+  - Remove instance fields `_worktrees`, `_isolation`, `worktreeState`; add `worktree?: WorktreeIsolation`.
+  - Remove the `setupWorktree()` method.
+  - Constructor: replace the `_worktrees`/`_isolation` assignments with `this.worktree = init.worktree`.
+  - `run()`: `this.worktree?.setup()`; `cwd: this.worktree?.path`.
+  - `completeRun()` / `failRun()`: replace the 4-line `worktreeState && _worktrees` blocks with `this.worktree?.cleanup(this.description)`.
+  - Update the file header doc comment (lists `worktreeState` as a phase-specific collaborator).
+- Changed: `src/lifecycle/agent-manager.ts`
+  - Import `WorktreeIsolation`.
+  - `spawn()`: construct the per-agent `WorktreeIsolation` when `options.isolation === "worktree"`; pass `worktree` to `Agent` instead of `worktrees` + `isolation`.
+  - Keep `this.worktrees` field, `AgentManagerOptions.worktrees`, and the `dispose()` → `this.worktrees.prune()` call unchanged.
+- Changed: `src/service/service-adapter.ts`
+  - `record.worktreeState?.cleanupResult` → `record.worktree?.cleanupResult`.
+- Removed: `src/lifecycle/worktree-state.ts` (folded into `WorktreeIsolation`).
+- Doc updates (`docs/architecture/architecture.md`):
+  - Class diagram (line ~115): `+worktreeState?: WorktreeState` → `+worktree?: WorktreeIsolation`; remove the `+setupWorktree(...)` method line.
+  - Layout listing (lines ~279–280): replace `worktree-state.ts  worktree phase state` with `worktree-isolation.ts  worktree lifecycle collaborator`.
+- Doc update (`.pi/skills/package-pi-subagents/SKILL.md`): Lifecycle domain row — replace `worktree-state.ts` with `worktree-isolation.ts` (module count stays 9).
+
+Symbols removed and their consumers (grepped across `src/` and `test/`):
+
+- `WorktreeState` (class): `src/lifecycle/agent.ts` (removed in this plan), `test/lifecycle/agent.test.ts`, `test/service/service-adapter.test.ts`, `test/lifecycle/worktree-state.test.ts` — all updated/removed below.
+- `Agent.setupWorktree()`: only `test/lifecycle/agent.test.ts` — removed below.
+- `Agent.worktreeState`: `service-adapter.ts` + several tests — all migrated to `worktree`.
+- The `WorktreeCleanupResult`/`WorktreeInfo` re-exports from `worktree-state.ts`: no external importer (verified) — safe to drop.
+
+## Test Impact Analysis
+
+1. New unit tests enabled by the extraction: `WorktreeIsolation` is now independently testable without an `Agent` — `worktree-isolation.test.ts` covers `setup()` (success stores path; failure throws), `cleanup()` (delegates to `worktrees.cleanup` with stored info + description, records `cleanupResult`; no-op before setup), and `path`/`cleanupResult` getters.
+   These absorb the existing `worktree-state.test.ts` coverage (constructor, `recordCleanup`, `performCleanup`) at the same granularity.
+2. Existing tests that become redundant / simplified: `test/lifecycle/worktree-state.test.ts` is removed (its behavior is covered by the new collaborator tests).
+   The `Agent — setupWorktree` describe block in `agent.test.ts` is removed (the method is gone); its intent migrates to the `WorktreeIsolation` unit tests plus the existing `Agent.run() — worktree` integration tests.
+3. Existing tests that must stay (genuinely exercise the layer):
+   `test/lifecycle/worktree.test.ts` (git plumbing + `GitWorktreeManager`) is untouched.
+   `Agent.run() — worktree` integration tests stay but switch their assertions from `agent.worktreeState` to `agent.worktree` and construct the agent with a `WorktreeIsolation`.
+   `agent-manager.test.ts` worktree tests stay but assert via `record.worktree?.path` / `record.worktree?.cleanupResult`.
+
+## TDD Order
+
+1. Add `WorktreeIsolation` with unit tests — new module, no consumers yet.
+   Surface: `test/lifecycle/worktree-isolation.test.ts`.
+   Covers: `setup()` success/failure, `cleanup()` delegation + result recording + pre-setup no-op, `path`/`cleanupResult` getters (migrating `worktree-state.test.ts` coverage).
+   Commit: `test: add WorktreeIsolation collaborator tests` then `feat(pi-subagents): add WorktreeIsolation collaborator`. (May be a single `feat` commit with the test if preferred — the module is self-contained.)
+2. Wire `WorktreeIsolation` into `Agent` and `AgentManager`; drop the old fields.
+   This is one commit because TypeScript will not accept `AgentInit` losing `worktrees`/`isolation` while call sites still pass them.
+   Changes: `agent.ts` (remove `_worktrees`/`_isolation`/`worktreeState`/`setupWorktree`, add `worktree`, update `run`/`completeRun`/`failRun`), `agent-manager.ts` (construct collaborator in `spawn`), `service-adapter.ts` (`record.worktree?.cleanupResult`), and their tests (`agent.test.ts` helpers `createRunnableAgent`/`createAgentWithWorktrees` + worktree describe blocks; remove the `setupWorktree` block; `agent-manager.test.ts` worktree assertions; `service-adapter.test.ts` setup).
+   Commit: `refactor(pi-subagents): Agent delegates worktree lifecycle to WorktreeIsolation`.
+3. Delete the now-orphaned `WorktreeState`.
+   Remove `src/lifecycle/worktree-state.ts` and `test/lifecycle/worktree-state.test.ts`; remove any remaining `WorktreeState` imports.
+   Run `pnpm fallow dead-code` to confirm no dangling exports.
+   Commit: `refactor(pi-subagents): remove WorktreeState, folded into WorktreeIsolation`.
+4. Update architecture doc + package skill.
+   `docs/architecture/architecture.md` class diagram + layout listing; `SKILL.md` Lifecycle domain row.
+   Commit: `docs(pi-subagents): reflect WorktreeIsolation extraction in architecture`.
+
+After all steps: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fallow dead-code`.
+
+## Risks and Mitigations
+
+- Risk: `WorktreeManager.cleanup` mutates `branch` in place; folding `WorktreeState` could lose that behavior.
+  Mitigation: `WorktreeIsolation` stores a mutable `WorktreeInfo` (`_info`) and passes it directly to `cleanup`, preserving the in-place mutation.
+- Risk: a hidden consumer imports `WorktreeCleanupResult`/`WorktreeInfo` from `worktree-state.ts`.
+  Mitigation: grep confirms all consumers import those types from `worktree.ts`; the deletion step re-runs the grep and `pnpm run check`.
+- Risk: the combined Step 2 commit touches several test files at once.
+  Mitigation: the changes are mechanical and localized to worktree-specific helpers/describe blocks; the type checker pinpoints every call site.
+  The bulk of `agent.test.ts` is untouched.
+- Risk: AgentManager's `dispose()` prune path relies on `this.worktrees`.
+  Mitigation: `AgentManager` keeps ownership of the shared `WorktreeManager`; only per-agent collaborator construction is added.
+
+## Open Questions
+
+- Whether `setup()` should return the path (as `setupWorktree()` did) for symmetry.
+  Deferred: no caller needs the return value once `Agent` reads `this.worktree?.path`; keep `setup(): void` until a consumer needs otherwise.
+- Whether `WorktreeIsolation` should later absorb the parent `cwd`/repo-root concern from `GitWorktreeManager`.
+  Deferred to the broader Phase 16 collaborator work; out of scope for Step 1.