@gotgenes/pi-subagents 7.7.0 → 7.8.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [7.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.8.0...pi-subagents-v7.8.1) (2026-05-26)
+
+
+### Documentation
+
+* plan reduce test duplication — top 3 clone families ([#219](https://github.com/gotgenes/pi-packages/issues/219)) ([c941b1b](https://github.com/gotgenes/pi-packages/commit/c941b1b3c047f6895eb57da3291b75082a2b99a3))
+* **retro:** add planning stage notes for issue [#219](https://github.com/gotgenes/pi-packages/issues/219) ([5122f7c](https://github.com/gotgenes/pi-packages/commit/5122f7cd666873abbbb6b6880fffb1e751beb9b5))
+* **retro:** add retro notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([ef9187b](https://github.com/gotgenes/pi-packages/commit/ef9187ba8521d10212bd992cbfcf3d853886938b))
+* **retro:** add TDD stage notes for issue [#219](https://github.com/gotgenes/pi-packages/issues/219) ([975f94e](https://github.com/gotgenes/pi-packages/commit/975f94e5e868310765029050490098b335a67e1e))
+
+## [7.8.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.7.0...pi-subagents-v7.8.0) (2026-05-26)
+
+
+### Features
+
+* inject agentDir into SettingsManager and loadSettings to remove SDK dependency ([7dcb986](https://github.com/gotgenes/pi-packages/commit/7dcb9868c8ac52c86a3eac0b6fc6648c8d57fc7c))
+* wire agentDir from SDK boundary in index.ts ([#218](https://github.com/gotgenes/pi-packages/issues/218)) ([17e9fc5](https://github.com/gotgenes/pi-packages/commit/17e9fc5f7880ae92168a6bb30e6fbc82748b7b2a))
+
+
+### Documentation
+
+* plan push SDK boundary in settings.ts ([#218](https://github.com/gotgenes/pi-packages/issues/218)) ([19f7cd6](https://github.com/gotgenes/pi-packages/commit/19f7cd6ddfa28290f7e61e6273d966c946868cf6))
+* **retro:** add planning stage notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([80be50e](https://github.com/gotgenes/pi-packages/commit/80be50e1b6ddf19f743010bd4c3cdf232d901cf1))
+* **retro:** add retro notes for issue [#217](https://github.com/gotgenes/pi-packages/issues/217) ([2140655](https://github.com/gotgenes/pi-packages/commit/21406555e34fbe0d41f48206e3208e1cb7326633))
+* **retro:** add TDD stage notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([86b4f94](https://github.com/gotgenes/pi-packages/commit/86b4f946d7498e96dbb2b4c513d0ea6331fc5f8c))
+
 ## [7.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.6.0...pi-subagents-v7.7.0) (2026-05-26)
 
 

package/docs/architecture/architecture.md

@@ -584,7 +584,10 @@ The IO boundary was split into two focused interfaces:
 export interface EnvironmentIO {
   detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
   getAgentDir: () => string;
-  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+  deriveSessionDir: (
+    parentSessionFile: string | undefined,
+    effectiveCwd: string,
+  ) => string;
 }
 
 /** Session factory — create SDK objects for a child agent session. */
@@ -592,7 +595,9 @@ export interface SessionFactoryIO {
   createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
   createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
-  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  createSession: (
+    opts: CreateSessionOptions,
+  ) => Promise<{ session: AgentSession }>;
   assemblerIO: AssemblerIO;
 }
 
@@ -643,7 +648,7 @@ Three closure factories converted to classes in [#214].
 - Smell: C (coupling — deps hidden in closure scope instead of explicit on class)
 - Outcome: 0 remaining closure factories (excluding pure-function factories), deps visible as constructor parameters
 
-### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215]
+### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215] ✓
 
 `buildParentContext` in `session/context.ts` is the only remaining fallow refactoring target.
 The function loops over branch entries with 3 type-check branches, each with sub-branches for role or summary.
@@ -671,7 +676,7 @@ Extracted:
 - Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
 - Outcome: `startAgent` reduced to ~40 LOC coordinator with zero mutable `let` bindings; `.then()`/`.catch()` are one-liners
 
-### Step 4: Extract overwrite guard from UI — [#217]
+### Step 4: Extract overwrite guard from UI — [#217] ✓
 
 The 20-line pattern duplicated between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` checks file existence, prompts for confirmation, writes the file, reloads the registry, and notifies the user.
 Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, label)` function.
@@ -680,7 +685,7 @@ Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, lab
 - Smell: A (production duplication)
 - Outcome: 0 production clone groups
 
-### Step 5: Push SDK boundary in `settings.ts` — [#218]
+### Step 5: Push SDK boundary in `settings.ts` — [#218] ✓
 
 `globalPath()` calls `getAgentDir()` (a Pi SDK function) at invocation time.
 This hides a platform dependency inside a module that is otherwise pure configuration logic.
@@ -890,7 +895,6 @@ The upstream test suite is run periodically as a regression canary for the agent
 [earendil-works/pi#4207]: https://github.com/earendil-works/pi/issues/4207
 [gotgenes/pi-packages]: https://github.com/gotgenes/pi-packages
 [tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents
-
 [166]: https://github.com/gotgenes/pi-packages/issues/166
 [167]: https://github.com/gotgenes/pi-packages/issues/167
 [168]: https://github.com/gotgenes/pi-packages/issues/168

package/docs/plans/0218-push-sdk-boundary-in-settings.md

@@ -0,0 +1,172 @@
+---
+issue: 218
+issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
+---
+
+# Push SDK boundary in settings.ts
+
+## Problem Statement
+
+`settings.ts` imports `getAgentDir` from the Pi SDK (`@earendil-works/pi-coding-agent`) and calls it inside `globalPath()` at invocation time.
+This hides a platform dependency inside a module that is otherwise pure configuration logic — violating the project's SDK-boundary rule that pure helpers and domain modules should remain SDK-independent.
+The SDK call also forces tests to redirect the env var `PI_CODING_AGENT_DIR` to control `getAgentDir()` output, rather than passing the value directly.
+
+## Goals
+
+- Remove the `getAgentDir` import from `settings.ts` (0 Pi SDK imports).
+- Inject `agentDir: string` into `SettingsManager` constructor deps.
+- Make `loadSettings` accept `agentDir` as an explicit parameter.
+- Eliminate `PI_CODING_AGENT_DIR` env var manipulation from all settings tests.
+
+## Non-Goals
+
+- Removing `process.cwd()` defaults from `loadSettings`/`saveSettings` — that's a separate concern (Node.js API, not Pi SDK).
+- Pushing SDK boundaries in other files (`skill-loader.ts`, `custom-agents.ts`, `agent-runner.ts`) — tracked separately in the Phase 13 roadmap.
+- Changing the `saveSettings` signature — it only calls `projectPath(cwd)` and has no SDK dependency.
+
+## Background
+
+`settings.ts` exports a `SettingsManager` class and two free functions (`loadSettings`, `saveSettings`).
+The only SDK import is `getAgentDir`, used in the private `globalPath()` helper to compute the global settings file path (`~/.pi/agent/subagents.json`).
+
+The `SettingsManager` constructor already accepts a deps bag `{ emit, cwd, onMaxConcurrentChanged? }`.
+Adding `agentDir` to this bag follows the established injection pattern.
+
+In `index.ts`, `getAgentDir` is already imported for several other call sites (agent runner IO, agent tool, `/agents` menu).
+Adding one more usage to the `SettingsManager` construction is zero new imports.
+
+### Relevant AGENTS.md constraints
+
+- **Pi SDK boundaries:** Keep Pi SDK imports out of business-logic modules; accept the value as a parameter or callback.
+- **Code-design skill, DIP:** Default to dependency injection for non-trivial dependencies.
+
+## Design Overview
+
+### Change to `globalPath()`
+
+Currently:
+
+```typescript
+function globalPath(): string {
+  return join(getAgentDir(), "subagents.json");
+}
+```
+
+After:
+
+```typescript
+function globalPath(agentDir: string): string {
+  return join(agentDir, "subagents.json");
+}
+```
+
+### Change to `loadSettings()`
+
+Currently:
+
+```typescript
+export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+}
+```
+
+After:
+
+```typescript
+export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
+}
+```
+
+### Change to `SettingsManager` constructor
+
+Add `agentDir: string` to the deps bag:
+
+```typescript
+constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
+  this.emit = deps.emit;
+  this.cwd = deps.cwd;
+  this.agentDir = deps.agentDir;
+  this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
+}
+```
+
+`SettingsManager.load()` passes `this.agentDir` to `loadSettings`:
+
+```typescript
+load(): SubagentsSettings {
+  const settings = loadSettings(this.agentDir, this.cwd);
+  // ... rest unchanged
+}
+```
+
+### Wiring in `index.ts`
+
+```typescript
+const settings = new SettingsManager({
+  emit: (event, payload) => pi.events.emit(event, payload),
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
+});
+```
+
+## Module-Level Changes
+
+### `src/settings.ts`
+
+1. Remove `import { getAgentDir } from "@earendil-works/pi-coding-agent"`.
+2. Add `agentDir: string` field to the `SettingsManager` constructor deps interface.
+3. Store `this.agentDir = deps.agentDir` as a private readonly field.
+4. Change `globalPath()` signature to `globalPath(agentDir: string)`.
+5. Change `loadSettings` signature to `loadSettings(agentDir: string, cwd?: string)`.
+6. Update `SettingsManager.load()` to call `loadSettings(this.agentDir, this.cwd)`.
+7. Update the header comment to reflect the new injection pattern.
+
+### `src/index.ts`
+
+1. Add `agentDir: getAgentDir()` to the `SettingsManager` constructor deps object.
+
+### `test/settings.test.ts`
+
+1. Remove all `PI_CODING_AGENT_DIR` env manipulation (`originalAgentDirEnv`, `beforeEach`/`afterEach` stubs).
+2. Pass `globalDir` directly to `loadSettings(globalDir, projectDir)` in free-function tests.
+3. Add `agentDir: globalDir` (or a dummy string for non-load tests) to all `new SettingsManager(...)` calls.
+4. In `SettingsManager.load()` tests, pass `agentDir: globalDir` to the constructor.
+5. In tests that don't exercise `load()`, use `agentDir: "/nonexistent"` or similar — the value is unused.
+
+## Test Impact Analysis
+
+1. **New capability:** Free-function tests (`loadSettings`, `saveSettings`) become pure — pass `globalDir` directly instead of manipulating `PI_CODING_AGENT_DIR`.
+   This is simpler and more reliable.
+2. **Redundant cleanup:** The `originalAgentDirEnv` save/restore pattern in `beforeEach`/`afterEach` can be removed from all `describe` blocks that use it.
+3. **Existing tests stay:** All existing test scenarios remain valid; only their setup mechanics change.
+
+## TDD Order
+
+1. **Red → Green:** Change `loadSettings` signature to accept `agentDir` parameter; update `globalPath` to accept it.
+   Update all free-function tests to pass `globalDir` directly instead of env var.
+   Remove env-var manipulation from the `settings persistence` describe block.
+   Commit: `feat: inject agentDir into loadSettings to remove SDK dependency`
+
+2. **Red → Green:** Add `agentDir` to `SettingsManager` constructor deps; store as private field; thread into `load()`.
+   Update all `new SettingsManager(...)` call sites in tests.
+   Remove env-var manipulation from `SettingsManager` describe blocks.
+   Remove `getAgentDir` import from `settings.ts`.
+   Commit: `feat: inject agentDir into SettingsManager constructor`
+
+3. **Green:** Wire `agentDir: getAgentDir()` into `SettingsManager` construction in `index.ts`.
+   Run `pnpm run check` to confirm no type errors across the package.
+   Commit: `feat: wire agentDir from SDK boundary in index.ts (#218)`
+
+## Risks and Mitigations
+
+| Risk                                                                                  | Mitigation                                                                                                   |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Breaking the `loadSettings` export signature for hypothetical external callers        | The function is only called from `SettingsManager.load()` and tests; no external consumers exist.            |
+| Test count is high (~35 constructor sites) — mechanical updates could introduce typos | Steps 1 and 2 are focused; run `pnpm vitest run test/settings.test.ts` after each to confirm.                |
+| Forgetting a test site that still manipulates `PI_CODING_AGENT_DIR`                   | Grep for `PI_CODING_AGENT_DIR` after step 2 to confirm zero remaining references in `test/settings.test.ts`. |
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and follows the established injection pattern used in prior Phase 13 steps.

package/docs/plans/0219-reduce-test-duplication-top-3-clone-families.md

@@ -0,0 +1,162 @@
+---
+issue: 219
+issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
+---
+
+# Reduce test duplication — top 3 clone families
+
+## Problem statement
+
+After Phase 12, three test files carry the heaviest remaining clone families in pi-subagents:
+
+1. `test/lifecycle/agent-manager.test.ts` (929 lines) — 16 clone groups, ~160 duplicated lines.
+   Repeated inline runner stubs, worktree stubs, and manager-lifecycle boilerplate.
+2. `test/conversation-viewer.test.ts` (307 lines) — 8 clone groups, ~91 duplicated lines.
+   Near-identical `ConversationViewer` construction in every test, plus repeated width-loop assertion patterns.
+3. `test/ui/agent-config-editor.test.ts` (471 lines) — 5 clone groups, ~42 duplicated lines.
+   Repeated `makeEditor()` + `makeMenuUI()` + `fileOps.findAgentFile.mockReturnValue(...)` setup.
+
+Total target: reduce test duplication by ~200 lines (from ~1,046 combined test-setup lines to < 850).
+
+## Goals
+
+- Extract shared setup and assertion helpers for the three target test files.
+- Reduce test duplication by ~200 lines without changing test semantics.
+- Follow the existing `test/helpers/` convention (factory + matching `.test.ts` file).
+
+## Non-goals
+
+- No production code changes.
+- No new test coverage — this is purely a refactoring of existing test infrastructure.
+- Not consolidating clone families in other test files beyond the top 3.
+- Not changing any assertion logic or test structure beyond replacing inline stubs with factory calls.
+
+## Background
+
+The project already has several shared test helpers in `test/helpers/`: `make-record.ts`, `mock-session.ts`, `ui-stubs.ts`, `runner-io.ts`, `stub-ctx.ts`, `make-deps.ts`.
+Each helper has a companion `.test.ts` file — this convention must be followed.
+
+Dependencies #214 (closure-to-class conversions) and #216 (startAgent decomposition) are both closed, so the production code these tests cover is stable.
+
+## Design overview
+
+### File 1: `agent-manager.test.ts` — extract to `test/helpers/manager-stubs.ts`
+
+Five clone families to extract:
+
+1. **Never-resolving runner** — `{ run: vi.fn().mockImplementation(() => new Promise(() => {})), resume: vi.fn() }` appears 5 times.
+   Extract as `createBlockingRunner(): AgentRunner`.
+
+2. **Session-creating runner** — runner that calls `opts.onSessionCreated?.(session)` and resolves.
+   Appears 5+ times with minor variations (some emit events through the session, some don't).
+   Extract as `createSessionRunner(session?: MockSession): AgentRunner` that calls `onSessionCreated` and returns a standard result.
+
+3. **Worktree stubs with path+branch** — `{ create: vi.fn().mockReturnValue({ path, branch }), cleanup: vi.fn(() => ({ hasChanges: false })), prune: vi.fn() }` appears 4 times identically, plus 1 variant with `create` returning `undefined`.
+   Extract as `createMockWorktrees(overrides?)`.
+
+4. **Standard run result shape** — `{ responseText: "done", session, aborted: false, steered: false }` is repeated in many runner factories.
+   Extract as `createRunResult(overrides?)`.
+
+5. **Gated runner** — uses `Promise.withResolvers` to control when the runner completes.
+   Appears 2 times.
+   Keep inline — too tightly coupled to individual test flow-control to generalize cleanly.
+
+Tests that construct custom runners with unique behavior (event-emitting runners in the `lifetimeUsage` and `compactionCount` tests) keep their inline stubs — those encode test-specific emission sequences that a shared factory would obscure.
+
+### File 2: `conversation-viewer.test.ts` — inline factory + assertion helper
+
+Two clone families to extract:
+
+1. **`ConversationViewer` construction** — 15 near-identical constructor calls with the same 8 fields.
+   Extract as an inline `createTestViewer(overrides?)` factory at the top of the test file.
+   The factory provides defaults for `tui`, `session`, `record`, `activity`, `theme`, `done`, `registry`, and `wrapText`, and accepts overrides including a convenience `width` and `messages` parameter.
+
+2. **Width-loop assertion** — the `for (const w of widths) { create viewer; assertAllLinesFit(viewer.render(w), w) }` pattern repeats in 10 "render width safety" tests.
+   Extract as an inline `assertRenderFitsWidths(messages, widths?, viewerOverrides?)` helper.
+
+These helpers stay inline (not in `test/helpers/`) because they depend on file-local helpers (`mockTui`, `mockSession`, `ansiTheme`) and are only used by this one test file.
+
+### File 3: `agent-config-editor.test.ts` — inline setup helper
+
+One clone family to extract:
+
+1. **Detail-test setup** — `makeEditor()` + `makeMenuUI([...])` + `fileOps.findAgentFile.mockReturnValue(...)` + optional `fileOps.read.mockReturnValue(...)` appears in ~18 tests.
+   Extract as an inline `setupDetail(selectResults, options?)` factory that returns `{ fileOps, editor, ui }` with pre-configured mocks.
+   Options: `filePath`, `fileContent`, `config` (merged into default via `createTestAgentConfig`).
+
+This stays inline because it's specific to the `showAgentDetail` test suite and depends on file-local `testRegistry` setup.
+
+## Module-level changes
+
+### New files
+
+| File                                 | Purpose                                                                                 |
+| ------------------------------------ | --------------------------------------------------------------------------------------- |
+| `test/helpers/manager-stubs.ts`      | `createBlockingRunner`, `createSessionRunner`, `createMockWorktrees`, `createRunResult` |
+| `test/helpers/manager-stubs.test.ts` | Smoke tests for the factories                                                           |
+
+### Modified files
+
+| File                                   | Change                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| `test/lifecycle/agent-manager.test.ts` | Replace inline runner/worktree stubs with `manager-stubs` factories         |
+| `test/conversation-viewer.test.ts`     | Add `createTestViewer` + `assertRenderFitsWidths` inline, migrate all tests |
+| `test/ui/agent-config-editor.test.ts`  | Add `setupDetail` inline, migrate `showAgentDetail` tests                   |
+
+### Unchanged files
+
+No production source files are modified.
+No other test files are modified.
+
+## Test impact analysis
+
+1. **New unit tests**: `manager-stubs.test.ts` adds smoke tests verifying factory return shapes (blocking runner never resolves, session runner calls `onSessionCreated`, worktree factory returns the expected interface, run result contains the correct fields).
+2. **Simplified tests**: ~30 tests across the three files replace 3–6 lines of inline stub construction with 1-line factory calls.
+3. **Unchanged tests**: All existing test assertions remain identical — only the setup code changes.
+   Tests with custom runner behavior (event-emitting, gated, error-throwing) keep their inline stubs.
+
+## TDD order
+
+1. **Create `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts`** Add `createBlockingRunner`, `createSessionRunner`, `createMockWorktrees`, `createRunResult`.
+   Add smoke tests verifying each factory's return shape and basic behavior.
+   Commit: `test: add manager-stubs helper factories (#219)`
+
+2. **Migrate `agent-manager.test.ts` to use manager-stubs** Replace 5 inline never-resolving runners with `createBlockingRunner()`.
+   Replace 4 identical worktree stubs with `createMockWorktrees()` / `createMockWorktrees({ create: ... })`.
+   Replace inline session-creating runners with `createSessionRunner(session)` where the test only needs `onSessionCreated` wiring.
+   Replace inline run-result objects with `createRunResult()` where the default shape suffices.
+   Run `pnpm vitest run test/lifecycle/agent-manager.test.ts` to verify green.
+   Commit: `test: migrate agent-manager tests to manager-stubs (#219)`
+
+3. **Add inline factories to `conversation-viewer.test.ts` and migrate** Add `createTestViewer(overrides?)` inline factory with defaults for all 8 constructor fields.
+   Add `assertRenderFitsWidths(messages, widths?, overrides?)` inline helper.
+   Migrate all 10 "render width safety" tests to use `assertRenderFitsWidths`.
+   Migrate all 5 "safety net" tests to use `createTestViewer`.
+   Run `pnpm vitest run test/conversation-viewer.test.ts` to verify green.
+   Commit: `test: reduce conversation-viewer test duplication (#219)`
+
+4. **Add inline `setupDetail` to `agent-config-editor.test.ts` and migrate** Add `setupDetail(selectResults, options?)` returning `{ fileOps, editor, ui }`.
+   Migrate `showAgentDetail` tests to use `setupDetail`.
+   Run `pnpm vitest run test/ui/agent-config-editor.test.ts` to verify green.
+   Commit: `test: reduce agent-config-editor test duplication (#219)`
+
+5. **Final verification** Run `pnpm vitest run` (full suite) to confirm no regressions.
+   Run `pnpm run check` to confirm no type errors.
+   Commit is not needed — this is a verification-only step.
+
+## Risks and mitigations
+
+1. **Factory defaults diverge from test intent** — If a shared factory's defaults don't match what an individual test expects, assertions silently pass or fail for the wrong reason.
+   Mitigation: diff all inline stubs against the proposed factory defaults before writing the factory.
+   Keep tests with unique mock behavior inline rather than force-fitting them into a factory.
+
+2. **Over-abstraction obscures test intent** — Extracting too many details into helpers makes tests harder to read.
+   Mitigation: only extract truly duplicated boilerplate (stub construction); keep test-specific setup and assertions inline.
+   The gated runner pattern stays inline for this reason.
+
+3. **Intermediate broken state** — Partially migrated test files may have import conflicts.
+   Mitigation: each TDD step fully migrates one file before committing.
+
+## Open questions
+
+None — the issue scope is well-defined and the dependencies are resolved.

package/docs/retro/0217-extract-overwrite-guard.md

@@ -34,3 +34,30 @@ Test count: 962 → 970 (+8 new tests in `test/ui/agent-file-writer.test.ts`).
 - Both consumer refactors were straightforward one-import-add + one-block-replace edits; all existing tests passed without modification, confirming the extraction preserved exact behavior.
 - The notification label `"Ejected ${name} to"` (with trailing space absorbed by `${targetPath}`) matched the pre-existing message format `"Ejected test-agent to /path"` exactly — no test assertions changed.
 - `FileWriter`, `WriterUI`, and `Reloadable` narrow interfaces are exported from `agent-file-writer.ts`; both consumer files import the concrete types from their original sources, satisfying TypeScript's structural checker without any casts.
+
+## Stage: Final Retrospective (2026-05-26T21:00:00Z)
+
+### Session summary
+
+Full plan → TDD → ship → release lifecycle completed in a single continuous session.
+Released as `pi-subagents-v7.7.0`.
+Zero rework, zero test failures, zero CI issues.
+
+### Observations
+
+#### What went well
+
+- The Phase 13 roadmap's step-level issue decomposition produced an issue (#217) that was right-sized for fully autonomous execution — the entire lifecycle completed without any blocking questions or scope surprises.
+- ISP-narrow interfaces (`FileWriter`, `WriterUI`, `Reloadable`) structurally satisfied both consumer types without casts, confirming the plan's design.
+- Existing tests in both consumer files passed without modification after the refactors, validating that the extraction preserved exact behavior.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan split TDD steps 1 (happy-path tests) and 2 (overwrite-guard tests) for a ~10-line function with a single conditional.
+  Writing all 8 tests at once and implementing the full function body in one pass was natural; splitting them would have been artificial.
+  Self-corrected by folding into one commit.
+  Impact: added friction but no rework — the plan said "implementation should already pass" for step 2, acknowledging the fold was expected.
+
+#### What caused friction (user side)
+
+- Nothing notable — the issue was well-scoped with clear target files, a concrete smell label, and an explicit dependency chain.

package/docs/retro/0218-push-sdk-boundary-in-settings.md

@@ -0,0 +1,72 @@
+---
+issue: 218
+issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
+---
+
+# Retro: #218 — Push SDK boundary in settings.ts
+
+## Stage: Planning (2026-05-26T17:01:55Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to inject `agentDir: string` into `SettingsManager` and `loadSettings`, removing the only Pi SDK import from `settings.ts`.
+The change is straightforward — a single parameter addition threading through constructor, free function, and boundary wiring.
+
+### Observations
+
+- The change is entirely mechanical: no design ambiguity, no new abstractions, no breaking public API.
+- The main implementation effort is in test updates (~35 `new SettingsManager(...)` call sites plus ~15 `loadSettings(...)` calls), all requiring an `agentDir` argument.
+- All test `describe` blocks that manipulate `PI_CODING_AGENT_DIR` env var can drop that scaffolding entirely, simplifying setup/teardown.
+- `saveSettings` has no SDK dependency and needs no signature change — only `loadSettings` calls `globalPath()`.
+
+## Stage: Implementation — TDD (2026-05-26T17:13:26Z)
+
+### Session summary
+
+Completed all 3 plan steps across 2 commits plus 1 doc commit.
+All 970 tests pass; `settings.ts` now has 0 Pi SDK imports and all `PI_CODING_AGENT_DIR` env var manipulation is gone from `settings.test.ts`.
+
+### Observations
+
+- **Steps 1+2 combined:** Changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` forced updating `SettingsManager.load()` in the same commit — they were inseparable (esbuild skips type checks, so the old call compiled but produced wrong runtime behavior).
+  The two production changes landed in one commit with a note in the body.
+- **Test simplification was significant:** Removed `originalAgentDirEnv` save/restore scaffolding from 5 `describe` blocks; the test code shrank by 32 lines net.
+- **`/nonexistent` sentinel:** Tests that construct `SettingsManager` but never call `load()` pass `agentDir: "/nonexistent"` — a clear signal the field is unused in that scope.
+- Architecture doc Step 5 heading marked `✓` and folded into the last `feat:` commit by `pi-autoformat`.
+
+## Stage: Final Retrospective (2026-05-26T17:22:11Z)
+
+### Session summary
+
+Issue #218 went from plan to shipped release (`pi-subagents-v7.8.0`) in a single continuous session.
+Planning, TDD (2 feat commits + 1 doc commit), shipping, CI verification, issue close, and release-please merge all completed without user intervention beyond stage transitions.
+
+### Observations
+
+#### What went well
+
+- **Clean mechanical execution:** The entire change was 2 production files (`settings.ts`, `index.ts`) and 1 test file, with zero unexpected test breakage and zero rework commits.
+- **Test simplification payoff:** Removing `PI_CODING_AGENT_DIR` env var scaffolding from 5 `describe` blocks shrank the test file by 32 lines net — a tangible improvement in test readability.
+- **Ship stage model efficiency:** The `/ship-issue` stage ran on `deepseek-v4-flash`, which was appropriate for the purely mechanical push/CI/close/merge workflow.
+
+#### What caused friction (agent side)
+
+1. `wrong-abstraction` — The plan split steps 1 and 2 into separate commits, but changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` immediately broke `SettingsManager.load()` which calls it.
+   The agent recognized this during the red phase and combined them into one commit.
+   The existing testing skill rule ("When a TDD plan lists separate steps that share a type definition… fold them into one step") already covers this — the plan just didn't apply it.
+   Impact: added friction but no rework; recognized on first test run.
+2. `missing-context` — Attempted to add `| ✓ #218 |` as an extra column to one row of the architecture doc's findings table, creating a column-count mismatch.
+   The autoformatter reverted the broken table.
+   The agent then spent ~5 tool calls (`git show --stat`, `git status`, `grep` ×2, `read`) investigating what happened before switching to the Step 5 heading approach.
+   Impact: ~2 minutes of investigation; no rework beyond the heading edit.
+
+#### What caused friction (user side)
+
+- The user asked "Are we ready for shipping?"
+  which surfaced that the TDD retro stage notes were still uncommitted.
+  This was a useful checkpoint — the ship stage committed them before pushing.
+  Opportunity: the `/tdd-plan` prompt could commit retro notes as part of its final step, but the current flow (write notes, then commit in ship) is lightweight enough that enforcing it would add complexity for marginal gain.
+
+### Changes made
+
+1. Retro file updated at `packages/pi-subagents/docs/retro/0218-push-sdk-boundary-in-settings.md` — no other files changed.

package/docs/retro/0219-reduce-test-duplication-top-3-clone-families.md

@@ -0,0 +1,36 @@
+---
+issue: 219
+issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
+---
+
+# Retro: #219 — Reduce test duplication — top 3 clone families
+
+## Stage: Planning (2026-05-26T20:00:00Z)
+
+### Session summary
+
+Analyzed duplication patterns in the three target test files (`agent-manager.test.ts`, `conversation-viewer.test.ts`, `agent-config-editor.test.ts`).
+Produced a 5-step TDD plan with shared `manager-stubs.ts` helper for runner/worktree factories, plus inline factories for the two UI test files.
+
+### Observations
+
+- The agent-manager test has the most diverse clone families (runner stubs, worktree stubs, run-result shapes) — these benefit from a shared helper file since the patterns are reused across 15+ describe blocks.
+- The conversation-viewer and config-editor duplication is more localized — inline factories within each test file are the right granularity to avoid over-extraction.
+- Gated runners (using `Promise.withResolvers`) were deliberately kept inline since they encode test-specific flow control that a factory would obscure.
+- Both dependencies (#214, #216) are closed, so the production code is stable and the tests won't shift under us during implementation.
+
+## Stage: Implementation — TDD (2026-05-26T17:42:41Z)
+
+### Session summary
+
+Completed all 4 TDD cycles: created `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts` (13 smoke tests), migrated `agent-manager.test.ts`, `conversation-viewer.test.ts`, and `agent-config-editor.test.ts`.
+Test count delta: 970 → 983 (+13 from smoke tests).
+All 4 commits landed cleanly; full suite green at every step.
+
+### Observations
+
+- Target file line savings: `agent-manager.test.ts` −63, `conversation-viewer.test.ts` −58, `agent-config-editor.test.ts` −16; offset by +211 for the new helper files.
+  Net LOC is positive, but the _clone_ lines fallow detects are eliminated — the metric the issue targets.
+- The `createSessionRunner` + `createRunResult` chain required careful identity-check verification: `createRunResult(sess)` calls `toAgentSession(sess)` which casts without creating a new object, so `toBe(session)` assertions in the execution-state tests still pass. ✓
+- ESLint auto-fixed two cosmetic issues on commit (`activity = undefined` → `activity` destructuring, `session as unknown` cast removal) — caught by pre-commit hooks, not a problem in practice.
+- The `assertRenderFitsWidths` helper in `conversation-viewer.test.ts` reduced the 10 render-safety tests from ~8 lines each to 1–4 lines each; the `setupDetail` helper in `agent-config-editor.test.ts` eliminated 3 repeated setup lines per test across 18 `showAgentDetail` tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.7.0",
+  "version": "7.8.1",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/index.ts

@@ -70,6 +70,7 @@ export default function (pi: ExtensionAPI) {
   const settings = new SettingsManager({
     emit: (event, payload) => pi.events.emit(event, payload),
     cwd: process.cwd(),
+    agentDir: getAgentDir(),
     onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
   });
   settings.load();

package/src/settings.ts

@@ -1,10 +1,9 @@
 // Persistence for pi-subagents operational settings.
-// - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
+// - Global:  ~/.pi/agent/subagents.json (agentDir injected at construction) — manual defaults, never written here
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -34,11 +33,13 @@ export class SettingsManager {
 
   private readonly emit: SettingsEmit;
   private readonly cwd: string;
+  private readonly agentDir: string;
   private readonly onMaxConcurrentChanged: (() => void) | undefined;
 
-  constructor(deps: { emit: SettingsEmit; cwd: string; onMaxConcurrentChanged?: () => void }) {
+  constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
     this.emit = deps.emit;
     this.cwd = deps.cwd;
+    this.agentDir = deps.agentDir;
     this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
   }
 
@@ -84,7 +85,7 @@ export class SettingsManager {
    * Returns the raw loaded settings object.
    */
   load(): SubagentsSettings {
-    const settings = loadSettings(this.cwd);
+    const settings = loadSettings(this.agentDir, this.cwd);
     if (typeof settings.maxConcurrent === "number") this.maxConcurrent = settings.maxConcurrent;
     if (typeof settings.defaultMaxTurns === "number") this.defaultMaxTurns = settings.defaultMaxTurns;
     if (typeof settings.graceTurns === "number") this.graceTurns = settings.graceTurns;
@@ -180,8 +181,8 @@ function sanitize(raw: unknown): SubagentsSettings {
   return out;
 }
 
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
+function globalPath(agentDir: string): string {
+  return join(agentDir, "subagents.json");
 }
 
 function projectPath(cwd: string): string {
@@ -205,8 +206,8 @@ function readSettingsFile(path: string): SubagentsSettings {
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
 }
 
 /**