@gotgenes/pi-subagents 16.3.1 → 16.4.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [16.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.3.1...pi-subagents-v16.4.0) (2026-06-16)
+
+
+### Features
+
+* **pi-subagents:** add loadLayeredSettings layered config loader ([2eeba78](https://github.com/gotgenes/pi-packages/commit/2eeba78230bd4537fa568641d4a77a6f1824271c))
+* **pi-subagents:** export loadLayeredSettings via ./settings subpath ([cefe7f6](https://github.com/gotgenes/pi-packages/commit/cefe7f6b7a9133cd0bbcc523ac8b34e48fce0a58))
+
 ## [16.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.3.0...pi-subagents-v16.3.1) (2026-06-16)
 
 

package/README.md

@@ -360,6 +360,53 @@ When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permissio
 No configuration is required.
 When `@gotgenes/pi-permission-system` is not installed, the lifecycle events have no subscriber — a harmless no-op.
 
+## For Extension Authors
+
+This package exposes two public subpath exports for companion extensions to import from the published tarball.
+
+### `@gotgenes/pi-subagents` — cross-extension service contract
+
+Access the subagent service from another extension at runtime:
+
+```typescript
+const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+const svc = getSubagentsService();
+svc?.spawn("Explore", "Check for stale TODOs");
+```
+
+Declare this package as an optional peer dependency.
+See `src/service/service.ts` for the full `SubagentsService` interface and the `WorkspaceProvider` seam.
+
+### `@gotgenes/pi-subagents/settings` — layered config loader
+
+Extensions that store configuration in JSON files can use the shared layered loader, which reads a global file (`<agentDir>/<filename>`) and a project file (`<cwd>/.pi/<filename>`) and merges them — project wins on conflicts, missing files are silent, malformed files warn and fall back:
+
+```typescript
+import { loadLayeredSettings, type LayeredSettingsSource } from "@gotgenes/pi-subagents/settings";
+
+interface MyConfig { enabled?: boolean; limit?: number }
+
+function sanitize(raw: unknown): Partial<MyConfig> {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: Partial<MyConfig> = {};
+  if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+  if (typeof r.limit === "number") out.limit = r.limit;
+  return out;
+}
+
+const config = loadLayeredSettings<MyConfig>({
+  agentDir,          // Pi runtime agent home directory
+  cwd,               // project root — project file lives at <cwd>/.pi/<filename>
+  filename: "my-extension.json",
+  sanitize,
+  warnLabel: "my-extension",  // prefix for the malformed-file stderr warning
+});
+```
+
+`loadLayeredSettings` returns `Partial<T>` (all fields optional); apply your defaults after the call.
+It never throws — all error conditions produce a `console.warn` and return `{}`.
+
 ## Architecture
 
 This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.

package/dist/settings.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Generic layered settings loader for `@gotgenes/pi-*` extensions.
+ *
+ * Extensions that store configuration in JSON files under a global agent
+ * directory and a per-project `.pi/` folder share the same three-step idiom:
+ *
+ *   1. Read the global file (`<agentDir>/<filename>`).
+ *   2. Read the project file (`<cwd>/.pi/<filename>`).
+ *   3. Merge them — project wins on conflicts — and return the result.
+ *
+ * Both layers are optional: a missing file is silent (`{}`), and a file that
+ * cannot be parsed warns to stderr and is treated as absent so startup
+ * proceeds normally.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { loadLayeredSettings, type LayeredSettingsSource } from "@gotgenes/pi-subagents/settings";
+ *
+ * interface MyConfig { enabled?: boolean; limit?: number }
+ *
+ * function sanitize(raw: unknown): Partial<MyConfig> {
+ *   if (!raw || typeof raw !== "object") return {};
+ *   const r = raw as Record<string, unknown>;
+ *   const out: Partial<MyConfig> = {};
+ *   if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+ *   if (typeof r.limit === "number") out.limit = r.limit;
+ *   return out;
+ * }
+ *
+ * const config = loadLayeredSettings<MyConfig>({
+ *   agentDir,     // e.g. from the Pi runtime env — the agent home directory
+ *   cwd,          // project root — project file is at <cwd>/.pi/<filename>
+ *   filename: "my-extension.json",
+ *   sanitize,
+ *   warnLabel: "my-extension",
+ * });
+ * ```
+ *
+ * @public
+ */
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @public
+ */
+interface LayeredSettingsSource<T> {
+    /** Directory holding the global settings file (typically the Pi agent dir). */
+    agentDir: string;
+    /** Project root; the project file lives at `<cwd>/.pi/<filename>`. */
+    cwd: string;
+    /** Base filename for both layers, e.g. `"subagents.json"`. */
+    filename: string;
+    /**
+     * Validate and coerce parsed JSON into a partial settings object.
+     * Unknown or invalid fields should be silently dropped — return `{}` for
+     * unrecognised shapes. Never throw.
+     */
+    sanitize: (raw: unknown) => Partial<T>;
+    /**
+     * Short label used in the malformed-file warning prefix,
+     * e.g. `"pi-subagents"` → `"[pi-subagents] Ignoring malformed settings at …"`.
+     */
+    warnLabel: string;
+}
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ *
+ * - A missing file is silent — returns `{}` for that layer.
+ * - A file that exists but cannot be parsed warns to stderr and returns `{}` for
+ *   that layer, so startup proceeds normally.
+ * - The two layers are merged with a shallow spread; project keys win.
+ *
+ * Throws nothing. All error conditions produce a warning and fall back to `{}`.
+ *
+ * @public
+ */
+declare function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T>;
+
+export { loadLayeredSettings };
+export type { LayeredSettingsSource };

package/docs/architecture/architecture.md

@@ -643,17 +643,17 @@ That method — testability friction as a boundary probe, with its limits — is
 
 ### Health metrics
 
-| Metric                     | Value                                   |
-| -------------------------- | --------------------------------------- |
-| Health score               | 78/100 (B)                              |
-| Total LOC                  | 8,356 (61 files, as of Phase 17 Step 5) |
-| Dead code                  | 0 files, 0 exports                      |
-| Maintainability index      | 90.8 (good)                             |
-| Avg cyclomatic complexity  | 1.4                                     |
-| P90 cyclomatic complexity  | 2                                       |
-| Production duplication     | 11 lines (1 internal clone group)       |
-| Test duplication           | 42 clone groups, 661 lines              |
-| Fallow refactoring targets | 0                                       |
+| Metric                     | Value                                        |
+| -------------------------- | -------------------------------------------- |
+| Health score               | 78/100 (B)                                   |
+| Total LOC                  | 8,356 (61 files, as of Phase 17 Step 5)      |
+| Dead code                  | 0 files, 0 exports                           |
+| Maintainability index      | 90.8 (good)                                  |
+| Avg cyclomatic complexity  | 1.4                                          |
+| P90 cyclomatic complexity  | 2                                            |
+| Production duplication     | 11 lines (1 internal clone group)            |
+| Test duplication           | 24 clone groups, 355 lines (Phase 17 Step 8) |
+| Fallow refactoring targets | 0                                            |
 
 ### Dependency bag inventory
 
@@ -890,17 +890,17 @@ The fuller four-domain split — metrics as a projection, result delivery as its
 
 Updated health metrics (fallow, package-wide including tests):
 
-| Metric                     | Phase 16 baseline              | Current                                       |
-| -------------------------- | ------------------------------ | --------------------------------------------- |
-| Health score               | 78/100 (B)                     | 78/100 (B)                                    |
-| Source LOC                 | 7,778 (57 files)               | 8,356 (61 files, landed Phase 17 Step 5)      |
-| Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                            |
-| Maintainability index      | 90.8 (good)                    | 90.8 (good)                                   |
-| Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                       |
-| Production duplication     | 11 lines (1 internal group)    | 34 lines (1 internal + 1 cross-package group) |
-| Test duplication           | 42 groups, 661 lines           | 44 groups, ~750 lines                         |
-| Fallow refactoring targets | 0                              | 0                                             |
-| Top churn hotspot          | `index.ts` 65.0 ▲ accelerating | `index.ts` 31.3 ▼ cooling                     |
+| Metric                     | Phase 16 baseline              | Current                                                            |
+| -------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| Health score               | 78/100 (B)                     | 78/100 (B)                                                         |
+| Source LOC                 | 7,778 (57 files)               | 8,356 (61 files, landed Phase 17 Step 5)                           |
+| Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                                                 |
+| Maintainability index      | 90.8 (good)                    | 90.8 (good)                                                        |
+| Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                                            |
+| Production duplication     | 11 lines (1 internal group)    | 11 lines (1 internal group; cross-package pair resolved in Step 9) |
+| Test duplication           | 42 groups, 661 lines           | 44 groups, ~750 lines                                              |
+| Fallow refactoring targets | 0                              | 0                                                                  |
+| Top churn hotspot          | `index.ts` 65.0 ▲ accelerating | `index.ts` 31.3 ▼ cooling                                          |
 
 The syntactic metrics are healthy and stable — the remaining debt is structural, mostly invisible to fallow, and concentrated in three places:
 
@@ -1002,27 +1002,38 @@ Priority = Impact × (6 − Risk).
   Behavior-preserving: the widget timer runs through every background completion, so self-seeding lands ≤80ms later within the same turn (linger is turn-based).
   Test count: 1009 → 1005 (+3 widget self-seed tests, −7 removed relay/field tests).
 
-#### Step 7 — Consolidate lifecycle test fixtures ([#378])
+#### Step 7 — Consolidate lifecycle test fixtures ([#378]) ✅ Complete
 
-- Targets: `test/lifecycle/subagent-manager.test.ts` (766 LOC), `test/lifecycle/subagent.test.ts`, `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/lifecycle/create-subagent-session-extension-tools.test.ts`, `test/lifecycle/concurrency-limiter.test.ts`, `test/helpers/`.
-- Smell: Category D — fallow reports five clone families across the lifecycle tests.
+- Targets: `test/lifecycle/subagent-manager.test.ts`, `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/lifecycle/create-subagent-session-extension-tools.test.ts` (deleted), `test/helpers/subagent-session-io.ts`.
+- Smell: Category D — at planning time fallow reported four clone families across the lifecycle tests (the issue's "five" predated Steps 1–6, which renamed the queue and dissolved the `subagent.test.ts`/`concurrency-limiter.test.ts` families).
 - Change: extract the repeated spawn/run/factory arrangements into shared helpers, migrating incrementally (lift-and-shift, never a single-step rewrite of a large test file).
-- Outcome: lifecycle clone families 5 → ≤ 1; package test duplication below 600 lines.
+- Outcome: package test duplication below 600 lines; lifecycle clone families reduced, with the residual deliberately left as the visible test subject (see Landed).
+- Landed: added a shared `createFactorySession` mock-session builder (`test/helpers/subagent-session-io.ts`); grouped the `createSubagentSession` arrange into describe-scoped `beforeEach` hooks with the `createSubagentSession(...)` act kept explicit per test (AAA); extracted a `programTurns` arrange helper for the turn-limit tests; consolidated the manager spawn/queued-pair arrangements; and folded `create-subagent-session-extension-tools.test.ts` (4 post-bind guard tests) into `create-subagent-session.test.ts`, deleting the file and its duplicated scaffolding.
+  Package test duplication: 669 → 512 lines; test files 64 → 63; test count 1005 → 1010 (+5 `createFactorySession` self-tests).
+  Two lifecycle clone families remain (`create-subagent-session.test.ts` ~29 lines, `subagent-manager.test.ts` ~23 lines): both are the repeated `await createSubagentSession(...)` / `spawn(...)` **act** with test-specific arrange, intentionally not extracted because hiding the system-under-test behind a helper is the wrong abstraction for test code (Sandi Metz: "duplication is far cheaper than the wrong abstraction").
+  Lesson: the original "families ≤ 1" target was a weak signal for _test_ code — an early act-wrapping helper that hit the metric was reverted in favour of the AAA structure above; the metric was relaxed deliberately.
+  The three overlapping session-mock builders this surfaced are tracked separately ([#412]).
 
-#### Step 8 — Consolidate UI and tools test fixtures ([#379])
+#### Step 8 — Consolidate UI and tools test fixtures ([#379]) ✅ Complete
 
-- Targets: `test/ui/agent-creation-wizard.test.ts`, `test/ui/agent-config-editor.test.ts`, `test/ui/ui-observer.test.ts`, `test/tools/foreground-runner.test.ts`, `test/tools/background-spawner.test.ts`, `test/session/session-config.test.ts`.
+- Targets: `test/ui/agent-creation-wizard.test.ts`, `test/ui/agent-config-editor.test.ts`, `test/ui/ui-observer.test.ts`, `test/tools/foreground-runner.test.ts`, `test/tools/background-spawner.test.ts`, `test/session/session-config.test.ts`, and `test/service/service-adapter.test.ts` (a seventh non-lifecycle family fallow reports; added to scope in planning).
 - Smell: Category D — remaining clone families outside the lifecycle tree.
 - Change: extract per-file repeated arrangements into local helpers or `test/helpers/` where shared across files.
-- Outcome: package clone groups 44 → ≤ 25; overall duplication ≤ 0.6%.
+- Outcome: each named family's extractable arrange consolidated; resulting fallow figures reported (the roadmap's original "44 → ≤ 25 groups; ≤ 0.6%" target predated Steps 1–7 and used a different baseline, so acceptance was "consolidate and measure," not a binding number).
+- Landed: promoted the cross-file `ResolvedSpawnConfig` builder to `test/helpers/make-spawn-config.ts` (`createResolvedSpawnConfig`, flat options that derive the mirrored `agentInvocation`/`presentation.detailBase` regions) with a 5-test companion; consolidated the remaining six families with file-local, value-returning arrange builders and `beforeEach` setup (`spawnAndWaitRegistering`, `ui-observer` session/tracker `beforeEach` with `vi.fn()` onUpdate counters, `generateUI`/`manualUI`/`withInputs`, `disabledConfig`, `exploreConfig`, `createManagerStub`).
+  Package test duplication: 512 → 355 lines; clone groups 32 → 24; duplication 2.49% → 1.73%; test files 63 → 64; test count 1010 → 1015 (+5 `createResolvedSpawnConfig` self-tests).
+  Three multi-group families remain: the two lifecycle residuals from Step 7 (`create-subagent-session.test.ts`, `subagent-manager.test.ts`) and `agent-config-editor.test.ts`, whose residual clones are the repeated `await editor.showAgentDetail(...)` **act** plus its `setupDetail` arrange and `ui.select.mock.calls` menu assertion — left inline because wrapping the system-under-test is the wrong abstraction for test code (Step 7 lesson; Sandi Metz: "duplication is far cheaper than the wrong abstraction").
 
-#### Step 9 — Resolve the cross-package settings-loader duplication ([#380])
+#### Step 9 — Resolve the cross-package settings-loader duplication ([#380]) ✅
 
 - Targets: `src/settings.ts:198-211`, `packages/pi-subagents-worktrees/src/config.ts:51-73`.
 - Smell: Category A — 23-line production clone: the layered global/project JSON read-sanitize-warn-merge loader.
-- Change: decide explicitly between (a) exporting a small `loadLayeredSettings` helper from pi-subagents' public surface for worktrees to consume, and (b) documenting the duplication as intentional (separate release cadences, registry-resolved dependency) with a recorded fallow suppression.
-  The issue weighs the public-API cost (type bundle, `verify:public-types`, docs for third-party authors) against living with the flag.
-- Outcome: `pnpm fallow:dupes` no longer reports the pair, via extraction or recorded suppression.
+- Decision: **extract** — `loadLayeredSettings<T>` added to `src/layered-settings.ts` and published via the `@gotgenes/pi-subagents/settings` dedicated subpath export (`dist/settings.d.ts`); `loadSettings` in `settings.ts` delegates to it internally.
+  Option 2 (fallow suppression) was rejected; the public-API cost is accepted as the right long-term tradeoff for a shared convention in the `@gotgenes/pi-*` family.
+  Worktrees migration (swap `config.ts`'s inlined loader for the shared helper) is deferred to [#415] — worktrees resolves pi-subagents from the registry, so it must wait for a published release carrying the helper.
+- Outcome: `pnpm fallow:dupes --skip-local` no longer reports the `settings.ts` ↔ `config.ts` pair.
+  The parametrised helper's token sequence diverged sufficiently that the contiguous identical run dropped below the reporting threshold even before the worktrees migration lands.
+  Definitive semantic elimination completes when worktrees adopts the helper in the follow-up.
 
 ### Step dependencies
 
@@ -1159,4 +1170,6 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#379]: https://github.com/gotgenes/pi-packages/issues/379
 [#380]: https://github.com/gotgenes/pi-packages/issues/380
 [#381]: https://github.com/gotgenes/pi-packages/issues/381
+[#412]: https://github.com/gotgenes/pi-packages/issues/412
+[#415]: https://github.com/gotgenes/pi-packages/issues/415
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/plans/0378-consolidate-lifecycle-test-fixtures.md

@@ -0,0 +1,243 @@
+---
+issue: 378
+issue_title: "Consolidate lifecycle test fixtures"
+---
+
+# Consolidate lifecycle test fixtures
+
+## Problem Statement
+
+`pnpm fallow:dupes` reports clone families concentrated in `test/lifecycle/`: repeated spawn-and-await arrangements and session-factory stubs copy-pasted across files and within them.
+This is Phase 17 Step 7 (core consolidation), sequenced after Steps 2–6 reshaped `Subagent` construction so the lifecycle tests had already churned.
+The roadmap Outcome is: lifecycle clone families 5 → ≤ 1; package test duplication below 600 lines.
+
+The issue body cites five families across six files (including `concurrency-queue.test.ts` and `subagent.test.ts` at 766 LOC).
+That snapshot predates Steps 1–6.
+The current state — measured with `fallow dupes -r packages/pi-subagents` against today's `main` — is **four** lifecycle clone families, because the queue was renamed to `concurrency-limiter.test.ts` ([#381]) and `subagent.test.ts`/`concurrency-limiter.test.ts` no longer report families after the Step 2–4 reshaping.
+
+## Goals
+
+- Consolidate the four current lifecycle clone families into shared or file-local helpers so the lifecycle tree reports ≤ 1 family.
+- Bring package-wide test duplication below 600 lines (current baseline: 669 lines / 3.3% across 20 files; the four lifecycle families total ~122 lines).
+- Preserve every existing test assertion — the existing suite is the regression guard for this refactor.
+- Keep the change non-breaking: test-only, no production-code, public-surface, or behavior change.
+
+## Non-Goals
+
+- Step 8 ([#379]) — UI and tools clone families (`agent-config-editor`, `agent-creation-wizard`, `ui-observer`, `foreground-runner`, `service-adapter`).
+  These are separate families outside the lifecycle tree and are deferred to their own issue.
+- Step 9 ([#380]) — the cross-package settings-loader production clone.
+- Any production-code change in `src/`.
+- Adding new behavioral test cases — this is duplication removal, not coverage expansion (helper self-tests are the only new `it` blocks).
+
+## Background
+
+The lifecycle suite already has substantial shared scaffolding under `test/helpers/`:
+
+- `subagent-session-io.ts` — `createSubagentSessionIO()`, `createAgentLookup()`, `createSubagentSessionDeps()`, `createChildLifecycleMock()`.
+  The natural home for shared `createSubagentSession`-test scaffolding.
+- `manager-stubs.ts` — `createBlockingFactory()`, `createSessionFactory()`.
+- `mock-session.ts` — `createMockSession()`, `createSubagentSessionStub()`, `toSubagentSession()`, `toAgentSession()`.
+- `make-subagent.ts` — `createTestSubagent()`, `makeStubExecution()`.
+
+Convention: every shared helper module under `test/helpers/` has a companion `*.test.ts` (e.g. `subagent-session-io.test.ts`, `make-subagent.test.ts`).
+New or extended shared helpers must extend that companion test.
+
+The four current lifecycle clone families and the repeated blocks driving them:
+
+| File                                              | Family             | Repeated block                                                                                                                                                                                                                       |
+| ------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `create-subagent-session.test.ts`                 | 3 groups, 31 lines | A file-local `createSession()` mock-session builder, then `io.createSession.mockResolvedValue({ session })` + `await createSubagentSession({ snapshot, type }, createSubagentSessionDeps({ io, exec, registry[, lifecycle] }))`      |
+| `create-subagent-session-extension-tools.test.ts` | 3 groups, 29 lines | A near-identical file-local `createSessionWithExtensionToolRegistration()` builder, then the same `io.createSession.mockResolvedValue` + `createSubagentSession(...)` invoke block, plus post-bind `setActiveToolsByName` assertions |
+| `subagent-manager.test.ts`                        | 4 groups, 40 lines | `spawn(STUB_SNAPSHOT, "general-purpose", "test", { description, isBackground: true, parentSession: { toolCallId } })` and the "spawn two bg agents under limit 1, assert one queued" arrange                                         |
+| `subagent-session.test.ts`                        | 3 groups, 22 lines | Repeated arrange blocks around the already-local `createSession(finalText)` / `makeSubagentSession()` / `emitTurnEnd()` helpers                                                                                                      |
+
+The two `createSubagentSession`-test session builders (`createSession` and `createSessionWithExtensionToolRegistration`) build near-identical mock sessions — the same eight `vi.fn()` methods — differing only in that the extension-tools variant flips `getActiveToolNames` between a before-bind and after-bind set.
+That overlap is the one genuinely cross-file duplication and the strongest candidate for promotion to `test/helpers/`.
+The manager and `subagent-session` families are intra-file.
+
+AGENTS.md / testing-skill constraints that apply:
+
+- When consolidating duplicate test factories, diff the default values across all copies before writing the shared factory — different defaults cause cascading assertion failures during migration.
+- When a TDD step deletes a test helper, re-check the file's remaining imports for orphans — Biome's `noUnusedImports` is warning-level (exit 0), so it will not fail `pnpm run lint`.
+- Run the full suite (not just the touched file) after each shared-helper change.
+
+## Design Overview
+
+The guiding distinction: **promote to `test/helpers/` only what is genuinely shared across files; keep intra-file families as file-local helpers.**
+Fallow's own recommendation for three of the four families is "extract shared function from `<file>`, `<file>`" (same file on both sides) — promoting those to `test/helpers/` would manufacture cross-file coupling that does not exist.
+
+### 1. Shared: a mock-session builder for `createSubagentSession` tests
+
+Add `createFactorySession(overrides?)` to `test/helpers/subagent-session-io.ts`.
+It returns the eight-method mock session both `createSubagentSession` test files build by hand today, with `getActiveToolNames` supporting a static set or a before/after-bind flip:
+
+```typescript
+export interface FactorySessionOptions {
+  /** Tools active before bindExtensions(). Default ["read"]. */
+  toolsBeforeBind?: string[];
+  /** Tools active after bindExtensions(). Defaults to toolsBeforeBind (no extension registration). */
+  toolsAfterBind?: string[];
+}
+
+export function createFactorySession(options: FactorySessionOptions = {}) {
+  const before = options.toolsBeforeBind ?? ["read"];
+  const after = options.toolsAfterBind ?? before;
+  let bound = false;
+  return {
+    messages: [] as unknown[],
+    subscribe: vi.fn(() => () => {}),
+    prompt: vi.fn().mockResolvedValue(undefined),
+    abort: vi.fn(),
+    steer: vi.fn().mockResolvedValue(undefined),
+    dispose: vi.fn(),
+    getActiveToolNames: vi.fn(() => (bound ? after : before)),
+    setActiveToolsByName: vi.fn(),
+    bindExtensions: vi.fn(async () => { bound = true; }),
+  };
+}
+```
+
+Return type is deliberately unannotated so callers retain the `Mock<...>` methods (`mock.calls`, `mockResolvedValue`) — matching the existing `createSubagentSessionIO()` convention in this file.
+
+`create-subagent-session.test.ts` replaces `createSession()` with `createFactorySession()`; the existing static `getActiveToolNames: () => ["read"]` becomes the default branch (`bound === after === before === ["read"]`), so the lone `bindExtensions` flip is inert there — behavior-preserving.
+`create-subagent-session-extension-tools.test.ts` replaces `createSessionWithExtensionToolRegistration(before, after)` with `createFactorySession({ toolsBeforeBind: before, toolsAfterBind: after })`.
+
+Consumer call site (verifies Tell-Don't-Ask: the helper returns a ready mock; the test arranges and asserts on it):
+
+```typescript
+const session = createFactorySession({ toolsBeforeBind: ["read"], toolsAfterBind: ["read", "extension_tool"] });
+io.createSession.mockResolvedValue({ session });
+await createSubagentSession({ snapshot: STUB_SNAPSHOT, type: "test-agent" }, createSubagentSessionDeps({ io, exec, registry }));
+expect(session.setActiveToolsByName.mock.calls[0][0]).toContain("extension_tool");
+```
+
+The repeated `io.createSession.mockResolvedValue({ session })` + `createSubagentSession(...)` invoke pair is left in the tests rather than wrapped in an `invokeCreate()` helper: it is two lines, the `params` and `deps` overrides vary per test, and wrapping it would hide the system-under-test call behind a helper (procedure-splitting, not design improvement).
+Extracting only the session builder removes the bulk of both families because the builder is the larger half of each clone.
+
+### 2. File-local: manager spawn / queued-pair arrangements
+
+`subagent-manager.test.ts` already has file-local `spawnBg`/`spawnFg`/`createManager`/`defaultFactory`.
+The remaining 40 lines are two intra-file patterns; add two file-local helpers:
+
+```typescript
+/** Spawn a background agent carrying a parentSession.toolCallId (notification path). */
+function spawnBgWithToolCall(mgr: SubagentManager, toolCallId: string, prompt = "test") {
+  return mgr.spawn(STUB_SNAPSHOT, "general-purpose", prompt, {
+    description: prompt,
+    isBackground: true,
+    parentSession: { toolCallId },
+  });
+}
+
+/** Arrange a manager at limit 1 with two bg agents: first runs, second queues. */
+function arrangeQueuedPair() {
+  const { manager } = createManager({ createSubagentSession: createBlockingFactory(), getMaxConcurrent: () => 1 });
+  const running = spawnBg(manager, "a");
+  const queued = spawnBg(manager, "b");
+  return { manager, running, queued };
+}
+```
+
+These stay file-local: they reference manager-specific concerns and fallow scores the family as same-file.
+
+### 3. File-local: `subagent-session.test.ts` arrange blocks
+
+The three small groups (22 lines) sit around the existing file-local `createSession(finalText)`, `makeSubagentSession()`, and `emitTurnEnd()` helpers.
+Fold the repeated "build session, build SubagentSession, run/emit" arrange into one file-local helper (e.g. `arrangeSession(finalText, metaOverrides?)` returning `{ session, listeners, sub }`), keeping the per-test assertions inline.
+No promotion to `test/helpers/` — this builder is specific to `subagent-session.test.ts`'s turn-loop assertions and is not used elsewhere.
+
+## Module-Level Changes
+
+- `test/helpers/subagent-session-io.ts` — add `createFactorySession()` and `FactorySessionOptions`.
+- `test/helpers/subagent-session-io.test.ts` — add a `describe("createFactorySession")` block: default tool set, before/after-bind flip, all eight methods present.
+- `test/lifecycle/create-subagent-session.test.ts` — delete local `createSession()`; import and use `createFactorySession()`; re-check imports for orphans.
+- `test/lifecycle/create-subagent-session-extension-tools.test.ts` — delete local `createSessionWithExtensionToolRegistration()`; use `createFactorySession({ toolsBeforeBind, toolsAfterBind })`; re-check imports.
+- `test/lifecycle/subagent-manager.test.ts` — add file-local `spawnBgWithToolCall()` and `arrangeQueuedPair()`; route the cloned spawn/queued-pair sites through them.
+- `test/lifecycle/subagent-session.test.ts` — add a file-local `arrangeSession()` helper; route the cloned arrange blocks through it.
+- `docs/architecture/architecture.md` — mark Step 7 ✅ Complete and add a `Landed:` bullet (matching Steps 1–6), updating the families and duplication figures.
+
+No `src/` files change.
+No public surface changes, so `verify:public-types` is unaffected.
+The `package-pi-subagents` SKILL.md's test count line ("994 tests across 63 files as of Phase 17 Step 4") is a point-in-time figure, not a Step-7 reference, and is left untouched.
+
+## Test Impact Analysis
+
+This is a test-refactoring issue, so the lens is inverted from a production extraction:
+
+1. **New tests the change enables.**
+   Only helper self-tests: a `createFactorySession` block in `subagent-session-io.test.ts` (per the `test/helpers/` companion-test convention).
+   No new behavioral tests — the refactor must not change coverage.
+2. **Existing tests that become redundant.**
+   None are removed.
+   The duplication being removed is *arrange-block* duplication inside `it()` bodies, not duplicate `it()` cases.
+   Every existing assertion stays.
+3. **Tests that must stay as-is.**
+   All 228 lifecycle test cases keep their assertions; they are the regression guard.
+   Migration is green-to-green: after each file's migration the full suite must stay passing.
+   In particular, the post-bind `setActiveToolsByName` assertions in the extension-tools file and the turn-limit/`emitTurnEnd` assertions in `subagent-session.test.ts` are unchanged — only their session-construction arrange is swapped.
+
+## Invariants at risk
+
+This step touches `subagent-manager.test.ts`, which pins invariants from earlier Phase 17 steps.
+The `arrangeQueuedPair()` helper must not swallow these:
+
+- **Step 1 ([#381]) / Step 3 ([#374]) — "every spawned agent has a `promise` at spawn, even while queued."**
+  Pinned by `subagent-manager.test.ts` → `it("gives a queued agent an awaitable promise at spawn (before its slot opens)")`, which asserts `getRecord(queuedId)!.promise` is a `Promise` while status is `"queued"`.
+  When this test adopts `arrangeQueuedPair()`, the helper must still return the queued id so the test can assert on `.promise` directly.
+- **Step 3 ([#374]) — "zero external writes to `Subagent.promise`/`.notification` outside `subagent.ts`" (grep-verifiable).**
+  The helper migration must not reintroduce `record.promise =` or `record.notification =`.
+  The existing `record.notification!.markConsumed()` sites are method calls, not writes, and stay as-is.
+  Re-grep `test/lifecycle/` for `\.promise =` and `\.notification =` after the manager migration to confirm none were added.
+
+## TDD Order
+
+This is a lift-and-shift refactor of tests; the suite is green at every step (no red phase — the existing assertions are the spec).
+Each migration step runs the full package suite before committing.
+
+1. **Add shared `createFactorySession` + helper test.**
+   Surface: `test/helpers/subagent-session-io.ts`, `test/helpers/subagent-session-io.test.ts`.
+   Covers: default tool set, before/after-bind flip, method presence.
+   Run `pnpm --filter @gotgenes/pi-subagents exec vitest run test/helpers/subagent-session-io.test.ts` then `pnpm run check`.
+   Commit: `test: add shared createFactorySession mock-session builder (#378)`.
+2. **Migrate `create-subagent-session.test.ts` to `createFactorySession`.**
+   Delete local `createSession()`, re-check imports, run full suite green.
+   Commit: `test: use shared factory session in create-subagent-session tests (#378)`.
+3. **Migrate `create-subagent-session-extension-tools.test.ts` to `createFactorySession({ toolsBeforeBind, toolsAfterBind })`.**
+   Delete local `createSessionWithExtensionToolRegistration()`, re-check imports, run full suite green.
+   Commit: `test: use shared factory session in extension-tools tests (#378)`.
+4. **Consolidate `subagent-manager.test.ts` spawn/queued-pair arrangements.**
+   Add `spawnBgWithToolCall()` and `arrangeQueuedPair()`; route the cloned sites through them; re-grep for `.promise =`/`.notification =`; run full suite green.
+   Commit: `test: consolidate manager spawn arrangements (#378)`.
+5. **Consolidate `subagent-session.test.ts` arrange blocks.**
+   Add `arrangeSession()`; route cloned sites; run full suite green.
+   Commit: `test: consolidate subagent-session arrange blocks (#378)`.
+6. **Verify and record outcome.**
+   Run `pnpm exec fallow dupes -r packages/pi-subagents` and confirm lifecycle families ≤ 1 and package duplication < 600 lines; run `pnpm run check && pnpm run lint && pnpm fallow dead-code`.
+   Update `docs/architecture/architecture.md` Step 7 to ✅ Complete with a `Landed:` bullet and refreshed figures.
+   Commit: `docs: mark Phase 17 Step 7 complete (#378)`.
+
+Steps 2–5 are independent of each other and order-insensitive; each only depends on Step 1's helper.
+
+## Risks and Mitigations
+
+- **Divergent defaults between the two session builders cause assertion failures.**
+  Mitigation: the two builders are diffed in Background — they share eight identical methods and differ only in `getActiveToolNames`.
+  `createFactorySession` defaults `toolsAfterBind` to `toolsBeforeBind` so the non-extension file's static behavior is preserved exactly.
+- **Over-extraction / procedure-splitting to chase the metric.**
+  Mitigation: the invoke pair (`mockResolvedValue` + `createSubagentSession(...)`) and the per-test assertions are left inline; only value-returning builders are extracted.
+  File-local families stay file-local rather than being force-promoted to `test/helpers/`.
+- **Orphaned imports after deleting local builders (Biome `noUnusedImports` is warning-level, exit 0).**
+  Mitigation: re-check each migrated file's imports as part of its step; the Step 6 `pnpm run lint` + dead-code pass is the backstop.
+- **Regressing a cross-step invariant with a green suite (the Step 3 lesson).**
+  Mitigation: the "Invariants at risk" section names the pinning tests and the grep checks folded into Step 4.
+
+## Open Questions
+
+- Whether package-wide duplication lands below 600 lines from Step 7 alone or needs Step 8 ([#379]).
+  Arithmetic says yes (669 − ~122 ≈ 547), but the Step 6 `fallow dupes` measurement is the authority; if it lands above 600, note it and confirm the lifecycle-families target (≤ 1) is still met rather than pulling Step 8 work forward.
+
+[#374]: https://github.com/gotgenes/pi-packages/issues/374
+[#379]: https://github.com/gotgenes/pi-packages/issues/379
+[#380]: https://github.com/gotgenes/pi-packages/issues/380
+[#381]: https://github.com/gotgenes/pi-packages/issues/381