@gotgenes/pi-subagents 5.4.1 → 5.6.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [5.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.5.0...pi-subagents-v5.6.0) (2026-05-20)
+
+
+### Features
+
+* convert AgentManager to options-bag constructor with DI ([1292cec](https://github.com/gotgenes/pi-packages/commit/1292cec60c24d8e657985c53b9b3413089c2a79d))
+* define AgentRunner interface in agent-runner.ts ([6a3c85a](https://github.com/gotgenes/pi-packages/commit/6a3c85a445daf0e4e8c01620eb6ae1a8237f1766))
+
+
+### Documentation
+
+* mark [#84](https://github.com/gotgenes/pi-packages/issues/84) as done in plan ([#72](https://github.com/gotgenes/pi-packages/issues/72)) ([5cfa1ec](https://github.com/gotgenes/pi-packages/commit/5cfa1ecf080f95fbd6b4aec05b27cc9672f60267))
+* **retro:** add retro notes for issue [#84](https://github.com/gotgenes/pi-packages/issues/84) ([99d9016](https://github.com/gotgenes/pi-packages/commit/99d90161df5fe9d302514e33c2d2d9fbfb248f25))
+
+## [5.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.4.1...pi-subagents-v5.5.0) (2026-05-20)
+
+
+### Features
+
+* extract WorktreeManager interface and GitWorktreeManager class ([#84](https://github.com/gotgenes/pi-packages/issues/84)) ([23efb99](https://github.com/gotgenes/pi-packages/commit/23efb99e0d5e6bf6a65b758020e00af69fe84f6e))
+
+
+### Documentation
+
+* plan dependency-inject AgentManager's collaborators ([#72](https://github.com/gotgenes/pi-packages/issues/72)) ([a99374a](https://github.com/gotgenes/pi-packages/commit/a99374aa2b11defd301be97f64b9bdba2a618712))
+* plan extract GitWorktreeManager class ([#84](https://github.com/gotgenes/pi-packages/issues/84)) ([47d9d93](https://github.com/gotgenes/pi-packages/commit/47d9d9368fc2f4762bf31e312ebd84e4332ca4c4))
+* **retro:** add retro notes for issue [#76](https://github.com/gotgenes/pi-packages/issues/76) ([ceef7e0](https://github.com/gotgenes/pi-packages/commit/ceef7e05c8753bbbb6558ca507924b5562cc9c52))
+* update plan to reference [#84](https://github.com/gotgenes/pi-packages/issues/84) as prerequisite ([#72](https://github.com/gotgenes/pi-packages/issues/72)) ([d8ad3f5](https://github.com/gotgenes/pi-packages/commit/d8ad3f544929c569789d63fcf140bd300d5ef389))
+
 ## [5.4.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.4.0...pi-subagents-v5.4.1) (2026-05-20)
 
 

package/docs/plans/0072-inject-agent-manager-collaborators.md

@@ -0,0 +1,329 @@
+---
+issue: 72
+issue_title: "refactor: dependency-inject AgentManager's collaborators"
+---
+
+# Dependency-inject AgentManager's collaborators
+
+## Problem Statement
+
+`AgentManager` directly imports and calls `runAgent`, `resumeAgent`, `createWorktree`, `cleanupWorktree`, and `pruneWorktrees`.
+Any test of `AgentManager` must mock entire modules via `vi.mock()`, coupling the test to the internal structure of `agent-runner.ts` and `worktree.ts` rather than to `AgentManager`'s own behavior.
+
+## Goals
+
+- Define an `AgentRunner` interface (execution boundary) and a `WorktreeManager` interface (real object with state) for the operations `AgentManager` actually needs.
+- Inject both into `AgentManager` via a constructor options bag, replacing the current 6-positional-parameter constructor.
+- Remove all runtime imports of `agent-runner.ts` and `worktree.ts` from `agent-manager.ts`.
+- Migrate `agent-manager.test.ts` from `vi.mock()` module stubs to `vi.fn()` interface stubs.
+- No behavior change.
+
+## Non-Goals
+
+- Changing `AgentManager`'s public method surface (`spawn`, `spawnAndWait`, `resume`, `abort`, etc.).
+- Refactoring `agent-runner.ts` internals (done in #71).
+- Capturing `pi: ExtensionAPI` inside the runner — `pi` stays per-call in `SpawnArgs` for now.
+- Extracting the notification system or widget (done in #54).
+
+## Background
+
+### Prerequisites
+
+| Issue | Title                                               | Status  |
+| ----- | --------------------------------------------------- | ------- |
+| #69   | Create `SubagentRuntime`                            | ✓ Done  |
+| #71   | Extract pure agent-session assembler                | ✓ Done  |
+| #76   | Inject `cwd` into `AgentManager`                    | ✓ Done  |
+| #80   | Consolidate `getConfig`/`getAgentConfig`            | ✓ Done  |
+| #84   | Extract `GitWorktreeManager` class from worktree.ts | ✓ Done  |
+
+### Prior art
+
+`pi-permission-system` `PermissionManager` takes a `PolicyLoader` via constructor injection.
+The interface is defined in `policy-loader.ts` alongside the default `FilePolicyLoader` implementation.
+`PermissionManager` imports the interface type-only — no runtime coupling to the loader module.
+
+### Current imports in `agent-manager.ts`
+
+```typescript
+import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";  // runtime + type
+import { addUsage } from "./usage.js";                                          // runtime (pure utility, stays)
+import { cleanupWorktree, createWorktree, pruneWorktrees } from "./worktree.js"; // runtime
+```
+
+After this refactor:
+
+```typescript
+import type { AgentRunner } from "./agent-runner.js";      // type-only (erased at compile)
+import type { WorktreeManager } from "./worktree.js";      // type-only (erased at compile)
+import { addUsage } from "./usage.js";                      // runtime (pure utility, stays)
+```
+
+### Relevant constraints from AGENTS.md
+
+- Keep modules focused and composable (one concern per file).
+- Prefer explicit configuration over hidden behavior.
+- When a shared interface references a collaborator, use a narrow interface type — not the concrete class.
+
+## Design Overview
+
+### Two collaborators, different natures
+
+#### WorktreeManager — real object with state
+
+The three worktree functions all operate on git worktrees relative to a repository root.
+Today `cwd` is threaded to each call — `createWorktree(ctx.cwd, id)`, `cleanupWorktree(ctx.cwd, wt, desc)`, `pruneWorktrees(this.cwd)`.
+In practice `ctx.cwd` and `this.cwd` are always the same value (the process working directory set at extension init).
+
+A `WorktreeManager` class captures `cwd` at construction, eliminating the per-call threading:
+
+```typescript
+// In worktree.ts
+export interface WorktreeManager {
+  create(id: string): WorktreeInfo | undefined;
+  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult;
+  prune(): void;
+}
+
+export class GitWorktreeManager implements WorktreeManager {
+  constructor(private readonly cwd: string) {}
+  create(id: string): WorktreeInfo | undefined { return createWorktree(this.cwd, id); }
+  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult { return cleanupWorktree(this.cwd, wt, description); }
+  prune(): void { pruneWorktrees(this.cwd); }
+}
+```
+
+The existing free functions stay as the internal implementation and for any direct callers.
+
+#### AgentRunner — execution boundary interface
+
+`runAgent` and `resumeAgent` are stateless IO orchestrators.
+They have no natural state to capture — `pi` is constant per extension but already flows through `SpawnArgs`.
+The interface exists to decouple `AgentManager` (lifecycle management: queuing, concurrency, abort) from the execution engine (SDK sessions, prompt loops, event wiring):
+
+```typescript
+// In agent-runner.ts
+export interface AgentRunner {
+  run(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
+}
+
+export interface ResumeOptions {
+  onToolActivity?: (activity: ToolActivity) => void;
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  signal?: AbortSignal;
+}
+```
+
+The existing `{ run: runAgent, resume: resumeAgent }` structurally satisfies the interface — no wrapper class needed.
+
+### Constructor options bag
+
+The current 6-positional-parameter constructor becomes an options bag:
+
+```typescript
+export interface AgentManagerOptions {
+  cwd: string;
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  maxConcurrent?: number;
+  getRunConfig?: () => RunConfig;
+  onStart?: OnAgentStart;
+  onComplete?: OnAgentComplete;
+  onCompact?: OnAgentCompact;
+}
+```
+
+All fields are used by `AgentManager` — no subset concern.
+
+### Wiring in index.ts
+
+```typescript
+import { runAgent, resumeAgent } from "./agent-runner.js";
+import { GitWorktreeManager } from "./worktree.js";
+
+const worktrees = new GitWorktreeManager(process.cwd());
+const manager = new AgentManager({
+  cwd: process.cwd(),
+  runner: { run: runAgent, resume: resumeAgent },
+  worktrees,
+  onComplete: (record) => { /* ... */ },
+  onStart: (record) => { /* ... */ },
+  onCompact: (record, info) => { /* ... */ },
+  getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }),
+});
+```
+
+### `cwd` on AgentManager after WorktreeManager captures it
+
+`AgentManager.cwd` was previously used for two purposes:
+
+1. Worktree operations (`createWorktree(ctx.cwd, ...)`, `pruneWorktrees(this.cwd)`) — now handled by the injected `WorktreeManager`.
+2. No other use remains inside `AgentManager` itself.
+
+However, `cwd` is still passed as part of `AgentManagerOptions` because `dispose()` calls `this.worktrees.prune()` — the `WorktreeManager` now owns the `cwd` for that call.
+The `cwd` field on `AgentManagerOptions` can be dropped if no other internal use remains after the refactor.
+A grep in step 8 will confirm whether `this.cwd` has any remaining readers; if not, it is removed.
+
+### Test pattern after DI
+
+```typescript
+function createManager(overrides?: Partial<AgentManagerOptions>) {
+  const runner: AgentRunner = {
+    run: vi.fn().mockResolvedValue({
+      responseText: "done", session: { dispose: vi.fn() }, aborted: false, steered: false,
+    }),
+    resume: vi.fn().mockResolvedValue("resumed"),
+  };
+  const worktrees: WorktreeManager = {
+    create: vi.fn(),
+    cleanup: vi.fn(() => ({ hasChanges: false })),
+    prune: vi.fn(),
+  };
+  return {
+    manager: new AgentManager({ cwd: "/test-cwd", runner, worktrees, ...overrides }),
+    runner,
+    worktrees,
+  };
+}
+```
+
+Tests access the mock stubs directly — no `vi.mocked(runAgent)` needed:
+
+```typescript
+const { manager, runner } = createManager({ onComplete: (r) => { /* ... */ } });
+manager.spawn(mockPi, mockCtx, "general-purpose", "test", { description: "test", isBackground: true });
+expect(runner.run).toHaveBeenCalled();
+```
+
+## Module-Level Changes
+
+### `src/worktree.ts` (no changes in this issue)
+
+`WorktreeManager` interface and `GitWorktreeManager` class were added by #84.
+
+### `src/agent-runner.ts` (modified)
+
+- Add `AgentRunner` interface (2 methods: `run`, `resume`).
+- Extract `ResumeOptions` as a named type from the inline parameter type in `resumeAgent`.
+- Export both.
+- No changes to `runAgent()` or `resumeAgent()` implementations.
+
+### `src/agent-manager.ts` (modified)
+
+- Add `AgentManagerOptions` interface.
+- Replace 6-positional-parameter constructor with single `options: AgentManagerOptions` parameter.
+- Replace `runAgent(ctx, ...)` with `this.runner.run(ctx, ...)`.
+- Replace `resumeAgent(session, ...)` with `this.runner.resume(session, ...)`.
+- Replace `createWorktree(ctx.cwd, id)` with `this.worktrees.create(id)`.
+- Replace `cleanupWorktree(ctx.cwd, wt, desc)` with `this.worktrees.cleanup(wt, desc)`.
+- Replace `pruneWorktrees(this.cwd)` with `this.worktrees.prune()`.
+- Remove runtime imports from `agent-runner.ts` and `worktree.ts`; keep `import type` only.
+- Remove `this.cwd` if grep confirms no remaining readers after the worktree delegation.
+
+### `src/index.ts` (modified)
+
+- Import `GitWorktreeManager` from `worktree.ts`.
+- Construct `new GitWorktreeManager(process.cwd())`.
+- Pass options bag to `new AgentManager({ ... })`.
+
+### `test/agent-manager.test.ts` (modified)
+
+- Remove `vi.mock("../src/agent-runner.js", ...)` block.
+- Remove `vi.mock("../src/worktree.js", ...)` block.
+- Remove `import { runAgent } from "../src/agent-runner.js"` and `import { pruneWorktrees } from "../src/worktree.js"`.
+- Add `createManager()` test helper factory.
+- Replace all 19 `new AgentManager(...)` calls with `createManager(...)`.
+- Update assertions from `vi.mocked(runAgent)` to `runner.run` / `runner.resume`.
+- Update assertions from `vi.mocked(pruneWorktrees)` to `worktrees.prune`.
+- Update assertions from `vi.mocked(createWorktree)` to `worktrees.create`.
+
+## Test Impact Analysis
+
+### New unit tests enabled by DI
+
+1. Queueing behavior — verify that excess background agents are queued and started in order when running agents complete, without needing module-level mocks.
+2. Concurrency limit enforcement — verify `maxConcurrent` is respected with controlled stub resolution.
+3. Abort semantics — verify that aborting a queued agent removes it from the queue and sets status, using stubs that never resolve.
+4. Lifecycle callback ordering — verify `onStart`, `onComplete`, `onCompact` fire at the right moments with correct record state.
+5. Worktree failure modes — verify that `create` returning `undefined` throws and leaves no orphan record, via a simple `vi.fn().mockReturnValue(undefined)`.
+
+### Existing tests that are migrated (not removed)
+
+All 19 test sites in `agent-manager.test.ts` are migrated from `vi.mock()` + `vi.mocked()` to the `createManager()` helper with injected stubs.
+The test logic stays identical — only the mock setup mechanism changes.
+
+### Existing tests that stay as-is
+
+Tests in `agent-runner.test.ts`, `agent-runner-extension-tools.test.ts`, `agent-runner-settings.test.ts`, and `session-config.test.ts` are unaffected — they test the execution engine, not the lifecycle manager.
+
+## TDD Order
+
+Issue #84 (extract `GitWorktreeManager`) must land first.
+This plan assumes `WorktreeManager` interface and `GitWorktreeManager` class already exist in `worktree.ts`.
+
+### Phase A: Define AgentRunner interface
+
+1. Add `AgentRunner` interface and named `ResumeOptions` type in `agent-runner.ts`.
+   Export both.
+   Run existing tests.
+   Commit: `feat: define AgentRunner interface in agent-runner.ts`
+
+### Phase B: Lift-and-shift test migration
+
+2. Create `createManager()` test helper factory in `agent-manager.test.ts`.
+   The factory constructs `AgentManager` using the **old** positional constructor, wrapping the same `vi.mock()` stubs in a consistent helper.
+   Migrate all 19 `new AgentManager(...)` call sites to use the factory.
+   All tests pass unchanged.
+   Commit: `test: add createManager helper and migrate call sites`
+
+### Phase C: Constructor conversion + DI
+
+3. RED: Add a test that calls `createManager()` with `runner` and `worktrees` overrides and asserts `runner.run` is called when spawning an agent.
+   This fails because the constructor does not accept the options bag yet.
+   Commit: `test: add agent-manager test with injected AgentRunner`
+
+4. GREEN: Convert `AgentManager` constructor to accept `AgentManagerOptions`.
+   Replace internal calls to `runAgent`/`resumeAgent`/`createWorktree`/`cleanupWorktree`/`pruneWorktrees` with `this.runner.*`/`this.worktrees.*`.
+   Remove runtime imports from `agent-runner.ts` and `worktree.ts`.
+   Update `createManager()` factory to pass injected stubs via the options bag.
+   Remove `vi.mock()` blocks for `agent-runner.js` and `worktree.js`.
+   Update all test assertions that referenced `vi.mocked(runAgent)` etc. to reference the injected stubs.
+   All tests pass.
+   Commit: `feat: convert AgentManager to options-bag constructor with DI`
+
+### Phase D: Wiring and verification
+
+5. Wire `index.ts`: construct `GitWorktreeManager`, pass options bag to `AgentManager`.
+   Run full test suite.
+   Commit: `refactor: wire injected deps into AgentManager (#72)`
+
+6. Add new tests enabled by DI: queueing order, concurrency enforcement, abort-from-queue, lifecycle callback timing.
+   Commit: `test: add DI-enabled agent-manager tests`
+
+7. Verify acceptance criteria.
+   Grep `agent-manager.ts` for runtime imports from `agent-runner.ts` and `worktree.ts` (expect none).
+   Grep for `this.cwd` — if no readers remain, remove the field and the `cwd` option.
+   Run `pnpm run check` for type safety.
+   Commit: `refactor: finalize AgentManager DI (#72)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                             | Mitigation                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.cwd` and `this.cwd` differ for worktree operations, causing `GitWorktreeManager` to use the wrong directory | In practice both are `process.cwd()` — verified by tracing `session_start` and constructor call sites. If a difference surfaces, `WorktreeManager` can accept `cwd` per-call as a fallback.                           |
+| Migrating 19 test call sites introduces test regressions                                                         | Phase B (step 3) migrates under the old constructor first, proving the helper factory works before any behavioral change. Phase C (step 5) changes the constructor and stubs atomically.                              |
+| `import type` from `agent-runner.ts`/`worktree.ts` is considered a "top-level import" by reviewers               | `import type` is erased by TypeScript at compile time and creates zero runtime dependency. The compiled JS will have no import from these modules. This matches the `PolicyLoader` pattern in `pi-permission-system`. |
+| New options bag breaks the `AgentManagerLike` interface in `service-adapter.ts`                                  | `AgentManagerLike` references `AgentManager`'s public methods (`spawn`, `getRecord`, etc.), not its constructor. The constructor change is invisible to the adapter.                                                  |
+| `addUsage` remains as a direct runtime import from `usage.ts`                                                    | Intentional — `addUsage` is a pure accumulator function with no IO. The issue targets `agent-runner.ts` and `worktree.ts` specifically.                                                                               |
+
+## Open Questions
+
+- Should `AgentRunner` eventually capture `pi: ExtensionAPI` to eliminate the `pi` parameter from `spawn()` and `SpawnArgs`?
+  Deferred — `pi` is already threaded through the call chain and removing it would change `AgentManager`'s public method signatures, which is a non-goal.
+- Does the `WorktreeManager` abstraction surface further opportunities (e.g., non-git isolation strategies)?
+  Noted for future consideration — the interface makes alternative implementations possible without changing `AgentManager`.
+- The `AgentRunner` interface is a testability seam, not a stateful object.
+  As the codebase continues untangling, a more natural execution abstraction may emerge.
+  This interface is intentionally minimal to avoid premature abstraction.

package/docs/plans/0084-extract-git-worktree-manager.md

@@ -0,0 +1,142 @@
+---
+issue: 84
+issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
+---
+
+# Extract GitWorktreeManager class
+
+## Problem Statement
+
+`worktree.ts` exports three free functions — `createWorktree(cwd, id)`, `cleanupWorktree(cwd, wt, desc)`, and `pruneWorktrees(cwd)` — that all operate on git worktrees relative to a repository root.
+Every caller threads `cwd` as the first argument.
+These functions form a cohesive unit with natural shared state (the repo root), but today there is no object to capture it.
+
+Issue #72 (dependency-inject `AgentManager`'s collaborators) needs a `WorktreeManager` interface to inject.
+Extracting the class first keeps #72 a clean DI + constructor refactor instead of mixing object extraction with dependency injection.
+
+## Goals
+
+- Define a `WorktreeManager` interface in `worktree.ts` with three methods: `create(id)`, `cleanup(wt, desc)`, `prune()` — no `cwd` parameter.
+- Add a `GitWorktreeManager` class that captures `cwd` at construction and delegates to the existing free functions.
+- Export both the interface and the class.
+- Existing free functions stay exported and unchanged.
+- No behavior change.
+
+## Non-Goals
+
+- Changing `AgentManager` to use the new class (that is #72).
+- Refactoring the internal implementation of `createWorktree`, `cleanupWorktree`, or `pruneWorktrees`.
+- Publishing `WorktreeManager` as a cross-extension API via `Symbol.for()` — it is internal to this package.
+
+## Background
+
+### Prerequisites
+
+None — this is the first step in the #72 dependency chain.
+
+### Relevant modules
+
+| Module                  | Role                                                       |
+| ----------------------- | ---------------------------------------------------------- |
+| `src/worktree.ts`       | Free functions for git worktree create/cleanup/prune       |
+| `test/worktree.test.ts` | Integration tests that create real git repos and worktrees |
+| `src/agent-manager.ts`  | Only consumer of the three free functions (6 call sites)   |
+
+### Constraints from AGENTS.md / code-style
+
+- Keep modules focused and composable (one concern per file).
+- When a shared interface references a collaborator, use a narrow interface type — not the concrete class.
+- Business logic should be pure functions wherever possible — keep IO at the edges.
+
+The free functions are IO (they shell out to `git`), so wrapping them in a class that captures `cwd` is the right level of abstraction — the class is a thin adapter, not business logic.
+
+## Design Overview
+
+### Interface and class
+
+Added at the bottom of `worktree.ts`, after the existing free functions:
+
+```typescript
+export interface WorktreeManager {
+  create(id: string): WorktreeInfo | undefined;
+  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult;
+  prune(): void;
+}
+
+export class GitWorktreeManager implements WorktreeManager {
+  constructor(private readonly cwd: string) {}
+
+  create(id: string): WorktreeInfo | undefined {
+    return createWorktree(this.cwd, id);
+  }
+
+  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult {
+    return cleanupWorktree(this.cwd, wt, description);
+  }
+
+  prune(): void {
+    pruneWorktrees(this.cwd);
+  }
+}
+```
+
+### Why the interface lives in `worktree.ts`
+
+The `WorktreeManager` interface references `WorktreeInfo` and `WorktreeCleanupResult`, which are already defined in `worktree.ts`.
+Co-locating avoids a separate file for a 5-line interface.
+This matches the #72 plan's expectation: `import type { WorktreeManager } from "./worktree.js"`.
+
+### No changes to callers
+
+`agent-manager.ts` continues importing and calling the free functions directly.
+Issue #72 handles the migration to the injected `WorktreeManager`.
+
+## Module-Level Changes
+
+### `src/worktree.ts` (modified)
+
+- Add `WorktreeManager` interface (3 methods).
+- Add `GitWorktreeManager` class implementing the interface.
+- Existing free functions, types, and imports unchanged.
+
+### `test/worktree.test.ts` (modified)
+
+- Add a new `describe("GitWorktreeManager")` block with tests for the class.
+- Existing free-function tests stay as-is.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+1. `GitWorktreeManager.create` — delegates to `createWorktree` with the captured `cwd`.
+2. `GitWorktreeManager.cleanup` — delegates to `cleanupWorktree` with the captured `cwd`.
+3. `GitWorktreeManager.prune` — delegates to `pruneWorktrees` with the captured `cwd`.
+
+These are thin delegation tests that verify the class wires `cwd` correctly.
+They reuse the same real-git-repo test infrastructure already in `worktree.test.ts`.
+
+### Existing tests
+
+All existing tests in `worktree.test.ts` stay unchanged — they test the free functions directly.
+
+## TDD Order
+
+1. **RED:** Add `describe("GitWorktreeManager")` with tests for `create`, `cleanup`, and `prune`.
+   Tests import `GitWorktreeManager` which does not exist yet — compilation fails.
+   Commit: `test: add GitWorktreeManager tests`
+
+2. **GREEN:** Add `WorktreeManager` interface and `GitWorktreeManager` class to `worktree.ts`.
+   All tests pass.
+   Run `pnpm run check` to verify types.
+   Commit: `feat: extract WorktreeManager interface and GitWorktreeManager class (#84)`
+
+## Risks and Mitigations
+
+| Risk                                                                      | Mitigation                                                                                                                                     |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Class delegation tests are slow because they create real git repos        | The existing test suite already does this; the new tests reuse the same `initGitRepo()` helper and add ~3 test cases to an already-fast suite. |
+| Future callers bypass the interface and use `GitWorktreeManager` directly | The #72 plan types `AgentManager`'s constructor parameter as `WorktreeManager` (the interface), not the class. Code review enforces this.      |
+
+## Open Questions
+
+None — the interface shape is specified by the issue and matches the #72 plan exactly.

package/docs/retro/0076-inject-cwd-into-agent-manager.md

@@ -0,0 +1,35 @@
+---
+issue: 76
+issue_title: "refactor: inject cwd into AgentManager constructor instead of reading process.cwd() in dispose()"
+---
+
+# Retro: #76 — inject cwd into AgentManager constructor
+
+## Final Retrospective (2026-05-19T21:00:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped a single-step refactoring that injects `cwd: string` into the `AgentManager` constructor, replacing the `process.cwd()` call in `dispose()` with `this.cwd`.
+Released as `pi-subagents-v5.4.1`.
+The entire cycle (plan → TDD → ship → release) completed in one session with one minor friction point.
+
+### Observations
+
+#### What went well
+
+- Clean single-commit implementation: one `refactor:` commit touched 3 files, updated 18 test constructor calls plus one production call site, and added one new assertion — all green on first run.
+- TDD Red phase worked well despite the plan calling this a "single-step refactoring."
+  Writing a new test (`"calls pruneWorktrees with the cwd passed to the constructor"`) gave a clear Red signal before the implementation change, even though the constructor signature change had to be applied atomically.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan's "Test Impact Analysis" stated "No new unit tests are needed" and framed existing tests as sufficient.
+  In practice, the existing tests only called `dispose()` in `afterEach` hooks without assertions on `pruneWorktrees` arguments, so a new test was needed for a proper Red phase.
+  The user noticed the discrepancy before TDD began ("We will at least alter some tests, right?").
+  Impact: one clarifying exchange, no rework.
+  User-caught.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's question about test changes was a useful early catch that would have surfaced during TDD anyway.

package/docs/retro/0084-extract-git-worktree-manager.md

@@ -0,0 +1,37 @@
+---
+issue: 84
+issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
+---
+
+# Retro: #84 — extract GitWorktreeManager class from worktree.ts free functions
+
+## Final Retrospective (2026-05-20T13:31:00Z)
+
+### Session summary
+
+Extracted a `WorktreeManager` interface and `GitWorktreeManager` class from the three free functions in `worktree.ts`.
+The two-step TDD cycle (add tests → add implementation) executed cleanly with no rework or deviations from the plan.
+Released as `pi-subagents-v5.5.0`.
+
+### Observations
+
+#### What went well
+
+- The issue body included an exact "Proposed Interface" section with TypeScript code, which made the plan nearly mechanical and eliminated all design ambiguity.
+  The `ask-user` step was correctly skipped.
+- The two-step TDD cycle was appropriately minimal for a thin delegation extraction — no over-engineering of the test or commit structure.
+- The full pipeline (plan → TDD → ship → release) completed in a single pass with zero corrections.
+
+#### What caused friction (agent side)
+
+No friction observed.
+The issue was well-scoped and the existing pipeline instructions handled every step.
+
+#### What caused friction (user side)
+
+No friction observed.
+The pipeline was driven cleanly with `/plan-issue` → `/tdd-plan` → `/ship-issue`.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0084-extract-git-worktree-manager.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.4.1",
+  "version": "5.6.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -9,12 +9,12 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentRunner, ToolActivity } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
-import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
+import type { WorktreeManager } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
@@ -24,6 +24,16 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
+export interface AgentManagerOptions {
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  maxConcurrent?: number;
+  getRunConfig?: () => RunConfig;
+  onStart?: OnAgentStart;
+  onComplete?: OnAgentComplete;
+  onCompact?: OnAgentCompact;
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -72,7 +82,8 @@ export class AgentManager {
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
-  private readonly cwd: string;
+  private readonly runner: AgentRunner;
+  private readonly worktrees: WorktreeManager;
   private maxConcurrent: number;
   private getRunConfig?: () => RunConfig;
 
@@ -81,20 +92,14 @@ export class AgentManager {
   /** Number of currently running background agents. */
   private runningBackground = 0;
 
-  constructor(
-    cwd: string,
-    onComplete?: OnAgentComplete,
-    maxConcurrent = DEFAULT_MAX_CONCURRENT,
-    onStart?: OnAgentStart,
-    onCompact?: OnAgentCompact,
-    getRunConfig?: () => RunConfig,
-  ) {
-    this.cwd = cwd;
-    this.onComplete = onComplete;
-    this.onStart = onStart;
-    this.onCompact = onCompact;
-    this.getRunConfig = getRunConfig;
-    this.maxConcurrent = maxConcurrent;
+  constructor(options: AgentManagerOptions) {
+    this.runner = options.runner;
+    this.worktrees = options.worktrees;
+    this.onComplete = options.onComplete;
+    this.onStart = options.onStart;
+    this.onCompact = options.onCompact;
+    this.getRunConfig = options.getRunConfig;
+    this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
@@ -164,7 +169,7 @@ export class AgentManager {
     // BEFORE state mutation so a throw doesn't leave the record half-running.
     let worktreeCwd: string | undefined;
     if (options.isolation === "worktree") {
-      const wt = createWorktree(ctx.cwd, id);
+      const wt = this.worktrees.create(id);
       if (!wt) {
         throw new Error(
           'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -190,7 +195,7 @@ export class AgentManager {
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
     const runConfig = this.getRunConfig?.();
-    const promise = runAgent(ctx, type, prompt, {
+    const promise = this.runner.run(ctx, type, prompt, {
       pi,
       model: options.model,
       maxTurns: options.maxTurns,
@@ -247,7 +252,7 @@ export class AgentManager {
 
         // Clean up worktree if used
         if (record.worktree) {
-          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          const wtResult = this.worktrees.cleanup(record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
             record.result = (record.result ?? "") +
@@ -281,7 +286,7 @@ export class AgentManager {
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
-            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            const wtResult = this.worktrees.cleanup(record.worktree, options.description);
             record.worktreeResult = wtResult;
           } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
@@ -351,7 +356,7 @@ export class AgentManager {
     record.error = undefined;
 
     try {
-      const responseText = await resumeAgent(record.session, prompt, {
+      const responseText = await this.runner.resume(record.session, prompt, {
         onToolActivity: (activity) => {
           if (activity.type === "end") record.toolUses++;
         },
@@ -488,6 +493,6 @@ export class AgentManager {
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
-    try { pruneWorktrees(this.cwd); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
+    try { this.worktrees.prune(); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }

package/src/agent-runner.ts

@@ -129,6 +129,23 @@ export interface RunResult {
   steered: boolean;
 }
 
+/** Options for resuming an existing agent session. */
+export interface ResumeOptions {
+  onToolActivity?: (activity: ToolActivity) => void;
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  signal?: AbortSignal;
+}
+
+/**
+ * Execution boundary: decouples AgentManager (lifecycle management) from the
+ * SDK session orchestration in runAgent/resumeAgent.
+ */
+export interface AgentRunner {
+  run(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
+}
+
 /**
  * Subscribe to a session and collect the last assistant message text.
  * Returns an object with a `getText()` getter and an `unsubscribe` function.
@@ -375,19 +392,7 @@ export async function runAgent(
 export async function resumeAgent(
   session: AgentSession,
   prompt: string,
-  options: {
-    onToolActivity?: (activity: ToolActivity) => void;
-    onAssistantUsage?: (usage: {
-      input: number;
-      output: number;
-      cacheWrite: number;
-    }) => void;
-    onCompaction?: (info: {
-      reason: "manual" | "threshold" | "overflow";
-      tokensBefore: number;
-    }) => void;
-    signal?: AbortSignal;
-  } = {},
+  options: ResumeOptions = {},
 ): Promise<string> {
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);

package/src/index.ts

@@ -13,7 +13,7 @@
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, normalizeMaxTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
@@ -33,6 +33,7 @@ import {
   AgentWidget,
   type UICtx,
 } from "./ui/agent-widget.js";
+import { GitWorktreeManager } from "./worktree.js";
 
 export default function (pi: ExtensionAPI) {
   // ---- Register custom notification renderer ----
@@ -61,49 +62,55 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager(process.cwd(), (record) => {
-    // Emit lifecycle event based on terminal status
-    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-    const eventData = buildEventData(record);
-    if (isError) {
-      pi.events.emit("subagents:failed", eventData);
-    } else {
-      pi.events.emit("subagents:completed", eventData);
-    }
+  const manager = new AgentManager({
+    runner: { run: runAgent, resume: resumeAgent },
+    worktrees: new GitWorktreeManager(process.cwd()),
+    onComplete: (record) => {
+      // Emit lifecycle event based on terminal status
+      const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+      const eventData = buildEventData(record);
+      if (isError) {
+        pi.events.emit("subagents:failed", eventData);
+      } else {
+        pi.events.emit("subagents:completed", eventData);
+      }
 
-    // Persist final record for cross-extension history reconstruction
-    pi.appendEntry("subagents:record", {
-      id: record.id, type: record.type, description: record.description,
-      status: record.status, result: record.result, error: record.error,
-      startedAt: record.startedAt, completedAt: record.completedAt,
-    });
+      // Persist final record for cross-extension history reconstruction
+      pi.appendEntry("subagents:record", {
+        id: record.id, type: record.type, description: record.description,
+        status: record.status, result: record.result, error: record.error,
+        startedAt: record.startedAt, completedAt: record.completedAt,
+      });
 
-    // Skip notification if result was already consumed via get_subagent_result
-    if (record.resultConsumed) {
-      notifications.cleanupCompleted(record.id);
-      return;
-    }
+      // Skip notification if result was already consumed via get_subagent_result
+      if (record.resultConsumed) {
+        notifications.cleanupCompleted(record.id);
+        return;
+      }
 
-    notifications.sendCompletion(record);
-  }, undefined, (record) => {
-    // Emit started event when agent transitions to running (including from queue)
-    pi.events.emit("subagents:started", {
-      id: record.id,
-      type: record.type,
-      description: record.description,
-    });
-  }, (record, info) => {
-    // Emit compacted event when agent's session compacts (preserves count on record).
-    pi.events.emit("subagents:compacted", {
-      id: record.id,
-      type: record.type,
-      description: record.description,
-      reason: info.reason,
-      tokensBefore: info.tokensBefore,
-      compactionCount: record.compactionCount,
-    });
-  },
-  () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }));
+      notifications.sendCompletion(record);
+    },
+    onStart: (record) => {
+      // Emit started event when agent transitions to running (including from queue)
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+    onCompact: (record, info) => {
+      // Emit compacted event when agent's session compacts (preserves count on record).
+      pi.events.emit("subagents:compacted", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        reason: info.reason,
+        tokensBefore: info.tokensBefore,
+        compactionCount: record.compactionCount,
+      });
+    },
+    getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }),
+  });
 
   // Typed service published via Symbol.for() for cross-extension access.
   // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");

package/src/worktree.ts

@@ -162,3 +162,33 @@ export function pruneWorktrees(cwd: string): void {
     execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
   } catch (err) { debugLog("pruneWorktrees", err); }
 }
+
+/**
+ * Interface for managing git worktrees relative to a fixed repository root.
+ * Callers do not thread `cwd` per call — it is captured at construction time.
+ */
+export interface WorktreeManager {
+  create(id: string): WorktreeInfo | undefined;
+  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult;
+  prune(): void;
+}
+
+/**
+ * Concrete implementation of WorktreeManager backed by the free functions in this module.
+ * Captures `cwd` (the repository root) at construction and delegates each method.
+ */
+export class GitWorktreeManager implements WorktreeManager {
+  constructor(private readonly cwd: string) {}
+
+  create(id: string): WorktreeInfo | undefined {
+    return createWorktree(this.cwd, id);
+  }
+
+  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult {
+    return cleanupWorktree(this.cwd, wt, description);
+  }
+
+  prune(): void {
+    pruneWorktrees(this.cwd);
+  }
+}