@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0123-remove-vi-fn-cast-smell.md

@@ -1,179 +0,0 @@
----
-issue: 123
-issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
----
-
-# Remove vi.fn() cast smell from test helpers
-
-## Problem Statement
-
-Several test files construct mock objects typed to narrow interfaces (`AgentManagerLike`, `LifecycleRuntime`, `LifecycleManager`, `ToolStartRuntime`).
-Because the returned objects are typed to the interface — not to Vitest's mock types — tests that need to configure individual method stubs are forced to cast:
-
-```typescript
-(deps.manager.abort as ReturnType<typeof vi.fn>).mockReturnValue(false);
-(deps.manager.getRecord as ReturnType<typeof vi.fn>).mockReturnValue(record);
-```
-
-This silences TypeScript without constraining the call's return type — if `getRecord`'s return type changes, the cast won't catch it.
-Nine occurrences exist across three test files.
-
-## Goals
-
-- Eliminate all `as ReturnType<typeof vi.fn>` casts from the test suite.
-- Preserve type safety: mock configuration calls should be checked against the real method signatures.
-- Keep the change minimal — this is a test hygiene fix, not a structural redesign.
-
-## Non-Goals
-
-- Changing `AgentManagerLike`, `LifecycleRuntime`, `LifecycleManager`, `ToolStartRuntime`, or any production code.
-- Restructuring test layout or merging describe blocks.
-
-## Background
-
-The cast pattern was noted during #111 implementation and preserved to keep scope tight.
-Issue #111 (split `AgentRecord` lifecycle state) is now closed and implemented.
-
-### Affected files
-
-| File                               | Occurrences | Interface                              |
-| ---------------------------------- | ----------- | -------------------------------------- |
-| `test/service-adapter.test.ts`     | 5           | `AgentManagerLike`                     |
-| `test/handlers/lifecycle.test.ts`  | 2           | `LifecycleRuntime`, `LifecycleManager` |
-| `test/handlers/tool-start.test.ts` | 2           | `ToolStartRuntime`                     |
-
-### Cast sites by file
-
-`service-adapter.test.ts` — the "steer, abort, waitForAll, hasRunning" block's `createDeps` returns `AdapterDeps` directly.
-Five casts reconfigure `getRecord`, `abort`, or `queueSteer` after construction:
-
-1. `(deps.manager.abort as ReturnType<typeof vi.fn>).mockReturnValue(false)`
-2. `(deps.manager.getRecord as ReturnType<typeof vi.fn>).mockReturnValue({...})` (×4)
-
-`lifecycle.test.ts` — mock objects are assigned to `let` variables in `beforeEach`, typed to `LifecycleRuntime` and `LifecycleManager`.
-Two casts reconfigure methods to track call order:
-
-1. `(runtime.setSessionContext as ReturnType<typeof vi.fn>).mockImplementation(...)`
-2. `(manager.clearCompleted as ReturnType<typeof vi.fn>).mockImplementation(...)`
-
-Note: the same file already uses `vi.mocked()` in the shutdown-order test — both patterns coexist, which is itself a consistency smell.
-
-`tool-start.test.ts` — mock object assigned to a `let` variable typed to `ToolStartRuntime`.
-Two casts reconfigure methods to track call order:
-
-1. `(runtime.setUICtx as ReturnType<typeof vi.fn>).mockImplementation(...)`
-2. `(runtime.onTurnStart as ReturnType<typeof vi.fn>).mockImplementation(...)`
-
-### Approach: named-variable extraction
-
-Extract individual `vi.fn()` stubs into named variables.
-This is the approach the issue recommends and it aligns with the testing skill's guidance on extractable stubs.
-
-The alternative — `vi.mocked()` — is already used in `lifecycle.test.ts` for the shutdown-order test and works for hand-built mocks, but is semantically less clean: `vi.mocked()` asserts that a value is already a mock, which is true here but opaque to readers.
-Named variables make the mock-ness explicit at the construction site.
-
-For `lifecycle.test.ts`, the named-variable approach also eliminates the inconsistency between the two ordering tests — one currently uses `vi.mocked()` and the other uses casts.
-After this change both will use named stubs.
-
-## Design Overview
-
-### service-adapter.test.ts
-
-Refactor the "steer, abort, waitForAll, hasRunning" block's `createDeps` to return named stubs:
-
-```typescript
-function createDeps(overrides: Partial<AdapterDeps> = {}) {
-  const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>();
-  const mockAbort = vi.fn<AgentManagerLike["abort"]>(() => true);
-  const mockQueueSteer = vi.fn<AgentManagerLike["queueSteer"]>(() => true);
-
-  const deps: AdapterDeps = {
-    manager: {
-      spawn: vi.fn(() => "id"),
-      getRecord: mockGetRecord,
-      listAgents: vi.fn(() => []),
-      abort: mockAbort,
-      waitForAll: vi.fn(async () => {}),
-      hasRunning: vi.fn(() => true),
-      queueSteer: mockQueueSteer,
-    },
-    resolveModel: vi.fn(),
-    getCtx: () => ({ pi: {}, ctx: {} }),
-    getModelRegistry: () => ({ find: () => null, getAll: () => [] }),
-    ...overrides,
-  };
-
-  return { deps, mockGetRecord, mockAbort, mockQueueSteer };
-}
-```
-
-Callers destructure what they need:
-
-```typescript
-const { deps, mockAbort } = createDeps();
-mockAbort.mockReturnValue(false);  // ← type-checked, no cast
-```
-
-### lifecycle.test.ts
-
-Promote the `beforeEach`-scoped `runtime` and `manager` mock construction to use named stubs.
-The stubs that need reconfiguration (`setSessionContext`, `clearCompleted`) become named `let` variables alongside the existing `runtime`/`manager` lets, reset in `beforeEach`:
-
-```typescript
-let mockSetSessionContext: MockInstance<LifecycleRuntime["setSessionContext"]>;
-let mockClearCompleted: MockInstance<LifecycleManager["clearCompleted"]>;
-// ...assigned in beforeEach when building runtime/manager
-```
-
-Also convert the shutdown-order test's `vi.mocked()` calls to the same pattern for consistency — `unpublishService`, `clearSessionContext`, `abortAll`, `disposeNotifications`, `dispose` all become named stubs.
-
-### tool-start.test.ts
-
-Same pattern: promote `setUICtx` and `onTurnStart` to named `let` variables:
-
-```typescript
-let mockSetUICtx: MockInstance<ToolStartRuntime["setUICtx"]>;
-let mockOnTurnStart: MockInstance<ToolStartRuntime["onTurnStart"]>;
-```
-
-## Module-Level Changes
-
-| File                               | Change                                                                                                                                                                                                |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `test/service-adapter.test.ts`     | Refactor `createDeps` in the "steer, abort, waitForAll, hasRunning" block to return named mock stubs alongside `deps`. Update all 5 cast sites to use named stubs.                                    |
-| `test/handlers/lifecycle.test.ts`  | Extract `mockSetSessionContext`, `mockClearCompleted`, `mockAbortAll`, `mockDispose`, `mockClearSessionContext` as named `let` variables. Replace 2 casts and 5 `vi.mocked()` calls with named stubs. |
-| `test/handlers/tool-start.test.ts` | Extract `mockSetUICtx` and `mockOnTurnStart` as named `let` variables. Replace 2 casts with named stubs.                                                                                              |
-
-No production files are changed.
-
-## Test Impact Analysis
-
-1. No new tests are added — this is a refactoring of existing test infrastructure.
-2. No tests become redundant — every existing assertion stays.
-3. All existing tests must pass unchanged; only the mock-wiring changes.
-
-## TDD Order
-
-1. **Commit:** Refactor `createDeps` in `service-adapter.test.ts` to return named stubs; update all 5 cast sites.
-   All tests pass before and after.
-   Commit: `test: remove vi.fn() cast smell from service-adapter tests (#123)`
-2. **Commit:** Extract named stubs in `lifecycle.test.ts`; replace 2 casts and 5 `vi.mocked()` calls.
-   All tests pass.
-   Commit: `test: remove vi.fn() cast smell from lifecycle tests (#123)`
-3. **Commit:** Extract named stubs in `tool-start.test.ts`; replace 2 casts.
-   All tests pass.
-   Commit: `test: remove vi.fn() cast smell from tool-start tests (#123)`
-
-Each step is an independent file — order doesn't matter, but one-file-per-commit keeps diffs reviewable.
-
-## Risks and Mitigations
-
-| Risk                                                                                                                          | Mitigation                                                                                              |
-| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| Overrides via `...overrides` in `service-adapter.test.ts` could replace a manager method, leaving the named stub disconnected | Only `manager`-level overrides are spread; individual method overrides aren't used in this block.       |
-| Named stubs add return-surface to helpers                                                                                     | Each helper is test-local and the extra names are self-documenting. The alternative (casting) is worse. |
-| Converting `vi.mocked()` in `lifecycle.test.ts` shutdown test expands scope slightly beyond the cast pattern                  | Worth it for consistency — mixing `vi.mocked()` and named stubs in the same file is a different smell.  |
-
-## Open Questions
-
-None — the issue is fully scoped and the approach is established in the codebase.

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

@@ -1,207 +0,0 @@
----
-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

@@ -1,219 +0,0 @@
----
-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`.