@gotgenes/pi-subagents 16.3.1 → 16.4.0

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

@@ -0,0 +1,100 @@
+---
+issue: 378
+issue_title: "Consolidate lifecycle test fixtures"
+---
+
+# Retro: #378 — Consolidate lifecycle test fixtures
+
+## Stage: Planning (2026-06-15T00:00:00Z)
+
+### Session summary
+
+Planned Phase 17 Step 7 — consolidating the lifecycle test clone families into shared/file-local helpers.
+Produced `docs/plans/0378-consolidate-lifecycle-test-fixtures.md` with a six-step lift-and-shift TDD order and committed it.
+
+### Observations
+
+- The issue body is stale relative to `main`: it cites five families across six files (including `concurrency-queue.test.ts` and a 766-LOC `subagent-manager.test.ts`).
+  Measuring with `fallow dupes -r packages/pi-subagents` against today's `main` shows **four** lifecycle families — Steps 1–6 already removed the queue (`concurrency-queue.test.ts` → `concurrency-limiter.test.ts`) and the `subagent.test.ts`/`concurrency-limiter.test.ts` families.
+  The plan is written against the measured current state, not the issue snapshot.
+- Design call: promote to `test/helpers/` only the genuinely cross-file duplication (the `createSubagentSession`-test mock-session builder, shared by `create-subagent-session.test.ts` and `create-subagent-session-extension-tools.test.ts` — `createFactorySession`).
+  The manager and `subagent-session` families are intra-file (fallow recommends same-file extraction), so they get file-local helpers.
+  Force-promoting intra-file families to `test/helpers/` would manufacture cross-file coupling that does not exist.
+- Resisted extracting the `io.createSession.mockResolvedValue(...)` + `createSubagentSession(...)` invoke pair into a helper — two lines with per-test varying overrides; wrapping the system-under-test call would be procedure-splitting, not design improvement.
+- Invariants at risk flagged: Step 1/Step 3's "every spawned agent has a `promise` at spawn" (pinned by the queued-promise test) and Step 3's "zero external `.promise`/`.notification` writes outside `subagent.ts`" (grep-verifiable).
+  `arrangeQueuedPair()` must return the queued id; Step 4 folds in a re-grep.
+- Baseline: package test duplication 669 lines / 3.3% across 20 files; the four lifecycle families total ~122 lines, so Step 7 alone should land below the 600-line goal (~547).
+  Flagged as an Open Question pending the Step 6 `fallow dupes` measurement.
+- Not breaking — test-only, no `src/`, public-surface, or behavior change.
+
+## Stage: Implementation — TDD (2026-06-15T23:10:00Z)
+
+### Session summary
+
+Executed the lifecycle test fixture consolidation across 8 commits.
+Added a shared `createFactorySession` builder, migrated the four lifecycle clone families, and (on operator steer) folded `create-subagent-session-extension-tools.test.ts` into `create-subagent-session.test.ts`, deleting the file.
+Package test duplication dropped 669 → 512 lines (under the 600 goal); test count 1005 → 1010 (+5 `createFactorySession` self-tests); test files 64 → 63.
+Pre-completion reviewer: PASS.
+
+### Observations
+
+- Plan premise was wrong on one point: extracting `createFactorySession` alone did **not** collapse the create-subagent-session families — the dominant clone was the arrange-act invoke block, not the builder.
+  I first extracted a `runCreate`/`runCreateWith` act-helper to hit the metric, then the operator flagged it: mixing arrange + act hides the system under test, and arranges should be grouped by `describe`.
+  Reworked to AAA — describe-scoped `beforeEach` for arrange, `createSubagentSession(...)` act kept explicit per test.
+- The operator relaxed the roadmap's "lifecycle families ≤ 1" Outcome.
+  Two families remain by design (the repeated act with test-specific arrange); documented as intentional in `architecture.md` Step 7.
+  Lesson recorded: a clone-count metric is a weak signal for *test* code — AAA structure beats it, and chasing the metric produced the wrong abstraction before it was caught.
+- `programTurns(session, listeners, turns)` is a legitimate arrange helper for the turn-limit tests (turn count is the meaningful input, not a discriminator flag); removed the restated-boundary comments per `code-design` (names/args over comments).
+- Folding the extension-tools tests was safe because the recursion guard reads only the session mock's `getActiveToolNames`/`setActiveToolsByName`; the agent config and `type` don't affect those assertions (mocked `io.createSession` ignores `cfg.toolNames`).
+- Surfaced three overlapping session-mock builders (`createMockSession`, `createSubagentSessionStub`, `createFactorySession`); filed [#412] as a follow-up rather than expanding #378 scope.
+- Cross-step invariants verified intact: queued-agent "promise at spawn" ([#374]) test preserved through the `arrangeQueuedPair` extraction; zero external `.promise`/`.notification` writes in `test/lifecycle/`.
+
+## Stage: Final Retrospective (2026-06-15T23:45:00Z)
+
+### Session summary
+
+Shipped Phase 17 Step 7 across plan → TDD → ship in one continuous session: 11 `test:`/`docs:` commits, package test duplication 669 → 512 lines, test files 64 → 63, tests 1005 → 1010.
+The dominant arc was a metric-driven detour — an act-wrapping helper extracted to satisfy the roadmap's "families ≤ 1" target, caught by the operator and reworked into an AAA structure (describe-scoped arrange, visible act).
+CI passed, issue closed, no release (test/docs commits only); follow-up [#412] filed.
+
+### Observations
+
+#### What went well
+
+- The "no sacred cows" invitation → structured `ask_user` multi-select produced a real improvement: deleting the redundant `create-subagent-session-extension-tools.test.ts` entirely (#1) and filing [#412], rather than accepting the status quo.
+  Self-critique under explicit invitation surfaced a whole-file removal the plan had not considered.
+- Verification was incremental, not end-only: `pnpm run check` plus a per-file `vitest run` plus a `fallow dupes` re-measurement ran between every TDD step, so each consolidation's effect on the clone count was visible immediately.
+- Cross-step invariant discipline held: the queued-agent "promise at spawn" ([#374]) test survived the `arrangeQueuedPair` extraction, and the grep for external `.promise`/`.notification` writes stayed at zero.
+- The release-timing gate correctly fired on the phased roadmap (Phase 17 Step 7 of 9) and surfaced the batch-vs-now choice instead of releasing silently.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — extracted a `runCreate`/`runCreateWith` act-helper that bundled arrange + the `createSubagentSession(...)` act, hiding the system under test, purely to drive the clone count to the roadmap's "families ≤ 1" target.
+  User-caught.
+  Impact: one commit (`96acc6c7`) committed then undone via `git reset --soft HEAD~1` and reworked into the AAA structure (`14375b07`); ~1 commit of rework, caught before ship.
+- `missing-context` — the plan asserted `createFactorySession` was "the larger half of each clone" without decomposing the clone; the post-Step-3 `fallow dupes` measurement showed the arrange-act invoke block was the dominant half, which is what drove the wrong-abstraction detour.
+  Impact: a wrong planning premise that fed the rework above.
+  A `fallow dupes --trace <file:line>` per-line decomposition during planning would have shown the split.
+- `other` (tool misuse) — first invoked `set_session_name` as a shell command (`command not found`), then self-corrected to the tool call.
+  Impact: one wasted call, no rework.
+
+#### What caused friction (user side)
+
+- The operator's redirect on arrange/act mixing landed after the act-helper was already committed.
+  The natural self-checkpoint was earlier: when the Step-3 measurement contradicted the plan's "builder is the larger half" premise, that contradiction was itself a deviation worth surfacing via `ask_user` ("wrap the act to hit the metric, or accept the residual for better structure?") rather than pushing forward to the helper.
+  Framed as opportunity: treat a plan's quantitative premise proving wrong as a stop-and-ask trigger, not a cue to escalate the abstraction.
+
+### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`) on a judgment-heavy review task; appropriate match, no mismatch.
+- **Escalation-delay tracking** — no rabbit-hole: the wrong-abstraction was a single committed approach redirected by the operator, not a repeated-error loop, so no 5+ consecutive same-error sequence.
+- **Unused-tool detection** — `fallow dupes --trace <file:line>` was available and would have decomposed the clone into builder-vs-act portions during planning; it was not used, and its absence is what let the wrong premise stand.
+- **Feedback-loop gap analysis** — no gap; checks ran incrementally after each step.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` (§ Test organization) — added a rule to group shared arrange in a describe-scoped `beforeEach`, keep the act explicit, and not wrap the system-under-test call to eliminate a duplication-metric clone.
+2. `.pi/prompts/tdd-plan.md` — sharpened the deviation rule: a quantitative target (LOC, clone count, complexity) that does not fall out as predicted is a stop-and-ask deviation, re-decided via `ask_user` rather than forcing the number.
+
+[#374]: https://github.com/gotgenes/pi-packages/issues/374
+[#412]: https://github.com/gotgenes/pi-packages/issues/412

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

@@ -0,0 +1,52 @@
+---
+issue: 379
+issue_title: "Consolidate UI and tools test fixtures"
+---
+
+# Retro: #379 — Consolidate UI and tools test fixtures
+
+## Stage: Planning (2026-06-16T00:00:00Z)
+
+### Session summary
+
+Produced a 9-step lift-and-shift plan for Phase 17 Step 8 — consolidating the non-lifecycle test clone families.
+Measured the live baseline (`fallow dupes -r packages/pi-subagents`: 32 clone groups / 512 lines / 2.49%, seven families) and characterized each family by reading all seven test files, classifying each as genuine cross-file duplication (one) versus intra-file (six).
+
+### Observations
+
+- The only genuine cross-file duplication is the `ResolvedSpawnConfig` builder shared by `foreground-runner.test.ts` and `background-spawner.test.ts` (`dup:80ee2004`) — the one promotion to `test/helpers/` (`make-spawn-config.ts`).
+  Everything else fallow scores same-file, so it stays file-local or moves into a describe-scoped `beforeEach`, per Step 7's ([#378]) discipline.
+- The plan's central constraint is Step 7's hard-won lesson: never wrap the system-under-test **act** in a helper to chase a duplication metric.
+  Every extracted helper returns a value (`createResolvedSpawnConfig`, `disabledConfig`, `exploreConfig`, `createManagerStub`, `spawnAndWaitRegistering`) or seeds `beforeEach`; the acts stay inline.
+  Added an "Invariants at risk" grep check to enforce this at review.
+- Scope was genuinely ambiguous and resolved via `ask_user`: the issue body names six files, but fallow reports a seventh non-lifecycle family in `test/service/service-adapter.test.ts` (four near-identical `SubagentManagerLike` stubs).
+  Operator chose to include service-adapter (seven files total) and to **not** bind a numeric group target — acceptance is "each named family consolidated, resulting fallow numbers reported."
+  My `ask_user` prompt incorrectly claimed the architecture roadmap's Step 8 `Targets` lists service-adapter; it does not (it lists the six issue-body files).
+  The plan corrects this and notes service-adapter was added in planning.
+- The roadmap's stated Step 8 outcome ("clone groups 44 → ≤ 25; overall duplication ≤ 0.6%") predates Steps 1–7 and does not match the current fallow metric (2.49%); flagged as an Open Question rather than treated as binding.
+- Non-Goals call out the two residual lifecycle families (Step 7 left them as the visible act), the 11-line production clone inside `src/ui/agent-config-editor.ts` (test-only issue), and the three overlapping session-mock builders ([#412]).
+- `ResolvedSpawnConfig` is deeply nested (`identity`/`execution`/`presentation` with mirrored scalars).
+  Designed the shared builder to take **flat** options and assemble the nested structure internally — sidesteps the `Partial<T>` deep-merge trap and encapsulates the mirroring (`agentInvocation.runInBackground`, `presentation.detailBase`) the hand-built copies duplicate.
+
+## Stage: Implementation — TDD (2026-06-16T13:10:00Z)
+
+### Session summary
+
+Executed all 9 plan steps as green-to-green lift-and-shift refactors (no red phase — the existing assertions were the spec), one commit per step plus the docs commit.
+Promoted the shared `createResolvedSpawnConfig` builder to `test/helpers/` (+5 self-tests) and consolidated the six remaining families with file-local value-returning builders / `beforeEach` setup.
+Test count 1010 → 1015; test files 63 → 64; clone groups 32 → 24; package test duplication 512 → 355 lines (2.49% → 1.73%).
+
+### Observations
+
+- The `agent-config-editor.test.ts` family did not collapse as the plan loosely estimated ("4 → ideally 2"): it stayed at 4 groups / 28 lines.
+  The `disabledConfig` helper removed only the small `enabled: false` arrange; the 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 (Step 7 lesson).
+  No `ask_user` was needed: acceptance was "consolidate and measure" (no binding numeric target), and the only way to force the number would violate the plan's stated discipline.
+- `service-adapter.test.ts` had four near-identical `SubagentManagerLike` stub factories with diverging defaults (`hasRunning` true vs false, varying `spawn` returns).
+  Consolidated into one file-local `createManagerStub()` with **unannotated** return (typed `vi.fn<SubagentManagerLike[...]>()` stubs) so callers retain `Mock<...>` methods — per the testing-skill rule that annotating the return with the production interface, or spreading `Partial<Interface>` overrides, erases mock methods.
+  Dropped the overrides parameter entirely; per-test behavior is configured on the returned object (`mgr.getRecord.mockImplementation(...)`, `mgr.hasRunning.mockReturnValue(true)`).
+  Used `sed` to swap the `defaultManager()` / `createTestManager()` call sites after deleting the factory definitions.
+- `ui-observer` update-counting tests moved from closure `let updateCount` counters to `vi.fn()` onUpdate with `toHaveBeenCalledTimes` — removes the repeated scaffolding without hiding the `session.emit` act.
+- Pre-completion reviewer: WARN — sole finding was this missing TDD retro entry (now written); all deterministic checks PASS, cross-step invariant ("don't wrap the act") verified upheld, 6 Mermaid blocks validated, dead-code clean.
+
+[#378]: https://github.com/gotgenes/pi-packages/issues/378
+[#412]: https://github.com/gotgenes/pi-packages/issues/412

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

@@ -0,0 +1,48 @@
+---
+issue: 380
+issue_title: "Resolve the cross-package settings-loader duplication"
+---
+
+# Retro: #380 — Resolve the cross-package settings-loader duplication
+
+## Stage: Planning (2026-06-16T00:00:00Z)
+
+### Session summary
+
+Planned the resolution of the 23-line cross-package production clone between `src/settings.ts` and `@gotgenes/pi-subagents-worktrees`'s `src/config.ts`.
+Issue #380 posed a binary: extract a shared loader vs. document-and-suppress.
+The operator chose extraction, delivered as a dedicated subpath export `@gotgenes/pi-subagents/settings`, sequenced as two stages (this plan lands the helper in pi-subagents; a follow-up migrates worktrees).
+The plan is a single-package TDD plan in `packages/pi-subagents/docs/plans/0380-extract-layered-settings-loader.md`.
+
+### Observations
+
+- The issue is the operator's own (author `gotgenes` == gh user), so the "Proposed change" was a hypothesis.
+  Used `ask_user` twice: first to confirm Option 1 vs Option 2 (operator picked extract, then asked for explicit for/against), then to pin API placement (`./settings` subpath, recommended) and release sequencing (two-stage, follow-up for worktrees).
+- Key mechanism finding that shaped the framing: fallow's `code-duplication` suppression is **file-scoped only** (`// fallow-ignore-file code-duplication`) — there is no line-level next-line directive, contrary to the issue's "rationale on the line above" phrasing for Option 2.
+  This would have mattered had Option 2 been chosen.
+- The shared idiom is the read-sanitize-warn-merge mechanism; the per-package `sanitize` (numeric ceilings vs `string[]`) is the genuinely-different part.
+  A generic `loadLayeredSettings<T>({ sanitize, warnLabel, filename, agentDir, cwd })` is a clean extraction with no discriminator parameter.
+- Honest Outcome caveat captured in the plan: because worktrees keeps its copy until the follow-up, `fallow:dupes` may still report a residual (or dissolve below `min-lines: 5`, since the generic helper's tokens diverge).
+  Definitive elimination is the follow-up's outcome, not a hard gate on this plan.
+- Followed the `0270-type-consumable-public-surface.md` plan as the template for the `.d.ts`-bundle + `verify:public-types` machinery; the new subpath extends that rather than introducing a new mechanism.
+- `loadSettings`'s `process.cwd()` default is dropped per the code-design "no `process.*` in library functions" rule; the sole caller (`SettingsManager.load`) already passes `this.cwd` (verified by grep).
+- The worktrees-migration follow-up issue should be created at ship time and back-referenced from the architecture Step 9 roadmap entry.
+
+## Stage: Implementation — TDD (2026-06-16T16:00:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps from the plan: added `src/layered-settings.ts` with 15 unit tests, refactored `settings.ts` to delegate through the helper (removing `readSettingsFile` and `globalPath`), published the `@gotgenes/pi-subagents/settings` subpath export with a rolled `dist/settings.d.ts` and extended `verify:public-types` harness, and recorded the decision in the architecture doc.
+Test count grew from 1015 to 1030 (+15).
+Pre-completion reviewer returned **PASS**.
+Follow-up issue [#415] created for the worktrees migration.
+
+### Observations
+
+- The plan's "Outcome caveat" resolved favourably: `pnpm fallow:dupes --skip-local` no longer reports the `settings.ts` ↔ `config.ts` pair after the extraction.
+  The parametrised helper's token sequence diverged enough that the contiguous identical run dropped below the reporting threshold — a better outcome than the plan's hedged prediction.
+- ESLint's pre-commit hook removed `!` non-null assertions from `spy.mock.calls[0]![0]` in the test file (typed `vi.spyOn` mock calls are non-optional tuples; the assertions were redundant).
+  Staged the auto-fix into the same commit without issue.
+- The `rollup.dts.config.mjs` array-of-configs approach worked without incident: both bundles (`dist/public.d.ts` and `dist/settings.d.ts`) are self-contained and `verify:public-types` confirmed both probes type-check against the packaged tarball.
+- The `satisfies LayeredSettingsSource<SubagentsSettings>` annotation at the `loadSettings` call site serves double duty: validates the object literal and keeps `LayeredSettingsSource` referenced for fallow dead-code (fallow confirmed: 0 issues).
+- Follow-up issue [#415] created before the TDD stage notes were written (operator requested it during the session); architecture doc updated with the `[#415]` reference and link definition.

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.3.1",
+  "version": "16.4.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/public.d.ts",
       "default": "./src/service/service.ts"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "default": "./src/layered-settings.ts"
     }
   },
   "files": [

package/src/layered-settings.ts

@@ -0,0 +1,105 @@
+/**
+ * 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
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @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 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
+ */
+export function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T> {
+  const { agentDir, cwd, filename, sanitize, warnLabel } = source;
+  const global = readLayer(join(agentDir, filename), sanitize, warnLabel);
+  const project = readLayer(join(cwd, ".pi", filename), sanitize, warnLabel);
+  return { ...global, ...project };
+}
+
+// ── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Read one settings file. Missing → `{}` (silent). Malformed → `{}` + warn.
+ */
+function readLayer<T>(path: string, sanitize: (raw: unknown) => Partial<T>, warnLabel: string): Partial<T> {
+  if (!existsSync(path)) return {};
+  try {
+    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[${warnLabel}] Ignoring malformed settings at ${path}: ${reason}`);
+    return {};
+  }
+}

package/src/settings.ts

@@ -2,8 +2,9 @@
 // - Global:  ~/.pi/agent/subagents.json (agentDir injected at construction) — manual defaults, never written here
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { type LayeredSettingsSource, loadLayeredSettings } from "#src/layered-settings";
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -181,33 +182,19 @@ function sanitize(raw: unknown): SubagentsSettings {
   return out;
 }
 
-function globalPath(agentDir: string): string {
-  return join(agentDir, "subagents.json");
-}
-
 function projectPath(cwd: string): string {
   return join(cwd, ".pi", "subagents.json");
 }
 
-/**
- * Read a settings file. Missing file is silent (returns `{}`). A file that
- * exists but can't be parsed emits a warning to stderr so users aren't
- * silently reverted to defaults — and still returns `{}` so startup proceeds.
- */
-function readSettingsFile(path: string): SubagentsSettings {
-  if (!existsSync(path)) return {};
-  try {
-    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
-    return {};
-  }
-}
-
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
+export function loadSettings(agentDir: string, cwd: string): SubagentsSettings {
+  return loadLayeredSettings({
+    agentDir,
+    cwd,
+    filename: "subagents.json",
+    sanitize,
+    warnLabel: "pi-subagents",
+  } satisfies LayeredSettingsSource<SubagentsSettings>);
 }
 
 /**