@gotgenes/pi-subagents 6.9.3 → 6.10.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [6.10.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.4...pi-subagents-v6.10.0) (2026-05-22)
+
+
+### Features
+
+* inject IO collaborators into assembleSessionConfig ([#132](https://github.com/gotgenes/pi-packages/issues/132)) ([74d3dbf](https://github.com/gotgenes/pi-packages/commit/74d3dbf5e67cf28f75683e55240719ad2be86490))
+
+
+### Documentation
+
+* mark Step G complete in Phase 8 roadmap ([#132](https://github.com/gotgenes/pi-packages/issues/132)) ([95512bd](https://github.com/gotgenes/pi-packages/commit/95512bdec3757d5955d13e22261a90da41cea40e))
+* plan IO collaborator injection into assembleSessionConfig ([#132](https://github.com/gotgenes/pi-packages/issues/132)) ([23c3b62](https://github.com/gotgenes/pi-packages/commit/23c3b624e8c0afb8fda72c1b5fba86cb165f78dd))
+* **retro:** add retro notes for issue [#131](https://github.com/gotgenes/pi-packages/issues/131) ([b91cee9](https://github.com/gotgenes/pi-packages/commit/b91cee9ef69f8b1ab41be986663bad22e77a8c67))
+
+## [6.9.4](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.3...pi-subagents-v6.9.4) (2026-05-22)
+
+
+### Documentation
+
+* plan consolidate shared test fixtures ([#131](https://github.com/gotgenes/pi-packages/issues/131)) ([2fe1e65](https://github.com/gotgenes/pi-packages/commit/2fe1e65024743384981c057b405f97f9c76f9b05))
+
 ## [6.9.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.2...pi-subagents-v6.9.3) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -506,8 +506,8 @@ Phase 7 eliminated all structural smells (mutable state, closure bags, callback
 Phase 8 targets the next layer: testability friction, display module cohesion, and menu decomposition.
 
 The test suite (690 tests, 1.4:1 test-to-code ratio) is comprehensive but uneven in quality.
-Two files — `session-config.test.ts` and `agent-runner.test.ts` — account for 11 of 12 total `vi.mock()` calls and rely heavily on verifying internal call sequences rather than observable outputs.
-This fragility is a symptom of production code that imports IO-touching collaborators directly instead of receiving them through injection.
+`agent-runner.test.ts` accounts for 7 of 8 remaining `vi.mock()` calls and relies heavily on verifying internal call sequences rather than observable outputs.
+This fragility is a symptom of production code that imports IO-touching collaborators directly instead of receiving them through injection. (Step G resolved `session-config.test.ts`, which previously held 4 of the 12 total mocks.)
 
 The display and menu improvements were identified during Phase 7 but deferred because they don't gate encapsulation work.
 They are included here because the display extraction unblocks menu decomposition.
@@ -517,7 +517,7 @@ They are included here because the display extraction unblocks menu decompositio
 | Symptom                       | Location                                                | Root cause                                                        |
 | ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
 | 7 `vi.mock()` calls           | `agent-runner.test.ts`                                  | Runner imports prompts, memory, skills, env, session-dir directly |
-| 4 `vi.mock()` calls           | `session-config.test.ts`                                | Assembler imports prompts, memory, skills directly                |
+| 7 `vi.mock()` calls           | `agent-runner.test.ts`                                  | Runner imports prompts, memory, skills, env, session-dir directly |
 | 52 `as any` casts             | Across test suite                                       | SDK session/context interfaces too wide to construct in tests     |
 | 3× duplicated `mockSession()` | agent-manager, record-observer, ui-observer tests       | No shared test fixture                                            |
 | 3× duplicated `makeDeps()`    | agent-tool, background-spawner, foreground-runner tests | No shared tool-deps fixture                                       |
@@ -535,26 +535,11 @@ Consolidate duplicated mock factories into `test/helpers/`.
 
 Impact: reduces test boilerplate; single source of truth for mock shapes; changes to dep interfaces propagate automatically.
 
-### Step G: Inject IO collaborators into session-config (#132)
-
-`assembleSessionConfig` is described as a pure assembler, but it directly imports three IO-touching functions: `preloadSkills` (reads `.pi/skills` files), `buildMemoryBlock` (reads `MEMORY.md`), and `buildReadOnlyMemoryBlock` (reads `MEMORY.md`).
-It also imports `buildAgentPrompt`, which is pure but mocked anyway because tests verify call arguments instead of output properties.
-
-Inject these as an `AssemblerIO` parameter:
-
-```typescript
-export interface AssemblerIO {
-  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
-  buildMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
-  buildReadOnlyMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
-  buildAgentPrompt: (config: AgentPromptConfig, cwd: string, env: EnvInfo, parentPrompt: string, extras: PromptExtras) => string;
-}
-```
-
-The production call site in `agent-runner.ts` passes the real implementations.
-Tests pass stubs or let real implementations run against controlled inputs.
+### Step G: Inject IO collaborators into session-config (#132) ✓ done
 
-Impact: eliminates all 4 `vi.mock()` calls in `session-config.test.ts`; tests verify `SessionConfig` output properties instead of mock call arguments; the assembler becomes truly pure.
+`assembleSessionConfig` now accepts `io: AssemblerIO` as a required parameter.
+`agent-runner.ts` constructs the real `AssemblerIO` from direct imports and passes it through.
+`session-config.test.ts` injects stubs — all 4 `vi.mock()` calls eliminated, assertions shifted to `SessionConfig` output properties.
 
 ### Step H: Inject SDK boundary into agent-runner (#133)
 

package/docs/plans/0131-consolidate-shared-test-fixtures.md

@@ -0,0 +1,207 @@
+---
+issue: 131
+issue_title: Consolidate shared test fixtures
+---
+
+# Consolidate shared test fixtures
+
+## Problem Statement
+
+Three `mockSession()` factories and three `makeDeps()` factories are duplicated across the test suite.
+Each copy drifts independently when production interfaces change, creating maintenance burden and inconsistent mock shapes.
+The architecture doc (Phase 8, Step F) identifies this as the first testability improvement before the IO-injection steps (G and H).
+
+## Goals
+
+- Extract `createMockSession()` into `test/helpers/mock-session.ts` — single source of truth for the subscribable session mock.
+- Extract `createToolDeps()` into `test/helpers/make-deps.ts` — builds `AgentToolDeps` with sensible defaults and override support.
+- Update all six test files to use the shared factories and remove their local copies.
+- Keep existing test behavior unchanged — this is a pure refactor with no production code changes.
+
+## Non-Goals
+
+- IO injection into `session-config` (Step G, #132) — deferred.
+- SDK boundary injection into `agent-runner` (Step H, #133) — deferred.
+- Consolidating `makeCtx()` or `makeParams()` helpers — those are specific to each tool's parameter shape and do not share enough structure to justify extraction.
+
+## Background
+
+### Existing helper
+
+`test/helpers/make-record.ts` exports `createTestRecord()`, which builds an `AgentRecord` with sensible defaults and override support.
+It has its own unit test file (`test/helpers/make-record.test.ts`).
+The two new factories follow the same pattern.
+
+### `mockSession()` — 3 copies
+
+| File                      | Shape                                                                                             |
+| ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `agent-manager.test.ts`   | `subscribe` (vi.fn), `emit`, `dispose` (vi.fn), `steer` (vi.fn), `sessionManager` — cast as `any` |
+| `record-observer.test.ts` | `subscribe` (vi.fn), `emit`                                                                       |
+| `ui/ui-observer.test.ts`  | `subscribe` (plain fn), `emit`                                                                    |
+
+The common core is `subscribe` + `emit` (the subscribable event bus).
+The `agent-manager` copy adds extra properties the other two don't need.
+
+### `makeDeps()` — 3 copies
+
+| File                               | Type             | Manager methods                                          | Widget methods                              | Extra fields                 |
+| ---------------------------------- | ---------------- | -------------------------------------------------------- | ------------------------------------------- | ---------------------------- |
+| `tools/agent-tool.test.ts`         | `AgentToolDeps`  | spawn, spawnAndWait, resume, getRecord, getMaxConcurrent | setUICtx, ensureTimer, update, markFinished | registry, agentDir, settings |
+| `tools/background-spawner.test.ts` | `BackgroundDeps` | spawn, getRecord, getMaxConcurrent                       | ensureTimer, update                         | —                            |
+| `tools/foreground-runner.test.ts`  | `ForegroundDeps` | spawnAndWait                                             | ensureTimer, markFinished                   | —                            |
+
+`AgentToolDeps` is a structural superset of both `BackgroundDeps` and `ForegroundDeps`.
+TypeScript's structural type system allows an `AgentToolDeps` value to be passed where `BackgroundDeps` or `ForegroundDeps` is expected — the narrower interfaces require a strict subset of the methods present on the wider one.
+
+## Design Overview
+
+### `createMockSession(overrides?)`
+
+Returns the subscribable event bus (core shape) merged with optional overrides.
+The core shape includes:
+
+```typescript
+interface MockSession {
+  subscribe: Mock<[fn: (event: any) => void], () => void>;
+  emit(event: any): void;       // test-only helper, not on production Session
+  dispose: Mock;
+  steer: Mock;
+  sessionManager: { getSessionFile: Mock };
+}
+```
+
+All fields are present in every call — callers that don't need `dispose` or `steer` simply ignore them.
+This avoids a discriminated "minimal vs. full" shape that would reintroduce the divergence problem.
+The `subscribe` spy is wired to a `Set<fn>` internally so `emit()` broadcasts to all subscribers, matching the existing hand-rolled pattern.
+The return type is `MockSession & Record<string, unknown>` so call sites can pass it as `any`-typed session parameters without explicit casts.
+
+Override support lets `agent-manager.test.ts` customize `steer` behavior or add fields:
+
+```typescript
+const session = createMockSession({ steer: vi.fn().mockRejectedValue(new Error("fail")) });
+```
+
+### `createToolDeps(overrides?)`
+
+Builds a full `AgentToolDeps` with mock manager, widget, activity map, registry, agent dir, and settings.
+Accepts `Partial<AgentToolDeps>` for overrides, following the same pattern as `createTestRecord()`.
+
+```typescript
+function createToolDeps(overrides?: Partial<AgentToolDeps>): AgentToolDeps;
+```
+
+Consumer call sites:
+
+```typescript
+// agent-tool.test.ts — uses the full type directly
+const deps = createToolDeps();
+const tool = createAgentTool(deps);
+
+// background-spawner.test.ts — structural typing narrows automatically
+const deps = createToolDeps();
+spawnBackground(deps, makeParams());
+
+// foreground-runner.test.ts — same structural narrowing
+const deps = createToolDeps({ manager: { spawnAndWait: vi.fn().mockResolvedValue(customRecord) } });
+await runForeground(deps, makeParams(), undefined, undefined);
+```
+
+The background and foreground tests gain unused mock methods on `manager` and `widget`, but this is harmless — the production code's ISP compliance ensures only the narrow interface methods are called.
+Tests that assert specific mock interactions (e.g., `expect(deps.manager.spawn).toHaveBeenCalled()`) continue to work because every method is a distinct `vi.fn()`.
+
+When a test needs to override a single manager method, it spreads into the nested object:
+
+```typescript
+createToolDeps({
+  manager: { ...createToolDeps().manager, spawnAndWait: vi.fn().mockRejectedValue(err) },
+});
+```
+
+This is slightly more verbose than today's flat override, but it happens rarely and the tradeoff is worthwhile for a single source of truth.
+
+Alternatively, `createToolDeps` can accept a `managerOverrides` shorthand if the nested-spread pattern proves too noisy during implementation.
+
+## Module-Level Changes
+
+### New files
+
+1. `test/helpers/mock-session.ts` — exports `createMockSession(overrides?)`.
+2. `test/helpers/mock-session.test.ts` — unit tests for `createMockSession`: verifies event broadcasting, subscribe/unsubscribe, and override merging.
+3. `test/helpers/make-deps.ts` — exports `createToolDeps(overrides?)`.
+4. `test/helpers/make-deps.test.ts` — unit tests for `createToolDeps`: verifies default shape satisfies `AgentToolDeps`, `BackgroundDeps`, and `ForegroundDeps`; verifies override merging.
+
+### Modified files
+
+1. `test/agent-manager.test.ts` — remove local `mockSession()`, import `createMockSession` from helpers.
+2. `test/record-observer.test.ts` — remove local `mockSession()`, import `createMockSession` from helpers.
+3. `test/ui/ui-observer.test.ts` — remove local `mockSession()`, import `createMockSession` from helpers.
+4. `test/tools/agent-tool.test.ts` — remove local `makeDeps()`, import `createToolDeps` from helpers.
+5. `test/tools/background-spawner.test.ts` — remove local `makeDeps()`, import `createToolDeps` from helpers.
+6. `test/tools/foreground-runner.test.ts` — remove local `makeDeps()`, import `createToolDeps` from helpers.
+
+## Test Impact Analysis
+
+1. The new factory unit tests (`mock-session.test.ts`, `make-deps.test.ts`) verify the shared fixture behavior that was previously only implicitly tested through the consumer test files.
+   This enables targeted debugging when a mock shape drifts from the production interface.
+2. No existing tests become redundant — the consumer tests exercise distinct production behavior that the factory tests do not cover.
+3. All existing tests stay as-is in terms of assertions.
+   Only the setup code (local factory → shared import) changes.
+
+## TDD Order
+
+1. **Red → Green: `createMockSession` factory.**
+   Write `test/helpers/mock-session.test.ts` — verify subscribe/emit broadcasting, unsubscribe, dispose/steer are vi.fn stubs, override merging.
+   Implement `test/helpers/mock-session.ts`.
+   Commit: `test: add createMockSession shared test fixture`
+
+2. **Green: migrate `record-observer.test.ts` to `createMockSession`.**
+   Replace local `mockSession()` with import from helpers.
+   Run test file — all tests pass unchanged.
+   Commit: `test: use createMockSession in record-observer tests`
+
+3. **Green: migrate `ui/ui-observer.test.ts` to `createMockSession`.**
+   Replace local `mockSession()` with import from helpers.
+   Run test file — all tests pass unchanged.
+   Commit: `test: use createMockSession in ui-observer tests`
+
+4. **Green: migrate `agent-manager.test.ts` to `createMockSession`.**
+   Replace local `mockSession()` with import from helpers.
+   This file uses extra fields (`sessionManager`, `steer`, `dispose`) — verify overrides or defaults cover them.
+   Run test file — all tests pass unchanged.
+   Commit: `test: use createMockSession in agent-manager tests`
+
+5. **Red → Green: `createToolDeps` factory.**
+   Write `test/helpers/make-deps.test.ts` — verify default shape, override merging, structural compatibility with `BackgroundDeps` and `ForegroundDeps`.
+   Implement `test/helpers/make-deps.ts`.
+   Commit: `test: add createToolDeps shared test fixture`
+
+6. **Green: migrate `tools/agent-tool.test.ts` to `createToolDeps`.**
+   Replace local `makeDeps()` with import from helpers.
+   Run test file — all tests pass unchanged.
+   Commit: `test: use createToolDeps in agent-tool tests`
+
+7. **Green: migrate `tools/background-spawner.test.ts` to `createToolDeps`.**
+   Replace local `makeDeps()` with import from helpers.
+   Adjust any override patterns for the wider type.
+   Run test file — all tests pass unchanged.
+   Commit: `test: use createToolDeps in background-spawner tests`
+
+8. **Green: migrate `tools/foreground-runner.test.ts` to `createToolDeps`.**
+   Replace local `makeDeps()` with import from helpers.
+   Adjust any override patterns for the wider type.
+   Run test file — all tests pass unchanged.
+   Commit: `test: use createToolDeps in foreground-runner tests`
+
+## Risks and Mitigations
+
+| Risk                                                                                                   | Mitigation                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Wider mock shape causes false-positive tests (tests pass even when production code calls wrong method) | The production interfaces are already ISP-narrow; the mock width only affects tests. Existing assertions on specific mock calls catch regressions.                                                                      |
+| Override merging doesn't handle nested objects (e.g., overriding a single manager method)              | Factory uses shallow merge for top-level fields; document that nested overrides require spreading the default nested object. Evaluate a `managerOverrides` shorthand during implementation if the pattern is too noisy. |
+| `createMockSession` return type is too loose (`any`) and hides type errors in tests                    | Return a named `MockSession` interface rather than `any`. Consumer sites that pass the mock as `any`-typed SDK parameters are already untyped at that boundary.                                                         |
+
+## Open Questions
+
+- Should `createToolDeps` accept a flat `managerOverrides` shorthand or require the caller to spread the nested object?
+  Decide during step 5 based on how verbose the migration turns out in steps 6–8.

package/docs/plans/0132-inject-io-into-session-config.md

@@ -0,0 +1,219 @@
+---
+issue: 132
+issue_title: "Inject IO collaborators into `assembleSessionConfig`"
+---
+
+# Inject IO collaborators into session-config
+
+## Problem Statement
+
+`assembleSessionConfig` is described as a pure configuration assembler, but it directly imports three IO-touching functions (`preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`) and one pure function (`buildAgentPrompt`).
+This forces `session-config.test.ts` to use 4 `vi.mock()` calls, 8 hoisted mock functions, and assertions that verify internal call sequences rather than output properties.
+The result is fragile tests that break on any internal restructuring even when observable behavior is unchanged.
+
+## Goals
+
+- Define an `AssemblerIO` interface bundling the four collaborators.
+- Add `io: AssemblerIO` as a parameter to `assembleSessionConfig()`.
+- Replace direct imports of the four functions with calls through `io`.
+- Update the single production call site in `agent-runner.ts` to pass real implementations.
+- Eliminate all 4 `vi.mock()` calls in `session-config.test.ts`.
+- Shift test assertions toward output-property verification.
+
+## Non-Goals
+
+- SDK boundary injection into `agent-runner` (Step H, #133) — depends on this change but is deferred to its own issue.
+- Consolidating shared test fixtures (#131) — independent refactor that can land before or after.
+- Changing the behavior of `assembleSessionConfig` — this is a pure structural refactor.
+- Injecting `getMemoryToolNames` / `getReadOnlyMemoryToolNames` — these are pure utility functions with no IO; they stay as direct imports.
+
+## Background
+
+### Current state
+
+`session-config.ts` imports four functions used during assembly:
+
+| Function                   | Module            | IO?                            | Purpose in assembler                    |
+| -------------------------- | ----------------- | ------------------------------ | --------------------------------------- |
+| `preloadSkills`            | `skill-loader.ts` | Yes (reads `.pi/skills` files) | Loads skill content into prompt extras  |
+| `buildMemoryBlock`         | `memory.ts`       | Yes (reads `MEMORY.md`)        | Builds read-write memory prompt section |
+| `buildReadOnlyMemoryBlock` | `memory.ts`       | Yes (reads `MEMORY.md`)        | Builds read-only memory prompt section  |
+| `buildAgentPrompt`         | `prompts.ts`      | No (pure)                      | Assembles final system prompt string    |
+
+The test file mocks all four via `vi.mock()` plus mocks `getMemoryToolNames` and `getReadOnlyMemoryToolNames` from `agent-types.ts` (pure functions that are mocked only for call-argument verification).
+
+### Established DI pattern
+
+`AgentManager` already injects `AgentRunner` via its constructor options — the same tell-don't-ask pattern used here.
+`assembleSessionConfig` already receives an `AgentConfigLookup` registry by parameter (migrated in #80/#108), demonstrating the incremental injection approach.
+
+### Architecture reference
+
+Phase 8, Step G in `docs/architecture/architecture.md`.
+
+### Constraints from AGENTS.md
+
+- Keep scope tight; prefer small, reversible changes.
+- Prefer explicit configuration over hidden behavior.
+- Business logic should be pure functions — keep IO at the edges.
+
+## Design Overview
+
+### `AssemblerIO` interface
+
+Defined in `session-config.ts` alongside the existing assembler types:
+
+```typescript
+export interface AssemblerIO {
+  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
+  buildMemoryBlock: (
+    name: string,
+    scope: MemoryScope,
+    cwd: string,
+  ) => string;
+  buildReadOnlyMemoryBlock: (
+    name: string,
+    scope: MemoryScope,
+    cwd: string,
+  ) => string;
+  buildAgentPrompt: (
+    config: AgentPromptConfig,
+    cwd: string,
+    env: EnvInfo,
+    parentPrompt?: string,
+    extras?: PromptExtras,
+  ) => string;
+}
+```
+
+The interface uses the same parameter types as the real functions.
+The assembler calls `io.preloadSkills(...)` etc. instead of the direct imports.
+
+### Call site in `agent-runner.ts`
+
+```typescript
+import { preloadSkills } from "./skill-loader.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { buildAgentPrompt } from "./prompts.js";
+
+const io: AssemblerIO = {
+  preloadSkills,
+  buildMemoryBlock,
+  buildReadOnlyMemoryBlock,
+  buildAgentPrompt,
+};
+
+const cfg = assembleSessionConfig(type, ctx, options, env, registry, io);
+```
+
+The runner constructs the real IO object once and passes it through.
+This keeps IO at the edge (runner) and makes the assembler a genuine pure function.
+
+### Test-side stubs
+
+Tests create a plain object with `vi.fn()` stubs satisfying `AssemblerIO`:
+
+```typescript
+const io: AssemblerIO = {
+  preloadSkills: vi.fn(() => []),
+  buildMemoryBlock: vi.fn(() => "memory block"),
+  buildReadOnlyMemoryBlock: vi.fn(() => "read-only memory block"),
+  buildAgentPrompt: vi.fn(() => "assembled system prompt"),
+};
+```
+
+This replaces all four `vi.mock()` calls and the hoisted mocks for those modules.
+
+### Pure utility functions stay as direct imports
+
+`getMemoryToolNames` and `getReadOnlyMemoryToolNames` from `agent-types.ts` are pure functions (no IO, no filesystem access).
+After the IO injection, the test's `vi.mock("../src/agent-types.js", ...)` can be removed and real implementations used.
+Tests that previously controlled these mocks to verify call arguments will instead set up input tool names to produce the desired output from the real functions, then assert on the returned `SessionConfig.toolNames`.
+
+## Module-Level Changes
+
+### Modified files
+
+1. `src/session-config.ts`
+   - Add `AssemblerIO` interface export.
+   - Add `io: AssemblerIO` parameter to `assembleSessionConfig()` (after `registry`).
+   - Replace `preloadSkills(...)` with `io.preloadSkills(...)`.
+   - Replace `buildMemoryBlock(...)` with `io.buildMemoryBlock(...)`.
+   - Replace `buildReadOnlyMemoryBlock(...)` with `io.buildReadOnlyMemoryBlock(...)`.
+   - Replace `buildAgentPrompt(...)` with `io.buildAgentPrompt(...)`.
+   - Remove imports of `preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`, `buildAgentPrompt`.
+   - Keep imports of `getMemoryToolNames`, `getReadOnlyMemoryToolNames` (pure, no change).
+
+2. `src/agent-runner.ts`
+   - Add imports for `preloadSkills`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`, `buildAgentPrompt`.
+   - Import `AssemblerIO` type from `session-config.ts`.
+   - Construct `AssemblerIO` object from real implementations.
+   - Pass `io` to `assembleSessionConfig()`.
+
+3. `test/session-config.test.ts`
+   - Remove all 4 `vi.mock()` calls and the corresponding hoisted mocks.
+   - Create `io` stub object with `vi.fn()` implementations.
+   - Pass `io` to every `assembleSessionConfig()` call.
+   - Update memory-section tests to use real `getMemoryToolNames` / `getReadOnlyMemoryToolNames`.
+   - Migrate mock-call assertions to output-property assertions where the output already captures the information.
+
+## Test Impact Analysis
+
+1. The IO injection enables testing `assembleSessionConfig` without any module mocking.
+   Tests can choose to inject real implementations with controlled inputs (integration-style) or stubs (unit-style).
+   Previously this was impossible without `vi.mock()`.
+
+2. Several existing tests that only verified mock-call arguments become redundant once we verify the same information through output properties (e.g., "calls buildAgentPrompt with env, cwd, parentSystemPrompt, and extras" is redundant if we verify `result.systemPrompt` reflects those inputs).
+   These can be simplified or removed.
+
+3. Tests for model resolution, isolated mode, thinking level, and unknown-type fallback stay as-is — they already assert output properties and are unaffected by the IO injection.
+
+## TDD Order
+
+1. **Define `AssemblerIO` and inject into `assembleSessionConfig`.**
+   Add the `AssemblerIO` interface to `session-config.ts`.
+   Add `io: AssemblerIO` as a required parameter.
+   Replace the 4 direct function calls with `io.*` calls.
+   Remove the 4 function imports from `session-config.ts`.
+   Add the 4 imports to `agent-runner.ts` and construct the `io` object at the call site.
+   Run `pnpm run check` to verify types compile.
+   Commit: `feat: inject IO collaborators into assembleSessionConfig (#132)`
+
+2. **Migrate test file to use injected IO stubs.**
+   Create an `io` stub object with `vi.fn()` stubs matching the existing hoisted mocks' default return values.
+   Pass `io` to all `assembleSessionConfig()` calls.
+   Remove the 3 `vi.mock()` calls for `prompts.js`, `memory.js`, and `skill-loader.js`.
+   Remove the corresponding hoisted mock variables (`mockBuildAgentPrompt`, `mockBuildMemoryBlock`, `mockBuildReadOnlyMemoryBlock`, `mockPreloadSkills`).
+   Update `beforeEach` to reset the `io` stubs instead.
+   All existing tests pass with the same assertions (io stubs replace module mocks).
+   Commit: `test: replace vi.mock with injected IO stubs in session-config tests`
+
+3. **Drop the `agent-types.js` mock; use real pure functions.**
+   Remove the `vi.mock("../src/agent-types.js", ...)` call and the `importOriginal` pattern.
+   Remove hoisted `mockGetMemoryToolNames` and `mockGetReadOnlyMemoryToolNames`.
+   Update memory-section tests to set up `mockGetToolNamesForType` return values that produce the desired output from the real `getMemoryToolNames` / `getReadOnlyMemoryToolNames`.
+   Assertions shift from "mock was called with Set" to "result.toolNames contains expected names".
+   Commit: `test: use real getMemoryToolNames in session-config tests`
+
+4. **Shift remaining mock-call assertions to output-property checks.**
+   Replace `expect(io.buildAgentPrompt).toHaveBeenCalledWith(...)` with assertions on `result.systemPrompt` (requires io.buildAgentPrompt stub to echo identifying values).
+   Replace `expect(io.preloadSkills).toHaveBeenCalledWith(skillList, "/tmp")` with `result.extras.skillBlocks` checks (already partially present).
+   Remove test cases that are now fully redundant with output-based tests in the same describe block.
+   Clean up any unused imports and variables.
+   Commit: `test: verify output properties in session-config tests (#132)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                      | Mitigation                                                                                                                                                                              |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Adding a parameter to `assembleSessionConfig` breaks the `agent-runner.ts` call site                      | Only one production call site exists; updated in the same commit (step 1). `pnpm run check` verifies.                                                                                   |
+| Removing `vi.mock()` causes tests to accidentally call real IO functions                                  | The real functions are no longer imported by `session-config.ts` after step 1. The module simply doesn't reach them. Vitest will error if any unmocked import is called.                |
+| Using real `getMemoryToolNames` / `getReadOnlyMemoryToolNames` makes tests depend on their implementation | These are pure, stable utility functions (return tool names from a set). Their behavior is well-defined and unlikely to change. Using real implementations is more robust than mocking. |
+| Step 2 touches 40+ call sites in the test file                                                            | All changes are mechanical (add `, io` argument). A find-and-replace handles it. Each call already passes `mockAgentLookup` as the last arg; the new arg follows the same pattern.      |
+
+## Open Questions
+
+- Should `AssemblerIO` be co-located in `session-config.ts` or extracted to a separate `session-config-types.ts`?
+  The interface is small (4 methods) and tightly coupled to the assembler.
+  Co-location in `session-config.ts` follows the existing pattern (`AssemblerContext`, `AssemblerOptions`, `SessionConfig` are all in the same file).
+  Extract only if it grows or gains consumers beyond `agent-runner.ts`.

package/docs/retro/0131-consolidate-shared-test-fixtures.md

@@ -0,0 +1,46 @@
+---
+issue: 131
+issue_title: Consolidate shared test fixtures
+---
+
+# Retro: #131 — Consolidate shared test fixtures
+
+## Final Retrospective (2026-05-22T11:30:00Z)
+
+### Session summary
+
+Planned and implemented the consolidation of six duplicated test factories into two shared helpers (`createMockSession` in `test/helpers/mock-session.ts`, `createToolDeps` in `test/helpers/make-deps.ts`).
+All 715 tests pass, released as `pi-subagents-v6.9.4`.
+The implementation was a pure test refactor with no production code changes.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift approach worked cleanly: create factory → migrate one consumer at a time → verify green after each step.
+  Each migration commit was small and isolated, making failures easy to diagnose.
+- Structural typing as a strategy proved out — `createToolDeps()` returns `AgentToolDeps` (the superset), and `spawnBackground(deps, ...)` and `runForeground(deps, ...)` accept their narrow `BackgroundDeps`/`ForegroundDeps` interfaces without any casting.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Plan used `registry.resolve("general-purpose", "/dir")` in the `make-deps.test.ts` test, but `AgentTypeRegistry` has no `resolve` method — the correct method is `resolveAgentConfig()`.
+  Impact: one test failure during step 5 red→green, fixed immediately with no rework.
+
+- `missing-context` — Default values differed between the old narrow factories and the new shared factory: `"bg-1"` vs `"agent-1"` for spawn IDs (`background-spawner.test.ts`), `"Task done."` vs `"All done."` for result text (`foreground-runner.test.ts`).
+  Impact: two test failures in step 7, one in step 8, each requiring assertion updates before the migration step could pass.
+
+- `missing-context` — `MockSession` interface used `ReturnType<typeof vi.fn>` which expands to `Mock<Procedure | Constructable>` in Vitest v4 — a union type TypeScript cannot call.
+  Impact: `pnpm run check` failed after all TDD steps were done, requiring a separate `style:` commit to switch to explicitly parameterized `Mock<() => void>` etc.
+
+- `missing-context` — Removed the `AgentToolDeps` import from `agent-tool.test.ts` without checking that the `execute()` helper still referenced it.
+  Impact: caught in the same `pnpm run check` pass, fixed in the same `style:` commit.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The plan was unambiguous, and the session ran autonomously through all 8 TDD steps plus post-checks without intervention.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added TDD planning rule for diffing default values when consolidating duplicate test factories.
+2. `.pi/skills/testing/SKILL.md` — added Vitest mock pattern rule for typing mock fields with `Mock<specific-signature>` instead of `ReturnType<typeof vi.fn>`.

package/package.json

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

package/src/agent-runner.ts

@@ -15,9 +15,12 @@ import {
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
 import { detectEnv } from "./env.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import type { ParentSnapshot } from "./parent-snapshot.js";
-import { assembleSessionConfig } from "./session-config.js";
+import { buildAgentPrompt } from "./prompts.js";
+import { type AssemblerIO, assembleSessionConfig } from "./session-config.js";
 import { deriveSubagentSessionDir } from "./session-dir.js";
+import { preloadSkills } from "./skill-loader.js";
 import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -178,6 +181,12 @@ export async function runAgent(
   const env = await detectEnv(options.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
+  const io: AssemblerIO = {
+    preloadSkills,
+    buildMemoryBlock,
+    buildReadOnlyMemoryBlock,
+    buildAgentPrompt,
+  };
   const cfg = assembleSessionConfig(
     type,
     {
@@ -194,6 +203,7 @@ export async function runAgent(
     },
     env,
     options.registry,
+    io,
   );
 
   const agentDir = getAgentDir();

package/src/session-config.ts

@@ -16,13 +16,42 @@ import {
   getReadOnlyMemoryToolNames,
 } from "./agent-types.js";
 import type { EnvInfo } from "./env.js";
-import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
-import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
-import { preloadSkills } from "./skill-loader.js";
-import type { SubagentType, ThinkingLevel } from "./types.js";
+import type { PromptExtras } from "./prompts.js";
+import type { PreloadedSkill } from "./skill-loader.js";
+import type {
+  AgentPromptConfig,
+  MemoryScope,
+  SubagentType,
+  ThinkingLevel,
+} from "./types.js";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
+/**
+ * IO collaborators injected into `assembleSessionConfig`.
+ *
+ * Bundling the four IO-touching (or promptly testable) functions into a single
+ * interface keeps the assembler free of direct module imports and makes it
+ * trivially testable without `vi.mock()` — callers inject real implementations
+ * at the edge (`agent-runner.ts`) or stubs in tests.
+ */
+export interface AssemblerIO {
+  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
+  buildMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
+  buildReadOnlyMemoryBlock: (
+    name: string,
+    scope: MemoryScope,
+    cwd: string,
+  ) => string;
+  buildAgentPrompt: (
+    config: AgentPromptConfig,
+    cwd: string,
+    env: EnvInfo,
+    parentPrompt?: string,
+    extras?: PromptExtras,
+  ) => string;
+}
+
 /**
  * Narrow context the assembler reads from the parent session.
  * Tests construct plain objects satisfying this interface — no SDK mocking needed.
@@ -132,8 +161,8 @@ function resolveDefaultModel(
 /**
  * Assemble all configuration needed to create an agent session.
  *
- * Synchronous and side-effect-free (beyond calling `preloadSkills` which reads
- * the filesystem). The caller is responsible for resolving `EnvInfo` beforehand
+ * Synchronous and side-effect-free — all IO is delegated through the `io`
+ * parameter. The caller is responsible for resolving `EnvInfo` beforehand
  * via `detectEnv()`.
  *
  * @param type       The subagent type name (case-insensitive registry lookup).
@@ -141,6 +170,7 @@ function resolveDefaultModel(
  * @param options    Per-call overrides (cwd, isolated, model, thinkingLevel).
  * @param env        Pre-resolved environment info from `detectEnv()`.
  * @param registry   Agent config lookup — provides resolveAgentConfig and getToolNamesForType.
+ * @param io         IO collaborators (skill loader, memory builder, prompt builder).
  */
 export function assembleSessionConfig(
   type: SubagentType,
@@ -148,6 +178,7 @@ export function assembleSessionConfig(
   options: AssemblerOptions,
   env: EnvInfo,
   registry: AgentConfigLookup,
+  io: AssemblerIO,
 ): SessionConfig {
   const agentConfig = registry.resolveAgentConfig(type);
 
@@ -162,7 +193,7 @@ export function assembleSessionConfig(
 
   // Skill preloading: when skills is string[], preload their content into the prompt
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, effectiveCwd);
+    const loaded = io.preloadSkills(skills, effectiveCwd);
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -185,7 +216,7 @@ export function assembleSessionConfig(
     if (hasWriteTools) {
       const extraNames = getMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildMemoryBlock(
+      extras.memoryBlock = io.buildMemoryBlock(
         agentConfig.name,
         agentConfig.memory,
         effectiveCwd,
@@ -193,7 +224,7 @@ export function assembleSessionConfig(
     } else {
       const extraNames = getReadOnlyMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildReadOnlyMemoryBlock(
+      extras.memoryBlock = io.buildReadOnlyMemoryBlock(
         agentConfig.name,
         agentConfig.memory,
         effectiveCwd,
@@ -202,7 +233,7 @@ export function assembleSessionConfig(
   }
 
   // Build system prompt from the resolved agent config
-  const systemPrompt = buildAgentPrompt(
+  const systemPrompt = io.buildAgentPrompt(
     agentConfig,
     effectiveCwd,
     env,