@gotgenes/pi-subagents 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.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)
+
+
+### Documentation
+
+* plan inject cwd into AgentManager constructor ([#76](https://github.com/gotgenes/pi-packages/issues/76)) ([7d3d50a](https://github.com/gotgenes/pi-packages/commit/7d3d50a7b7b96ef15cf5ffd7f609ed0baa46d6b9))
+* **retro:** add retro notes for issue [#80](https://github.com/gotgenes/pi-packages/issues/80) ([ac38a72](https://github.com/gotgenes/pi-packages/commit/ac38a7209788c7725c7307491a18fb5a8e83962d))
+
 ## [5.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.3.0...pi-subagents-v5.4.0) (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 | Pending |
+
+### 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 are added by prerequisite #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/0076-inject-cwd-into-agent-manager.md

@@ -0,0 +1,102 @@
+---
+issue: 76
+issue_title: "refactor: inject cwd into AgentManager constructor instead of reading process.cwd() in dispose()"
+---
+
+# Inject cwd into AgentManager constructor
+
+## Problem Statement
+
+`AgentManager.dispose()` calls `pruneWorktrees(process.cwd())` directly — the only place in the class that reads a process global instead of accepting `cwd` from the caller.
+Every other code path that needs a working directory receives it via the per-spawn invocation context (`ctx.cwd`).
+This implicit dependency makes the class harder to test and inconsistent with its own conventions.
+
+## Goals
+
+- Add `cwd: string` as the first parameter of the `AgentManager` constructor and store it as a private field.
+- Replace `pruneWorktrees(process.cwd())` in `dispose()` with `pruneWorktrees(this.cwd)`.
+- Update the single production call site in `index.ts` to pass `process.cwd()`.
+- Update all 18 test-file constructor calls to pass a test directory string.
+
+## Non-Goals
+
+- Removing other `process.cwd()` calls elsewhere in the extension (e.g., `loadCustomAgents` in `index.ts`).
+- Changing how per-spawn `ctx.cwd` flows through `agent-runner.ts`.
+- Refactoring the constructor's callback-heavy signature into an options object (potential follow-up).
+
+## Background
+
+### Relevant modules
+
+| Module               | Role                                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `agent-manager.ts`   | Owns `AgentManager` class; constructor at line 83, `dispose()` at line 479 with the `process.cwd()` call.                     |
+| `index.ts`           | Extension entry point; constructs `AgentManager` at line 64. Already calls `process.cwd()` at line 43 for `loadCustomAgents`. |
+| `worktree.ts`        | Exports `pruneWorktrees(cwd: string)` consumed by `dispose()`.                                                                |
+| `service-adapter.ts` | Depends on `AgentManagerLike` interface, which does not expose the constructor — unaffected.                                  |
+
+### Constraints
+
+From AGENTS.md / code-style skill:
+
+> Do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions — accept the value as a parameter.
+
+This refactoring directly enforces that rule.
+
+`AgentManager` is internal — the public API surface (`exports` in `package.json`) is `service.ts` only, so this is a non-breaking change for consumers.
+
+## Design Overview
+
+The change is mechanical:
+
+1. Prepend `cwd: string` to the constructor parameter list.
+2. Store it as `private readonly cwd: string`.
+3. Replace `process.cwd()` in `dispose()` with `this.cwd`.
+4. At the call site in `index.ts`, pass `process.cwd()` as the first argument.
+5. In tests, pass a fixed string like `"/test-cwd"` to every `new AgentManager(...)` call.
+
+No new types, no interface changes, no export changes.
+
+## Module-Level Changes
+
+### `src/agent-manager.ts`
+
+- Add `private readonly cwd: string` field.
+- Constructor: add `cwd: string` as the first parameter, assign `this.cwd = cwd`.
+- `dispose()`: change `pruneWorktrees(process.cwd())` → `pruneWorktrees(this.cwd)`.
+- Remove the `process` global dependency (no more `process.cwd()` import needed in this file).
+
+### `src/index.ts`
+
+- Pass `process.cwd()` as the first argument to `new AgentManager(...)`.
+
+### `test/agent-manager.test.ts`
+
+- All 18 `new AgentManager(...)` calls gain `"/test-cwd"` as the first argument.
+- No other test logic changes — `pruneWorktrees` is already mocked.
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — the existing `dispose()` test already exercises `pruneWorktrees` via the mock; it will now verify the injected `cwd` is forwarded instead of the process global.
+2. No existing tests become redundant.
+3. All 18 constructor calls must be updated with the new first argument, but the test assertions remain valid.
+
+## TDD Order
+
+1. **Red → Green: update constructor and dispose** — change the `AgentManager` constructor to accept `cwd` as the first parameter, store it, and use `this.cwd` in `dispose()`.
+   Update all 18 test constructor calls to pass `"/test-cwd"`.
+   Update `index.ts` call site to pass `process.cwd()`.
+   Commit message: `refactor: inject cwd into AgentManager constructor (#76)`
+
+This is a single-step refactoring — splitting it further would leave the codebase in a broken intermediate state since the constructor signature change must be applied atomically across production code and tests.
+
+## Risks and Mitigations
+
+| Risk                            | Mitigation                                                                                                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Missing a constructor call site | `grep 'new AgentManager'` across the entire repo confirms only `index.ts` (1 call) and `agent-manager.test.ts` (18 calls).                |
+| Accidentally changing behavior  | `pruneWorktrees` is already mocked in tests; production call site passes `process.cwd()` which is the same value `dispose()` read before. |
+
+## Open Questions
+
+None — the issue's proposed change section is unambiguous and the refactoring is mechanical.

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/0080-consolidate-agent-config-lookup.md

@@ -0,0 +1,35 @@
+---
+issue: 80
+issue_title: "refactor: consolidate getConfig / getAgentConfig into a single resolution path"
+---
+
+# Retro: #80 — consolidate getConfig / getAgentConfig
+
+## Final Retrospective (2026-05-20T00:35:00Z)
+
+### Session summary
+
+Consolidated two overlapping agent config lookup functions (`getConfig` and `getAgentConfig`) into a single `resolveAgentConfig(type): AgentConfig` with a guaranteed-non-null return and internal fallback chain.
+Migrated all 6 source callers and 5 test files across 6 TDD commits, then shipped as `pi-subagents-v5.4.0`.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift migration strategy (add new function → migrate callers incrementally → remove old functions) kept every commit green.
+  No intermediate step broke the test suite.
+- The planning phase correctly identified an under-documented scope question (callers beyond the two mentioned in the issue) and used `ask-user` to resolve it before writing the plan.
+- The `test/prompts.test.ts` caller, missed by the plan, was caught cleanly during the final grep sweep in step 6 — no rework needed, just an additional edit in the same commit.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan specified that `resolveAgentConfig` should fall back for disabled types (matching `getConfig`'s semantics), but didn't trace what `agent-menu.ts` actually reads from disabled configs.
+  `agent-menu.ts` iterates `getAllTypes()` (including disabled agents) and needs the real config to render `✕` indicators, source badges, and `(disabled)` descriptions.
+  With fallback-for-disabled semantics, disabled agents would silently display as general-purpose.
+  Caught during step 4 while editing `agent-menu.ts`, before any wrong test assertions ran.
+  Impact: required changing `resolveAgentConfig` semantics (only fall back for unknown types, not disabled) and updating the step 1 test — a ~5 minute fix folded into the step 4 commit.
+
+#### What caused friction (user side)
+
+- Nothing notable.
+  The user's `ask-user` response during planning ("remove both, migrate all callers") was clear and included a useful directional note about computing values earlier.

package/package.json

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

package/src/agent-manager.ts

@@ -72,6 +72,7 @@ export class AgentManager {
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
+  private readonly cwd: string;
   private maxConcurrent: number;
   private getRunConfig?: () => RunConfig;
 
@@ -81,12 +82,14 @@ export class AgentManager {
   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;
@@ -485,6 +488,6 @@ export class AgentManager {
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
-    try { pruneWorktrees(process.cwd()); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
+    try { pruneWorktrees(this.cwd); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }

package/src/index.ts

@@ -61,7 +61,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager((record) => {
+  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);

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);
+  }
+}