@gotgenes/pi-subagents 16.3.1 → 16.5.0

package/docs/plans/0379-consolidate-ui-tools-test-fixtures.md

@@ -0,0 +1,335 @@
+---
+issue: 379
+issue_title: "Consolidate UI and tools test fixtures"
+---
+
+# Consolidate UI and tools test fixtures
+
+## Problem Statement
+
+`pnpm fallow:dupes` reports clone families in the UI, tools, session, and service test suites that sit outside the lifecycle tree consolidated in Step 7 ([#378]).
+These are independent of the `Subagent` refactoring and can be tidied at any time.
+This is Phase 17 Step 8 (core consolidation) — the last non-lifecycle test-duplication cleanup before Step 9's cross-package production clone.
+
+Measured against today's `main` (`fallow dupes -r packages/pi-subagents`), the package reports **32 clone groups / 512 duplicated lines (2.49%)**, with seven clone families.
+Two of those families (`create-subagent-session.test.ts`, `subagent-manager.test.ts`) are the residual that Step 7 deliberately left as the visible system-under-test **act** — Non-Goals here.
+The remaining five families are the UI/tools/session targets named in the issue, plus a sixth in `test/service/service-adapter.test.ts` (a repeated `SubagentManagerLike` stub) added to scope by operator decision during planning.
+
+## Goals
+
+- Consolidate the seven targeted test files' clone families by extracting **value-returning arrange builders** (or describe-scoped `beforeEach` setup), never by wrapping the system-under-test act.
+- Promote genuinely cross-file duplication (the `ResolvedSpawnConfig` builder shared by the two tools tests) into `test/helpers/`; keep intra-file families as file-local helpers.
+- 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.
+- Report the resulting `fallow dupes` group count and duplication percentage as the outcome (no binding numeric group target — see Open Questions).
+
+## Non-Goals
+
+- The two residual lifecycle families (`create-subagent-session.test.ts`, `subagent-manager.test.ts`).
+  Step 7 ([#378]) intentionally left these as the repeated `await createSubagentSession(...)` / `spawn(...)` act with test-specific arrange; re-extracting them would hide the test subject behind a helper (the wrong abstraction Step 7's `Landed` note calls out).
+- The 11-line **production** clone inside `src/ui/agent-config-editor.ts` (lines 125–135 / 163–173, the location-select-and-write block).
+  This issue is test-only; the production clone is tracked separately in the architecture doc's "Production duplication" section.
+- The cross-package settings-loader production clone — Step 9 ([#380]).
+- The three overlapping session-mock builders ([#412]).
+- Adding new behavioral test cases — this is duplication removal, not coverage expansion (helper self-tests are the only new `it` blocks).
+
+## Background
+
+The package already has substantial shared scaffolding under `test/helpers/`:
+
+- `make-deps.ts` — `createToolDeps(overrides)` returns `{ manager, runtime, widget }` for the tools tests.
+- `ui-stubs.ts` — `makeFileOps()`, `makeMenuUI(selectResults)`, `makeMenuManager()`, `createTestSubagentConfig(overrides)`.
+- `make-subagent.ts` — `createTestSubagent(overrides)`.
+- `mock-session.ts` — `createMockSession()`, `createSubagentSessionStub()`, `toSubagentSession()`.
+- `manager-stubs.ts` — `createBlockingFactory()`, `createSessionFactory()` (session factories, **not** the `SubagentManagerLike` service stub).
+- `stub-ctx.ts` — `STUB_SNAPSHOT`.
+
+Convention: every shared helper module under `test/helpers/` has a companion `*.test.ts` (e.g. `subagent-session-io.test.ts`).
+A new shared helper must ship its own companion test.
+
+The seven clone families fallow reports today, and the repeated blocks driving each:
+
+| File                                    | Family             | Repeated block                                                                                                                                               | Disposition                                                       |
+| --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| `test/ui/agent-creation-wizard.test.ts` | 3 groups, 33 lines | `makeMenuUI([...selections])` + `ui.input = vi.fn()...` arrange, then `makeWizard(deps)` + `showCreateWizard(...)` act                                       | file-local arrange builders                                       |
+| `test/ui/agent-config-editor.test.ts`   | 4 groups, 29 lines | disabled-config spy arrange + `setupDetail(...)`, then `showAgentDetail(...)` act and `ui.select.mock.calls[0][1]` menu assertions                           | file-local `disabledConfig` builder; `setupDetail` already exists |
+| `test/ui/ui-observer.test.ts`           | 3 groups, 20 lines | `const session = createMockSession(); const tracker = new AgentActivityTracker();` setup, then `subscribeUIObserver(...)` + `session.emit(...)` act          | describe-scoped `beforeEach`                                      |
+| `test/tools/foreground-runner.test.ts`  | 2 groups, 21 lines | a local `makeConfig`/`makeParams` builder (cross-file with background-spawner) + a `spawnAndWait.mockImplementation` observer-registering block (intra-file) | shared `createResolvedSpawnConfig`; file-local observer helper    |
+| `test/tools/background-spawner.test.ts` | (cross-file group) | a near-identical local `makeConfig`/`makeParams` builder                                                                                                     | shared `createResolvedSpawnConfig`                                |
+| `test/session/session-config.test.ts`   | 1 group, 16 lines  | `mockResolveAgentConfig.mockReturnValueOnce({ name: "Explore", ..., model })` arrange, then the 6-arg `assembleSessionConfig(...)` act                       | file-local `exploreConfig` builder                                |
+| `test/service/service-adapter.test.ts`  | 2 groups, 13 lines | four near-identical 7-method `SubagentManagerLike` stub factories (`createMockManager`, `defaultManager`, `createTestManager`, an inline literal)            | file-local `createManagerStub` builder                            |
+
+The cross-file group `dup:80ee2004` (background-spawner `5-16` ↔ foreground-runner `4-15`) is the `ResolvedSpawnConfig` skeleton head — the only genuine **cross-file** duplication and the sole promotion candidate.
+Every other family fallow scores as "same file on both sides," so they stay file-local.
+
+AGENTS.md / testing-skill / Step 7 constraints that apply:
+
+- Do not wrap the system-under-test act in a helper to eliminate a duplication-metric clone — the repeated act is the test subject (testing skill; Step 7 `Landed` note; the act-wrapping helper was reverted in Step 7).
+- 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).
+- Run the full package suite (not just the touched file) after each shared-helper change.
+- `Partial<T>` top-level spread does not deep-merge nested sub-objects — relevant to the `ResolvedSpawnConfig` builder (nested `identity`/`execution`/`presentation`).
+
+## Design Overview
+
+Guiding distinction, inherited from Step 7: **promote to `test/helpers/` only what is genuinely shared across files; keep intra-file families as file-local helpers or describe-scoped `beforeEach`; never extract the act.**
+
+### 1. Shared: a `ResolvedSpawnConfig` builder for the tools tests
+
+`foreground-runner.test.ts` and `background-spawner.test.ts` each hand-build a full `ResolvedSpawnConfig` with a local `makeConfig(overrides)` — the cross-file clone.
+The two copies share the nested shape and differ only in a handful of scalars:
+
+| Field                       | foreground      | background          |
+| --------------------------- | --------------- | ------------------- |
+| `identity.displayName`      | `"Agent"`       | `"General-purpose"` |
+| `execution.prompt`          | `"do the task"` | `"do something"`    |
+| `execution.description`     | `"fg task"`     | `"bg task"`         |
+| `execution.runInBackground` | `false`         | `true`              |
+
+Crucially, three regions of the config mirror the same scalars — `execution.runInBackground` mirrors into `execution.agentInvocation.runInBackground`; `identity.displayName`/`execution.description`/`identity.subagentType` mirror into `presentation.detailBase`.
+The hand-built copies duplicate that mirroring.
+Add a flat-options builder to a new `test/helpers/make-spawn-config.ts` that **derives** the mirrored regions, so the construction knowledge lives in one tested place:
+
+```typescript
+import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
+
+export interface ResolvedSpawnConfigOptions {
+  subagentType?: string;
+  rawType?: string;
+  fellBack?: boolean;
+  displayName?: string;
+  prompt?: string;
+  description?: string;
+  model?: string;
+  runInBackground?: boolean;
+}
+
+export function createResolvedSpawnConfig(
+  options: ResolvedSpawnConfigOptions = {},
+): ResolvedSpawnConfig {
+  const subagentType = options.subagentType ?? "general-purpose";
+  const displayName = options.displayName ?? "Agent";
+  const description = options.description ?? "task";
+  const runInBackground = options.runInBackground ?? false;
+  const agentInvocation = {
+    modelName: options.model,
+    thinking: undefined,
+    maxTurns: undefined,
+    inheritContext: false,
+    runInBackground,
+  };
+  return {
+    identity: {
+      subagentType,
+      rawType: options.rawType ?? subagentType,
+      fellBack: options.fellBack ?? false,
+      displayName,
+    },
+    execution: {
+      prompt: options.prompt ?? "do the task",
+      description,
+      model: undefined,
+      effectiveMaxTurns: undefined,
+      thinking: undefined,
+      inheritContext: false,
+      runInBackground,
+      agentInvocation,
+    },
+    presentation: {
+      modelName: options.model,
+      agentTags: [],
+      detailBase: { displayName, description, subagentType, modelName: options.model, tags: undefined },
+    },
+  };
+}
+```
+
+Flat options (rather than `Partial<ResolvedSpawnConfig>` nested overrides) sidestep the deep-merge trap and cover every override the two files use today: the foreground "fallback note" test (`fellBack: true`, `rawType: "unknown-type"`) and the background "my task" / queued tests (`description`, `runInBackground`).
+Return type **is** annotated `ResolvedSpawnConfig` here because the builder returns a plain data object (no `Mock<...>` methods to preserve), unlike the mock-session factories.
+
+Consumer call site (the act stays inline and explicit):
+
+```typescript
+const result = await runForeground(
+  manager, widget, runtime.agentActivity,
+  { config: createResolvedSpawnConfig({ fellBack: true, rawType: "unknown-type" }), snapshot: STUB_SNAPSHOT, parentSession },
+  undefined, undefined,
+);
+expect(result.content[0].text).toContain('Unknown agent type "unknown-type"');
+```
+
+`makeParams(overrides)` stays file-local in each tools test (the `parentSession`/`settings` shapes differ between `ForegroundParams` and `BackgroundParams`); only its inner `config:` default switches to `createResolvedSpawnConfig(...)`.
+
+### 2. File-local: tools observer-registering arrange
+
+`foreground-runner.test.ts` repeats a `spawnAndWait.mockImplementation(async (...) => { ...register observer.onSessionCreated... })` block twice (`dup:fbdc0856`).
+Extract a file-local helper that **returns** the mock implementation (a value), keeping the `createToolDeps(...)` wiring and the `runForeground(...)` act inline:
+
+```typescript
+function spawnAndWaitRegistering(record = createTestSubagent({ result: "done" })) {
+  record.subagentSession = toSubagentSession(createSubagentSessionStub(createMockSession()));
+  return vi.fn(async (_s, _t, _p, opts: { observer?: { onSessionCreated?: (r: Subagent) => void } }) => {
+    opts.observer?.onSessionCreated?.(record);
+    return record;
+  });
+}
+```
+
+### 3. File-local: `ui-observer.test.ts` describe-scoped `beforeEach`
+
+Every test opens with `const session = createMockSession(); const tracker = new AgentActivityTracker();`.
+Move both into a describe-scoped `beforeEach` (the Step 7 AAA pattern); keep `subscribeUIObserver(session, tracker[, onUpdate])` and `session.emit(...)` inline as the act.
+For the update-counting tests, replace the closure `let updateCount = 0; () => updateCount++` with a `vi.fn()` onUpdate and assert `toHaveBeenCalledTimes(n)` — removing the repeated counter scaffolding without hiding the act.
+
+### 4. File-local: `agent-creation-wizard.test.ts` arrange builders
+
+The repeated arrange is the menu-selection arrays and the `ui.input = vi.fn().mockResolvedValueOnce(...)` chains; the act is `makeWizard(deps)` + `showCreateWizard(ui, STUB_SNAPSHOT)`.
+Extract value-returning builders for the arrange only:
+
+```typescript
+function manualUI(opts: { location?: string; tools?: string; model?: string; thinking?: string }) {
+  return makeMenuUI([opts.location ?? "Project (.pi/agents/)", "Manual configuration",
+    opts.tools ?? "all", opts.model ?? "inherit (parent model)", opts.thinking ?? "inherit"]);
+}
+function withInputs(ui: ReturnType<typeof makeMenuUI>, ...values: (string | undefined)[]) {
+  ui.input = vi.fn();
+  for (const v of values) (ui.input as Mock).mockResolvedValueOnce(v);
+  return ui;
+}
+```
+
+`makeWizard(deps)` + `await wizard.showCreateWizard(...)` stay inline in every test.
+
+### 5. File-local: `agent-config-editor.test.ts` disabled-config builder
+
+This file is already well-factored (`setupDetail`, `makeEditor`).
+The residual families are the `vi.spyOn(testRegistry, "resolveAgentConfig").mockReturnValue({ ...testXConfig, enabled: false })` arrange (5 sites) and the repeated `showAgentDetail(...)` act with `const options = ui.select.mock.calls[0][1] as string[]` menu assertions.
+Extract a single value-returning `disabledConfig(base)` helper (`(base: AgentConfig) => ({ ...base, enabled: false })`) for the disabled-config arrange.
+Leave the `showAgentDetail(...)` act and the menu-option assertions inline — they are the test subject (see Test Impact Analysis for the menu-structure redundancy note).
+
+### 6. File-local: `session-config.test.ts` config builder
+
+Extract a value-returning `exploreConfig(model?)` helper returning the `{ name: "Explore", description, systemPrompt, promptMode: "replace", model }` literal that `mockResolveAgentConfig.mockReturnValueOnce(...)` consumes across the model-resolution tests.
+The 6-arg `assembleSessionConfig("Explore", ctx, {}, mockEnv, mockAgentLookup, mockIO)` act stays inline.
+
+### 7. File-local: `service-adapter.test.ts` manager-stub builder
+
+Four near-identical 7-method `SubagentManagerLike` stubs (`createMockManager`, `defaultManager`, `createTestManager`, and an inline literal) drive both families.
+Diffed defaults: `hasRunning` is `true` in `createTestManager` and `false` elsewhere; `spawn` returns `"spawned-id"` / `"id"` / `"spawned-id"` variously; `getRecord`/`listAgents`/`abort` are typed in `createTestManager`.
+Consolidate into one file-local builder with documented defaults and typed overrides:
+
+```typescript
+function createManagerStub(overrides: Partial<SubagentManagerLike> = {}): SubagentManagerLike {
+  return {
+    spawn: vi.fn(() => "spawned-id"),
+    getRecord: vi.fn(),
+    listAgents: vi.fn(() => []),
+    abort: vi.fn(() => true),
+    waitForAll: vi.fn(async () => {}),
+    hasRunning: vi.fn(() => false),
+    registerWorkspaceProvider: vi.fn(() => () => {}),
+    ...overrides,
+  };
+}
+```
+
+Call sites pass the differing fields via `overrides` (`{ hasRunning: vi.fn(() => true) }`, `{ getRecord: vi.fn((id) => records.find(...)) }`, etc.).
+This is file-local — `SubagentManagerLike` is service-adapter-specific and fallow scores the family same-file.
+
+## Module-Level Changes
+
+- `test/helpers/make-spawn-config.ts` — **new**: `createResolvedSpawnConfig(options)` + `ResolvedSpawnConfigOptions`.
+- `test/helpers/make-spawn-config.test.ts` — **new** companion test: default shape, the four scalar overrides, and the derived-mirroring assertions (`agentInvocation.runInBackground`, `presentation.detailBase`).
+- `test/tools/foreground-runner.test.ts` — delete local `makeConfig`; `makeParams` inner `config:` uses `createResolvedSpawnConfig(...)`; add file-local `spawnAndWaitRegistering()`; re-check imports for orphans.
+- `test/tools/background-spawner.test.ts` — delete local `makeConfig`; `makeParams` inner `config:` uses `createResolvedSpawnConfig({ displayName: "General-purpose", prompt: "do something", description: "bg task", runInBackground: true })`; re-check imports.
+- `test/ui/ui-observer.test.ts` — add describe-scoped `beforeEach` creating `session`/`tracker`; switch update-counting tests to `vi.fn()` onUpdate.
+- `test/ui/agent-creation-wizard.test.ts` — add file-local `manualUI()` / `withInputs()` arrange builders; route cloned arrange through them; keep act inline.
+- `test/ui/agent-config-editor.test.ts` — add file-local `disabledConfig(base)`; route the disabled-config spy arranges through it.
+- `test/session/session-config.test.ts` — add file-local `exploreConfig(model?)`; route the model-resolution arranges through it.
+- `test/service/service-adapter.test.ts` — add file-local `createManagerStub(overrides)`; replace the four stub factories/literal with it; re-check imports.
+- `docs/architecture/architecture.md` — mark Step 8 ✅ Complete with a `Landed:` bullet (matching Step 7); add `test/service/service-adapter.test.ts` to the Step 8 `Targets` line with a note that it was added in planning; refresh the "Test duplication" current-state figure.
+
+No `src/` files change.
+No public surface changes, so `verify:public-types` and the type bundle are unaffected.
+The `package-pi-subagents` SKILL.md test-count line ("994 tests across 63 files as of Phase 17 Step 4") is an explicitly point-in-time figure, not a Step-8 reference, and is left untouched.
+
+## Test Impact Analysis
+
+Inverted lens, per the test-refactoring nature of this issue:
+
+1. **New tests the change enables.**
+   Only one helper self-test file: `make-spawn-config.test.ts` (per the `test/helpers/` companion-test convention).
+   No new behavioral tests — coverage must not change.
+2. **Existing tests that become redundant.**
+   The five menu-structure tests in `agent-config-editor.test.ts`'s `showAgentDetail` describe assert the same expected arrays as the five `buildMenuOptions` unit tests below them.
+   They are **not** removed: the `showAgentDetail` variants verify the `resolveType` → `resolveAgentConfig` → `buildMenuOptions` wiring (an integration concern), whereas `buildMenuOptions` tests the pure function in isolation.
+   Removing either layer is a coverage decision outside this issue's scope; flagged here, deferred.
+3. **Tests that must stay as-is.**
+   Every assertion in all seven files is the regression guard; migration is green-to-green.
+   In particular the foreground spinner/timer assertions, the `spawnBackground` queued/output-file assertions, the `ui-observer` turn-count/unsubscribe assertions, and the `service-adapter` serialization-stripping assertions are unchanged — only their arrange scaffolding is consolidated.
+
+## Invariants at risk
+
+This step touches no production code and no surface a prior Phase 17 step refactored for behavior; the lifecycle invariants from Steps 1–6 (`.promise`/`.notification` encapsulation) live in `test/lifecycle/`, which this step does not touch.
+The one cross-step continuity risk is **regressing Step 7's documented discipline** — "do not wrap the system-under-test act."
+Mitigation: every builder extracted here returns a value or seeds `beforeEach` setup; the acts (`showCreateWizard`, `showAgentDetail`, `runForeground`, `spawnBackground`, `assembleSessionConfig`, `subscribeUIObserver` + `emit`, and the `svc.*` calls) stay inline and explicit in each test.
+A reviewer can grep each migrated file to confirm no helper name wraps an act call.
+
+## TDD Order
+
+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.
+Steps 4–8 are independent of each other and order-insensitive; Steps 2–3 depend on Step 1.
+
+1. **Add shared `createResolvedSpawnConfig` + helper test.**
+   Surface: `test/helpers/make-spawn-config.ts`, `test/helpers/make-spawn-config.test.ts`.
+   Covers: default shape, the four scalar overrides, derived `agentInvocation`/`presentation.detailBase` mirroring.
+   Run the helper test, then `pnpm run check`.
+   Commit: `test: add shared createResolvedSpawnConfig builder (#379)`.
+2. **Migrate `foreground-runner.test.ts`.**
+   Delete local `makeConfig`; point `makeParams` at the shared builder; add `spawnAndWaitRegistering()`; re-check imports; run full suite green.
+   Commit: `test: consolidate foreground-runner spawn-config fixtures (#379)`.
+3. **Migrate `background-spawner.test.ts`.**
+   Delete local `makeConfig`; point `makeParams` at the shared builder with background defaults; re-check imports; run full suite green.
+   Commit: `test: consolidate background-spawner spawn-config fixtures (#379)`.
+4. **Consolidate `ui-observer.test.ts`.**
+   Add describe-scoped `beforeEach`; switch counters to `vi.fn()` onUpdate; run full suite green.
+   Commit: `test: consolidate ui-observer arrange into beforeEach (#379)`.
+5. **Consolidate `agent-creation-wizard.test.ts`.**
+   Add `manualUI()` / `withInputs()`; route cloned arrange; run full suite green.
+   Commit: `test: consolidate agent-creation-wizard arrange builders (#379)`.
+6. **Consolidate `agent-config-editor.test.ts`.**
+   Add `disabledConfig(base)`; route the disabled-config arranges; run full suite green.
+   Commit: `test: consolidate agent-config-editor disabled-config arrange (#379)`.
+7. **Consolidate `session-config.test.ts`.**
+   Add `exploreConfig(model?)`; route the model-resolution arranges; run full suite green.
+   Commit: `test: consolidate session-config model fixtures (#379)`.
+8. **Consolidate `service-adapter.test.ts`.**
+   Add `createManagerStub(overrides)`; replace the four stub factories/literal; re-check imports; run full suite green.
+   Commit: `test: consolidate service-adapter manager stubs (#379)`.
+9. **Measure and record outcome.**
+   Run `pnpm exec fallow dupes -r packages/pi-subagents` and record the resulting clone-group count and duplication percentage; run `pnpm run check && pnpm run lint && pnpm fallow dead-code`.
+   Update `docs/architecture/architecture.md` Step 8 to ✅ Complete with a `Landed:` bullet (figures, what was extracted, what was intentionally left inline), add service-adapter to its `Targets`, and refresh the current-state "Test duplication" figure.
+   Commit: `docs: mark Phase 17 Step 8 complete (#379)`.
+
+## Risks and Mitigations
+
+- **Over-extraction / procedure-splitting to chase the metric (the Step 7 lesson).**
+  Mitigation: only value-returning arrange builders and `beforeEach` setup are extracted; every act stays inline; the "Invariants at risk" grep check confirms no helper wraps an act.
+- **Divergent defaults across the consolidated factories cause assertion failures.**
+  Mitigation: the differing scalars are tabulated in Design (tools `ResolvedSpawnConfig`; service-adapter manager stub) before writing each shared builder; migration sets the differing fields via overrides.
+- **Deep-merge trap on the nested `ResolvedSpawnConfig`.**
+  Mitigation: the builder takes **flat** options and assembles the nested structure internally, so no caller passes a partial nested object expecting a merge.
+- **Orphaned imports after deleting local builders (Biome `noUnusedImports` is exit 0).**
+  Mitigation: re-check each migrated file's imports as part of its step; the Step 9 `pnpm run lint` + `fallow dead-code` pass is the backstop.
+
+## Open Questions
+
+- The roadmap's stated Step 8 outcome ("clone groups 44 → ≤ 25; overall duplication ≤ 0.6%") predates Steps 1–7; today's baseline is 32 groups / 2.49% under a different fallow metric.
+  Per the planning decision, acceptance is "each named family consolidated; resulting `fallow dupes` numbers reported," not a binding group target.
+  Step 9's measurement (or a later metric reconciliation) can decide whether to restate the roadmap's numeric target.
+- Whether the menu-structure `showAgentDetail` tests in `agent-config-editor.test.ts` should eventually collapse into the `buildMenuOptions` unit tests (Test Impact Analysis item 2) — deferred as a coverage decision, not duplication removal.
+
+[#378]: https://github.com/gotgenes/pi-packages/issues/378
+[#380]: https://github.com/gotgenes/pi-packages/issues/380
+[#412]: https://github.com/gotgenes/pi-packages/issues/412

package/docs/plans/0380-extract-layered-settings-loader.md

@@ -0,0 +1,223 @@
+---
+issue: 380
+issue_title: "Resolve the cross-package settings-loader duplication"
+---
+
+# Extract a layered settings loader into the pi-subagents public surface
+
+## Problem Statement
+
+`pnpm fallow:dupes` reports a 23-line cross-package production clone: `src/settings.ts:198-211` ↔ `@gotgenes/pi-subagents-worktrees`'s `src/config.ts:51-73`.
+Both implement the same layered global/project settings-file loader — read each path, sanitize parsed JSON, warn to stderr on malformed input, and merge with the project file overriding global.
+It is the only cross-package production clone in the package.
+
+Issue [#380] frames this as a binary decision: extract a shared `loadLayeredSettings` helper from pi-subagents' public surface, or document the duplication as intentional and record a fallow suppression.
+The operator chose extraction — pi-subagents should provide layered-settings loading as core support for the `@gotgenes/pi-*` family — delivered through a **dedicated subpath export** (`@gotgenes/pi-subagents/settings`) rather than the cross-extension service contract, and sequenced as **two stages**: this plan lands the helper in pi-subagents (exported and adopted internally); a follow-up migrates worktrees onto it after a published release.
+
+## Goals
+
+- Add a generic `loadLayeredSettings<T>(...)` function that owns the read-sanitize-warn-merge idiom: global file under `<agentDir>/<filename>`, project file under `<cwd>/.pi/<filename>`, project overriding global, missing files silent, malformed files warned-but-continued.
+- Export it from pi-subagents via a new dedicated subpath, `@gotgenes/pi-subagents/settings`, keeping the existing `.` service contract (spawn/abort/workspace seam) cohesive and unchanged.
+- Adopt the helper internally: `src/settings.ts`'s `loadSettings` delegates to `loadLayeredSettings`, proving the helper against a real consumer and removing the pi-subagents copy of the idiom.
+- Extend the `.d.ts` bundle (`rollup.dts.config.mjs`) and the `verify:public-types` harness to cover the new subpath, so the export is provably type-consumable from the packaged tarball.
+- Document the helper for third-party extension authors (input/return contract, throw/warn semantics, a minimal wiring example).
+- This is a non-breaking, additive change: `feat:` — a new public capability plus an internal refactor.
+  `loadSettings`'s observable behavior is preserved.
+
+## Non-Goals
+
+- Migrating `@gotgenes/pi-subagents-worktrees` onto the helper.
+  Worktrees resolves pi-subagents from the **registry** (`linkWorkspacePackages: false`), so it can only consume the helper after a pi-subagents release carrying it.
+  That migration — swap `config.ts`'s loader, raise the peer/dev dependency floor, delete the worktrees copy — is a separate follow-up issue (created at ship time).
+  Until it lands, the worktrees copy of the idiom persists (see Risks).
+- Touching `saveSettings` or the `SettingsManager` class beyond the `loadSettings` delegation.
+  Saving is pi-subagents-specific (worktrees has no save path) and stays as-is.
+- Changing how Pi loads the extension (`pi.extensions: ["./src/index.ts"]` is untouched).
+- Adding a fallow suppression — extraction is the chosen path, not Option 2.
+
+## Background
+
+Relevant modules and facts:
+
+- `packages/pi-subagents/src/settings.ts` — owns `SubagentsSettings`, the `SettingsManager` class, and the free functions `loadSettings`, `saveSettings`, `persistToastFor`, plus private `sanitize`, `globalPath`, `projectPath`, `readSettingsFile`.
+  The cloned block is `readSettingsFile` (lines 197-208) plus the `loadSettings` merge (lines 209-211).
+  `loadSettings(agentDir, cwd = process.cwd())` is called once, by `SettingsManager.load()`, which passes `this.cwd` explicitly.
+  `saveSettings` calls `projectPath(cwd)` — so `projectPath` stays; only `globalPath` and `readSettingsFile` lose their callers after the refactor.
+- `packages/pi-subagents-worktrees/src/config.ts` — the clone partner.
+  `loadWorktreesConfig(agentDir, cwd)` with private `sanitize`, `globalPath`, `projectPath`, `readConfigFile`.
+  Its `sanitize` validates a `string[]` (`worktreeAgents`); pi-subagents' validates numeric fields with ceilings.
+  The per-package `sanitize` is the genuinely-different part; the read/merge/warn mechanism is identical.
+- `packages/pi-subagents/rollup.dts.config.mjs` — rolls `src/service/service.ts` into `dist/public.d.ts` (the only public entry today), externals = `@earendil-works/*` + `@sinclair/typebox`.
+  Exports a single config object.
+- `packages/pi-subagents/scripts/verify-public-types.sh` — packs the tarball, asserts `dist/public.d.ts` is `#src`-free and carries the expected symbols, then type-checks a throwaway consumer importing from `@gotgenes/pi-subagents`.
+  Run in CI via the existing `verify:public-types` step (no `ci.yml` change needed — the extended script covers the new probe).
+- `package.json` `exports` has only `"."`; `files` already allowlists `src` and `dist`, so a new `src/` module and a new `dist/*.d.ts` ship automatically.
+
+Constraints from `AGENTS.md` and skills:
+
+- Public API documentation: a new cross-extension export must be documented for third-party authors, not just typed ([code-design] skill).
+- Library functions must not read `process.cwd()` / `process.env` internally — accept them as parameters ([code-design] skill).
+  The new helper takes `agentDir` and `cwd` explicitly (no `process.cwd()` default), matching the only caller, which already passes `this.cwd`.
+- The published `dist/*.d.ts` must be self-contained (no `#src/*`) — the harness gates on it.
+  The helper imports only `node:fs` / `node:path` and is generic over `T`, so its rolled declaration is trivially self-contained.
+- This is the package with the repo's only build step ([ADR-0003]); the subpath export extends that machinery rather than introducing a new mechanism.
+
+Why a dedicated subpath rather than `service/service.ts`: the `.` entry is the cross-extension **service contract**.
+A stateless settings-file utility is a different kind of thing; folding it into the service surface dilutes its cohesion.
+A `./settings` subpath keeps the two concerns separate at the cost of a second rollup entry and a second `verify:public-types` probe (accepted in the decision).
+
+## Design Overview
+
+### Public API shape
+
+```typescript
+/**
+ * Describes one layered settings source: a global file at `<agentDir>/<filename>`
+ * and a project file at `<cwd>/.pi/<filename>`. @public
+ */
+export 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, e.g. "subagents.json". */
+  filename: string;
+  /** Validate/coerce parsed JSON into a partial settings object. Garbage → {}. */
+  sanitize: (raw: unknown) => Partial<T>;
+  /** Label for the malformed-file stderr warning, e.g. "pi-subagents". */
+  warnLabel: string;
+}
+
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ * Missing files are silent ({}). A file that exists but cannot be parsed warns
+ * to stderr (prefixed `[warnLabel]`) and is treated as absent so startup proceeds.
+ */
+export function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T>;
+```
+
+The helper internalizes everything the two copies share: the two path constructions (`join(agentDir, filename)` and `join(cwd, ".pi", filename)`), the single-file read (`existsSync` → `JSON.parse(readFileSync)` → `sanitize`, `catch` → `console.warn("[label] Ignoring malformed settings at ...")` → `{}`), and the project-over-global merge.
+Callers supply only what genuinely differs: `filename`, `sanitize`, `warnLabel`.
+
+Returning `Partial<T>` fits both consumers: `SubagentsSettings`'s fields are all optional (`Partial<SubagentsSettings>` is identical), and worktrees applies its `?? []` default in its own caller after the merge.
+
+### Internal consumer call site (pi-subagents `settings.ts`)
+
+```typescript
+export function loadSettings(agentDir: string, cwd: string): SubagentsSettings {
+  return loadLayeredSettings({
+    agentDir,
+    cwd,
+    filename: "subagents.json",
+    sanitize,
+    warnLabel: "pi-subagents",
+  } satisfies LayeredSettingsSource<SubagentsSettings>);
+}
+```
+
+The `satisfies` annotation both validates the call site and gives `LayeredSettingsSource` an in-repo reference, so fallow does not flag the exported interface as an unused type.
+The warn message stays `"[pi-subagents] Ignoring malformed settings at ..."`, so the existing `/Ignoring malformed settings/` assertion in `settings.test.ts` still passes.
+`process.cwd()` default is dropped from `loadSettings`; the sole caller (`SettingsManager.load`) already passes `this.cwd`.
+
+### Subpath export wiring
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  },
+  "./settings": {
+    "types": "./dist/settings.d.ts",
+    "default": "./src/layered-settings.ts"
+  }
+}
+```
+
+`rollup.dts.config.mjs` becomes an array with a second entry (`input: "src/layered-settings.ts"` → `dist/settings.d.ts`), same plugin/externals.
+`files` already covers `src` and `dist`, so no allowlist change.
+
+### Edge cases
+
+- Both files missing → `{}` (no warn).
+- A file present but unparseable → warn once per bad file, that layer treated as `{}`.
+- Both present → shallow merge, project wins per key.
+- `sanitize` returning `{}` for garbage shapes is the caller's concern; the helper never inspects field types.
+
+## Module-Level Changes
+
+- `packages/pi-subagents/src/layered-settings.ts` — **new**.
+  Exports `loadLayeredSettings` and `LayeredSettingsSource<T>`; imports only `node:fs` (`existsSync`, `readFileSync`) and `node:path` (`join`).
+  Private helpers (path builders, single-file reader) stay in-file below the public function (stepdown order).
+- `packages/pi-subagents/src/settings.ts`
+  - `loadSettings` delegates to `loadLayeredSettings`; drop the `process.cwd()` default.
+  - Remove private `readSettingsFile` and `globalPath` (no remaining callers once `loadSettings` delegates).
+  - Keep `projectPath` (still used by `saveSettings`), `sanitize`, `saveSettings`, `persistToastFor`, `SettingsManager`.
+- `packages/pi-subagents/package.json` — add the `"./settings"` conditional export.
+- `packages/pi-subagents/rollup.dts.config.mjs` — export an array; add the `src/layered-settings.ts` → `dist/settings.d.ts` entry.
+- `packages/pi-subagents/scripts/verify-public-types.sh` — add a self-containment guard for `dist/settings.d.ts` (no `#src`, carries `loadLayeredSettings`) and a probe importing `loadLayeredSettings` from `@gotgenes/pi-subagents/settings`.
+- `packages/pi-subagents/test/layered-settings.test.ts` — **new** unit tests (see TDD Order).
+- `packages/pi-subagents/docs/architecture/architecture.md`
+  - Step 9 entry (lines ~1027-1033): record the chosen approach (extraction via `./settings` subpath; internal adoption; worktrees migration deferred to a follow-up) and restate the Outcome (see Risks — full fallow elimination completes with the follow-up).
+  - "Production duplication" metric note (line ~900) and any roadmap-summary line referencing the 23-line cross-package clone: update once the pi-subagents copy is gone.
+- `packages/pi-subagents/README.md` and/or `.pi/skills/package-pi-subagents/SKILL.md` — note the new `@gotgenes/pi-subagents/settings` public entry and its contract (third-party-author documentation).
+
+No symbol named in this plan is referenced by `.pi/skills/package-*/SKILL.md` today (`readSettingsFile` / `globalPath` are private and not documented) — verified by grep; the only SKILL/README edits are additive (documenting the new export).
+
+## Test Impact Analysis
+
+1. New tests this enables: direct unit coverage of the generic loader — the `warnLabel`-parametrized warning prefix, an arbitrary `filename`, and an arbitrary `sanitize` — none of which `settings.test.ts` can reach because it only exercises the `"subagents.json"` / `"pi-subagents"` wiring.
+2. Existing tests that become partly redundant: the generic mechanics in `settings.test.ts` (missing→{}, malformed→warn, project-over-global precedence) are now also covered at the lower level.
+   They are **kept** — they still genuinely exercise `loadSettings`'s wiring and the `SubagentsSettings`-specific `sanitize` (numeric ceilings), which the lower-level tests do not.
+3. Tests that must stay as-is: all of `settings.test.ts` (wiring + `SubagentsSettings` sanitize + `saveSettings` + `persistToastFor`).
+
+## Invariants at risk
+
+`settings.ts` was not refactored by an earlier Phase 17 step (it is outside the `Subagent`/lifecycle cluster), so no prior step's documented `Outcome:` is regressed.
+The invariant under change is `loadSettings`'s observable behavior (merge precedence, silent-missing, warn-malformed) — pinned by the existing `settings.test.ts` cases, which stay green throughout the refactor.
+No new pin is needed.
+
+## TDD Order
+
+1. **Add `loadLayeredSettings` + unit tests.**
+   Red: `test/layered-settings.test.ts` driving the helper directly via temp dirs (mirroring `settings.test.ts`'s tmp-dir pattern): missing files → `{}`; malformed file → `console.warn` with the `[warnLabel]` prefix + `{}`; project overrides global; custom `filename` resolves `<agentDir>/<filename>` and `<cwd>/.pi/<filename>`; `sanitize` applied to parsed JSON.
+   Green: implement `src/layered-settings.ts`.
+   The test import keeps the new export live for fallow dead-code.
+   Commit: `feat(pi-subagents): add loadLayeredSettings layered config loader`.
+2. **Adopt internally in `settings.ts`.**
+   Refactor `loadSettings` to delegate to `loadLayeredSettings` (with the `satisfies` call site); remove `readSettingsFile` and `globalPath`.
+   No test changes — the existing `settings.test.ts` suite (including the `/Ignoring malformed settings/` warn assertion) must stay green, proving behavior preservation.
+   Run `pnpm fallow dead-code` to confirm no orphaned private helper remains.
+   Commit: `refactor(pi-subagents): load settings via loadLayeredSettings`.
+3. **Publish the `./settings` subpath + document it.**
+   Add the `"./settings"` export, the second `rollup.dts.config.mjs` entry, and the `verify-public-types.sh` guard + probe; add the third-party-author JSDoc/README/SKILL note.
+   Run `pnpm run build:types` and `pnpm run verify:public-types` — the new `dist/settings.d.ts` must be `#src`-free and the subpath probe must type-check.
+   Commit: `feat(pi-subagents): export loadLayeredSettings via ./settings subpath`.
+4. **Record the decision in the architecture doc.**
+   Update the Step 9 roadmap entry and the duplication-metric notes to reflect extraction + the deferred worktrees follow-up; run `pnpm fallow:dupes --skip-local` and record whether the cross-package pair still reports (see Risks).
+   Commit: `docs(pi-subagents): record settings-loader extraction decision (#380)`.
+
+## Risks and Mitigations
+
+- **The cross-package clone may still report after this plan.**
+  Worktrees' copy persists until the follow-up.
+  The extracted helper is generic (parametrized `warnLabel`/`sanitize`), so its token sequence diverges from worktrees' inlined copy; the contiguous identical run likely drops below fallow's `min-lines: 5`, dissolving the pair — but this is not guaranteed.
+  Mitigation: Step 4 runs `fallow:dupes --skip-local` and records the actual result.
+  Definitive elimination of the pair is an explicit outcome of the worktrees follow-up, not a hard gate on this plan; this plan's measurable outcome is that pi-subagents owns and publishes the canonical loader.
+- **`rollup-plugin-dts` second-entry resolution.**
+  Low risk — the module is dependency-free apart from `node:*`.
+  Step 3's `build:types` + `verify:public-types` is the checkpoint; if `dist/settings.d.ts` is not self-contained, stop and reassess before wiring the export.
+- **Permanent public-API surface growth.**
+  Accepted per the [#380] decision; mitigated by isolating the helper on its own subpath so the service contract stays minimal, and by documenting it for third-party authors.
+- **`loadSettings` signature change (dropped `process.cwd()` default).**
+  Internal only — the sole caller passes `cwd` explicitly; verified by grep.
+
+## Open Questions
+
+- Exact new module filename (`src/layered-settings.ts` proposed) — settle in Step 1.
+- Whether the third-party docs live in `README.md`, the package `SKILL.md`, or both — settle in Step 3.
+- The follow-up worktrees-migration issue number — created at ship time; referenced from the Step 9 roadmap entry.
+
+[#380]: https://github.com/gotgenes/pi-packages/issues/380
+[ADR-0003]: ../decisions/0003-publish-bundled-type-declarations.md
+[code-design]: ../../../../.pi/skills/code-design/SKILL.md