@gotgenes/pi-subagents 6.3.1 → 6.5.0

package/docs/plans/0108-extract-agent-type-registry.md

@@ -0,0 +1,322 @@
+---
+issue: 108
+issue_title: "refactor(pi-subagents): extract AgentTypeRegistry class from module-scoped state"
+---
+
+# Extract AgentTypeRegistry class
+
+## Problem Statement
+
+`agent-types.ts` manages a module-scoped `Map<string, AgentConfig>` mutated by `registerAgents()` and read by 12+ call sites across 6 files.
+This is global mutable state hidden behind free functions — tests must call `registerAgents(new Map())` in `beforeEach` to reset it, and `reloadCustomAgents` is threaded as a callback through `AgentToolDeps` and `AgentMenuDeps` because there is no object to own the reload.
+
+## Goals
+
+- Wrap the module-scoped `agents` Map and its free functions into an injectable `AgentTypeRegistry` class.
+- Replace the `reloadCustomAgents` callback (threaded through 2 dependency bags) with `registry.reload()`.
+- Move `DEFAULT_AGENT_NAMES` from `types.ts` to the registry (it is a constant, not a type).
+- Enable test isolation without module resets — each test creates its own registry instance.
+- Use lift-and-shift: introduce the class alongside the free functions, migrate consumers incrementally, then remove the free functions.
+
+## Non-Goals
+
+- `SettingsManager` extraction (#109) — separate Phase 7 step.
+- `AgentActivityTracker` extraction (#110) — separate Phase 7 step.
+- Splitting `AgentRecord` lifecycle state (#111) — separate Phase 7 step.
+- Narrowing `AgentConfig` (21 fields) — tracked in the architecture doc but out of scope.
+- Moving `BUILTIN_TOOL_NAMES` — it is a constant with no Map dependency, stays as a module export.
+
+## Background
+
+### Architecture reference
+
+Phase 7, Step A1 in `docs/architecture/architecture.md`.
+Steps A1–A3 are independent and can proceed in any order.
+This plan addresses A1 only.
+
+### Relevant modules
+
+| Module                      | Role                                                     | agent-types dependency                                                                                                                                 |
+| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent-types.ts`            | Module-scoped `agents` Map + 11 free functions           | Owns the state                                                                                                                                         |
+| `default-agents.ts`         | `DEFAULT_AGENTS` Map constant                            | Read by `registerAgents`                                                                                                                               |
+| `custom-agents.ts`          | `loadCustomAgents()` → disk scan                         | Imports `BUILTIN_TOOL_NAMES`                                                                                                                           |
+| `session-config.ts`         | `assembleSessionConfig()`                                | Imports `resolveAgentConfig`, `getToolNamesForType`, `getMemoryToolNames`, `getReadOnlyMemoryToolNames`                                                |
+| `agent-runner.ts`           | `runAgent()` → calls `assembleSessionConfig`             | No direct import (transitive via session-config)                                                                                                       |
+| `agent-manager.ts`          | `AgentManager` → calls runner                            | No direct import                                                                                                                                       |
+| `tools/agent-tool.ts`       | Agent tool definition                                    | Imports `resolveAgentConfig`, `resolveType`; receives `reloadCustomAgents` via `AgentToolDeps`                                                         |
+| `ui/agent-menu.ts`          | `/agents` command handler                                | Imports `BUILTIN_TOOL_NAMES`, `getAllTypes`, `resolveAgentConfig`, `resolveType`; receives `reloadCustomAgents` via `AgentMenuDeps`                    |
+| `ui/agent-widget.ts`        | Widget + `getDisplayName` / `getPromptModeLabel` helpers | Imports `resolveAgentConfig`                                                                                                                           |
+| `ui/conversation-viewer.ts` | Live conversation overlay                                | Imports `getDisplayName`, `getPromptModeLabel` from `agent-widget.ts`                                                                                  |
+| `tools/get-result-tool.ts`  | `get_subagent_result` tool                               | Imports `getDisplayName` from `agent-widget.ts`                                                                                                        |
+| `index.ts`                  | Extension entry point, wiring                            | Imports `registerAgents`, `getAvailableTypes`, `getDefaultAgentNames`, `getUserAgentNames`, `resolveAgentConfig`; defines `reloadCustomAgents` closure |
+
+### Test files affected
+
+| Test file                                          | Current agent-types coupling                                              | Change needed                                                          |
+| -------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `agent-types.test.ts` (333 lines)                  | Tests free functions directly, calls `registerAgents()` in `beforeEach`   | Add class tests; eventually migrate free-function tests to class tests |
+| `session-config.test.ts` (601 lines)               | `vi.mock("../src/agent-types.js")`                                        | Pass mock registry param, remove module mock                           |
+| `agent-runner.test.ts` (302 lines)                 | `vi.mock("../src/agent-types.js")`                                        | Provide mock registry in `RunOptions`, remove module mock              |
+| `agent-runner-extension-tools.test.ts` (307 lines) | `vi.mock("../src/agent-types.js")`                                        | Same as `agent-runner.test.ts`                                         |
+| `tools/agent-tool.test.ts` (240 lines)             | Mocks `reloadCustomAgents` in deps                                        | Replace with `registry` in deps                                        |
+| `ui/agent-menu.test.ts` (184 lines)                | `vi.mock("../../src/agent-types.js")`, mocks `reloadCustomAgents` in deps | Replace with `registry` in deps, remove module mock                    |
+| `agent-widget.test.ts` (26 lines)                  | Minimal                                                                   | Pass registry to widget constructor                                    |
+| `agent-manager.test.ts` (712 lines)                | No `agent-types.js` mock                                                  | Add registry to constructor options                                    |
+
+### Constraints from AGENTS.md / code-design skill
+
+- **ISP:** `session-config.ts` should accept a narrow interface (only `resolveAgentConfig` + `getToolNamesForType`), not the full registry class.
+- **DIP:** Accept collaborators as parameters; keep IO at the edges.
+- **Pi SDK boundaries:** Pure helpers must not import Pi SDK types.
+- **Lift-and-shift:** Never plan a single step that rewrites an entire large test file at once.
+
+## Design Overview
+
+### `AgentTypeRegistry` class
+
+```typescript
+export class AgentTypeRegistry {
+  private agents = new Map<string, AgentConfig>();
+
+  constructor(private loadUserAgents: () => Map<string, AgentConfig>) {
+    this.reload();
+  }
+
+  /** Re-scan custom agents from disk and merge with defaults. */
+  reload(): void { /* clear + merge DEFAULT_AGENTS + loadUserAgents() */ }
+
+  resolveAgentConfig(type: string): AgentConfig { /* ... */ }
+  resolveType(name: string): string | undefined { /* ... */ }
+  getAvailableTypes(): string[] { /* ... */ }
+  getAllTypes(): string[] { /* ... */ }
+  getDefaultAgentNames(): string[] { /* ... */ }
+  getUserAgentNames(): string[] { /* ... */ }
+  isValidType(type: string): boolean { /* ... */ }
+  getToolNamesForType(type: string): string[] { /* ... */ }
+
+  static readonly DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as const;
+}
+```
+
+The constructor accepts a `loadUserAgents` callback (typically `() => loadCustomAgents(process.cwd())`).
+This keeps `process.cwd()` at the edge (in `index.ts`) and makes tests trivial — they pass `() => new Map()` or a fixture.
+
+### What stays as free functions
+
+- **`BUILTIN_TOOL_NAMES`** — constant array, no Map dependency.
+  Stays as a module-level export in `agent-types.ts`.
+- **`getMemoryToolNames` / `getReadOnlyMemoryToolNames`** — pure functions over constant arrays, no Map access.
+  Stay as module-level exports.
+
+### Narrow interface for `session-config.ts`
+
+```typescript
+/** Narrow registry interface for session-config (ISP). */
+export interface AgentConfigLookup {
+  resolveAgentConfig(type: string): AgentConfig;
+  getToolNamesForType(type: string): string[];
+}
+```
+
+`assembleSessionConfig` gains a `registry: AgentConfigLookup` parameter.
+Tests construct a plain object satisfying this interface — no class instantiation needed.
+
+### Threading through the call chain
+
+`session-config.ts` ← called by `agent-runner.ts` ← called by `AgentManager`:
+
+1. `assembleSessionConfig(type, ctx, options, env, registry)` — new param.
+2. `RunOptions` gains `registry: AgentConfigLookup`.
+3. `AgentManagerOptions` gains `registry: AgentTypeRegistry`.
+4. `AgentManager` stores the registry and passes it to the runner via `RunOptions`.
+
+### Replacing `reloadCustomAgents` callback
+
+Before:
+
+```typescript
+// index.ts
+const reloadCustomAgents = () => {
+  const userAgents = loadCustomAgents(process.cwd());
+  registerAgents(userAgents);
+};
+
+// AgentToolDeps / AgentMenuDeps
+reloadCustomAgents: () => void;
+```
+
+After:
+
+```typescript
+// index.ts
+const registry = new AgentTypeRegistry(() => loadCustomAgents(process.cwd()));
+
+// AgentToolDeps / AgentMenuDeps
+registry: AgentTypeRegistry;
+
+// Callers use:
+deps.registry.reload();
+```
+
+### Display helpers (`getDisplayName`, `getPromptModeLabel`)
+
+These functions in `agent-widget.ts` call `resolveAgentConfig(type)`.
+After the extraction, they accept the registry (or a `resolveAgentConfig` callback) as a parameter.
+The `AgentWidget` constructor gains a `registry` parameter and passes it to these helpers internally.
+External callers (`conversation-viewer.ts`, `get-result-tool.ts`, etc.) pass the registry they already hold via their deps.
+
+## Module-Level Changes
+
+### New
+
+No new files.
+
+### Modified
+
+1. **`src/agent-types.ts`**
+   - Add `AgentTypeRegistry` class with all instance methods.
+   - Add `AgentConfigLookup` interface.
+   - Keep free functions temporarily (delegation shim during migration).
+   - Final step: remove free functions, module-scoped `agents` Map, and `registerAgents`.
+
+2. **`src/types.ts`**
+   - Remove `DEFAULT_AGENT_NAMES` constant (moved to `AgentTypeRegistry.DEFAULT_AGENT_NAMES`).
+
+3. **`src/session-config.ts`**
+   - `assembleSessionConfig` gains a `registry: AgentConfigLookup` parameter.
+   - Remove imports of `resolveAgentConfig`, `getToolNamesForType` from `agent-types.ts`.
+
+4. **`src/agent-runner.ts`**
+   - `RunOptions` gains `registry: AgentConfigLookup`.
+   - `runAgent` passes `options.registry` to `assembleSessionConfig`.
+
+5. **`src/agent-manager.ts`**
+   - `AgentManagerOptions` gains `registry: AgentTypeRegistry`.
+   - `AgentManager` stores `this.registry` and passes it into `RunOptions` when calling `runner.run`.
+
+6. **`src/tools/agent-tool.ts`**
+   - `AgentToolDeps`: add `registry: AgentTypeRegistry`, remove `reloadCustomAgents`.
+   - Replace `resolveType(...)` / `resolveAgentConfig(...)` imports with `deps.registry.resolveType(...)` / `deps.registry.resolveAgentConfig(...)`.
+   - Replace `deps.reloadCustomAgents()` with `deps.registry.reload()`.
+
+7. **`src/ui/agent-menu.ts`**
+   - `AgentMenuDeps`: add `registry: AgentTypeRegistry`, remove `reloadCustomAgents`.
+   - Replace `getAllTypes()`/`resolveAgentConfig()`/`resolveType()` imports with `deps.registry.*` calls.
+   - `BUILTIN_TOOL_NAMES` import stays (it is a constant, not a method).
+   - Replace `deps.reloadCustomAgents()` with `deps.registry.reload()`.
+
+8. **`src/ui/agent-widget.ts`**
+   - `AgentWidget` constructor gains a `registry: AgentTypeRegistry` (or narrow interface) parameter.
+   - `getDisplayName(type, registry)` / `getPromptModeLabel(type, registry)` gain a registry parameter.
+   - Internal render methods use `this.registry`.
+
+9. **`src/ui/conversation-viewer.ts`**
+   - `ConversationViewer` constructor gains a registry parameter.
+   - Passes it to `getDisplayName` / `getPromptModeLabel` calls.
+
+10. **`src/tools/get-result-tool.ts`**
+    - `GetResultToolDeps` (or equivalent) gains registry.
+    - Passes it to `getDisplayName` calls.
+
+11. **`src/index.ts`**
+    - Construct `AgentTypeRegistry` with `() => loadCustomAgents(process.cwd())`.
+    - Pass registry to `AgentManager`, agent-tool deps, menu deps, widget, get-result-tool deps.
+    - Remove `reloadCustomAgents` closure.
+    - Remove free-function imports (`registerAgents`, `getDefaultAgentNames`, `getUserAgentNames`, `getAvailableTypes`, `resolveAgentConfig`).
+    - Use `registry.*` methods directly for `buildTypeListText`.
+
+### Removed
+
+- Free functions from `agent-types.ts`: `registerAgents`, `resolveType`, `resolveAgentConfig`, `getAvailableTypes`, `getAllTypes`, `getDefaultAgentNames`, `getUserAgentNames`, `isValidType`, `getToolNamesForType` (final cleanup step).
+- Module-scoped `agents` Map and `resolveKey` helper.
+- `DEFAULT_AGENT_NAMES` from `types.ts`.
+- `reloadCustomAgents` field from `AgentToolDeps` and `AgentMenuDeps`.
+
+## Test Impact Analysis
+
+### New tests enabled
+
+- **Isolation without module resets:** Each test creates its own `AgentTypeRegistry` with a fixture callback, eliminating cross-test state leakage and the `registerAgents(new Map())` ceremony.
+- **Reload behavior:** Tests can verify `registry.reload()` picks up new agents without touching module state.
+
+### Existing tests that become redundant
+
+- The existing free-function tests in `agent-types.test.ts` become redundant once the class tests cover the same behavior.
+  They can be removed in the final cleanup step.
+
+### Existing tests that must stay
+
+- `session-config.test.ts` — tests `assembleSessionConfig` behavior; mock setup changes from `vi.mock("agent-types.js")` to passing a mock `AgentConfigLookup` object.
+- `agent-runner.test.ts`, `agent-runner-extension-tools.test.ts` — test runner behavior; mock setup changes from `vi.mock("agent-types.js")` to providing mock registry in `RunOptions`.
+- `tools/agent-tool.test.ts` — tests tool handler; deps mock changes from `reloadCustomAgents: vi.fn()` to `registry: mockRegistry`.
+- `ui/agent-menu.test.ts` — tests menu handler; deps mock changes similarly.
+- `agent-manager.test.ts` — must add a mock registry to constructor options.
+
+## TDD Order
+
+1. **Create `AgentTypeRegistry` class** — Add class to `agent-types.ts` alongside existing free functions.
+   Add `AgentConfigLookup` interface.
+   Test all methods in a new `describe('AgentTypeRegistry')` block in `agent-types.test.ts`: construction, `reload()`, `resolveAgentConfig`, `resolveType`, `getAvailableTypes`, `getAllTypes`, `getDefaultAgentNames`, `getUserAgentNames`, `isValidType`, `getToolNamesForType`.
+   - Test surface: `agent-types.test.ts` — new describe block
+   - Commit: `feat(pi-subagents): add AgentTypeRegistry class (#108)`
+
+2. **Inject through the config-assembly chain** — `assembleSessionConfig` gains `registry: AgentConfigLookup` param.
+   `RunOptions` gains `registry: AgentConfigLookup`.
+   `AgentManagerOptions` gains `registry: AgentTypeRegistry`.
+   Construct registry in `index.ts` and pass through `AgentManager` → `runAgent` → `assembleSessionConfig`.
+   Update `session-config.test.ts` (replace `vi.mock("agent-types.js")` with mock `AgentConfigLookup` object), `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` (provide mock registry in `RunOptions`, remove `vi.mock`), `agent-manager.test.ts` (add registry to constructor options).
+   - Test surface: `session-config.test.ts`, `agent-runner.test.ts`, `agent-runner-extension-tools.test.ts`, `agent-manager.test.ts`
+   - Commit: `refactor(pi-subagents): inject registry through config-assembly chain (#108)`
+
+3. **Inject into agent tool** — Add `registry: AgentTypeRegistry` to `AgentToolDeps`, remove `reloadCustomAgents`.
+   Replace `resolveType` / `resolveAgentConfig` module imports with `deps.registry.*` calls.
+   Replace `deps.reloadCustomAgents()` with `deps.registry.reload()`.
+   Update `index.ts` agent-tool deps and `tools/agent-tool.test.ts`.
+   - Test surface: `tools/agent-tool.test.ts`
+   - Commit: `refactor(pi-subagents): inject registry into agent tool (#108)`
+
+4. **Inject into agent menu** — Add `registry: AgentTypeRegistry` to `AgentMenuDeps`, remove `reloadCustomAgents`.
+   Replace `getAllTypes` / `resolveAgentConfig` / `resolveType` module imports with `deps.registry.*` calls.
+   Replace `deps.reloadCustomAgents()` with `deps.registry.reload()`.
+   Update `index.ts` menu deps and `ui/agent-menu.test.ts`.
+   - Test surface: `ui/agent-menu.test.ts`
+   - Commit: `refactor(pi-subagents): inject registry into agent menu (#108)`
+
+5. **Inject into agent widget and display helpers** — `AgentWidget` constructor gains `registry`.
+   `getDisplayName(type, registry)` and `getPromptModeLabel(type, registry)` gain registry parameters.
+   `ConversationViewer` constructor gains registry.
+   `GetResultToolDeps` gains registry for `getDisplayName` calls.
+   Update `index.ts` wiring, `agent-widget.test.ts`, and any test files that call these helpers.
+   - Test surface: `agent-widget.test.ts`, related callers
+   - Commit: `refactor(pi-subagents): inject registry into agent widget (#108)`
+
+6. **Move `DEFAULT_AGENT_NAMES` to registry** — Add static `DEFAULT_AGENT_NAMES` property on `AgentTypeRegistry`.
+   Remove the constant from `types.ts`.
+   Grep confirms no import consumers exist — the constant is defined but unused.
+   - Test surface: `agent-types.test.ts` — add assertion for static property
+   - Commit: `refactor(pi-subagents): move DEFAULT_AGENT_NAMES to registry (#108)`
+
+7. **Remove free-function exports** — Delete `registerAgents`, `resolveType`, `resolveAgentConfig`, `getAvailableTypes`, `getAllTypes`, `getDefaultAgentNames`, `getUserAgentNames`, `isValidType`, `getToolNamesForType`, the module-scoped `agents` Map, and `resolveKey` helper from `agent-types.ts`.
+   Remove the free-function tests from `agent-types.test.ts` (now covered by class tests).
+   Remove any remaining free-function imports from `index.ts`.
+   Verify with `pnpm run check` that no dangling references remain.
+   - Test surface: `agent-types.test.ts` — remove old describe block
+   - Commit: `refactor(pi-subagents): remove free-function exports from agent-types (#108)`
+
+## Risks and Mitigations
+
+| Risk                                                                                          | Impact                                         | Mitigation                                                                                   |
+| --------------------------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Large blast radius — 11 source files, 8 test files                                            | Merge conflicts if other PRs land concurrently | Lift-and-shift: free functions keep working until final removal; each step is a valid commit |
+| `vi.mock("agent-types.js")` removal in runner tests changes behavior                          | Tests may expose latent bugs in session-config | Mock `AgentConfigLookup` with the same values the current `vi.mock` provides                 |
+| Display helpers (`getDisplayName`, `getPromptModeLabel`) thread registry through many callers | Signature churn in UI layer                    | These callers already have a deps bag or constructor params — registry fits naturally        |
+| `agent-types.test.ts` (333 lines) needs migration from free-function tests to class tests     | Large test rewrite in step 7                   | Step 1 creates class tests first; step 7 only deletes the now-redundant free-function tests  |
+| `AgentRunner` interface change (`RunOptions` gains `registry`)                                | Breaks callers that construct `RunOptions`     | Only `agent-manager.ts` constructs `RunOptions`; single-site change                          |
+
+## Open Questions
+
+- **`getDisplayName` / `getPromptModeLabel` placement:** These are thin display helpers that wrap `resolveAgentConfig`.
+  The plan proposes adding a registry parameter.
+  An alternative is to make them methods on the registry itself (e.g., `registry.getDisplayName(type)`), trading purity for convenience.
+  Decide during implementation based on how natural the call sites feel.

package/docs/plans/0109-extract-settings-manager.md

@@ -0,0 +1,276 @@
+---
+issue: 109
+issue_title: "refactor(pi-subagents): extract SettingsManager class"
+---
+
+# Extract SettingsManager class
+
+## Problem Statement
+
+The settings read/write/persist cycle is spread across free functions in `settings.ts` (`loadSettings`, `saveSettings`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged`), a `SettingsAppliers` callback interface, and 6 settings-related fields in `AgentMenuDeps`.
+The in-memory values live on two different objects (`SubagentRuntime` for `defaultMaxTurns`/`graceTurns`, `AgentManager` for `maxConcurrent`).
+This is mutable state plus the methods that read and write it — a class waiting to happen.
+
+## Goals
+
+- Encapsulate the settings concern into a single testable `SettingsManager` class.
+- Own all three in-memory settings values (`defaultMaxTurns`, `graceTurns`, `maxConcurrent`).
+- Absorb the `SettingsAppliers` interface and the composite functions `applyAndEmitLoaded`, `saveAndEmitChanged`.
+- Collapse the 6 settings-related fields in `AgentMenuDeps` to a single `settings` collaborator (13 → 8 fields).
+- Replace `getDefaultMaxTurns` in `AgentToolDeps` with a narrow settings accessor.
+- Move `maxConcurrent` ownership from `AgentManager` to `SettingsManager`; `AgentManager` reads via injected function.
+- Keep pure helpers (`sanitize`, `loadSettings`, `saveSettings`, `persistToastFor`) as private/internal implementation details.
+- This is a non-breaking refactoring change — no public API surface changes.
+
+## Non-Goals
+
+- Changing the persistence format (`subagents.json`) or the global-vs-project merge strategy.
+- Extracting `AgentActivityTracker` (#110) — that is the next step in Phase 7.
+- Changing the `SubagentsService` public API (`service.ts`).
+- Touching `RunConfig` — it stays as-is; `SettingsManager` naturally satisfies it.
+
+## Background
+
+### Current module map
+
+| Module                | Settings concern                                                                                                                                                                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `settings.ts`         | Free functions: `loadSettings`, `saveSettings`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged`, `persistToastFor`. Types: `SubagentsSettings`, `SettingsAppliers`, `SettingsEmit`.                         |
+| `runtime.ts`          | `SubagentRuntime.defaultMaxTurns` and `.graceTurns` — mutable fields read by `AgentManager` via `getRunConfig`.                                                                                                         |
+| `agent-manager.ts`    | `private maxConcurrent` — used for queue decisions (`spawn`, `drainQueue`). Exposed via `get/setMaxConcurrent`.                                                                                                         |
+| `index.ts`            | Wires callbacks: constructs `SettingsAppliers` closures, calls `applyAndEmitLoaded` at startup, builds 6 callback fields for `AgentMenuDeps`.                                                                           |
+| `ui/agent-menu.ts`    | `AgentMenuDeps` has 6 settings fields: `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns`, `snapshotSettings`, `saveSettings`. `AgentMenuManager` has `getMaxConcurrent`, `setMaxConcurrent`. |
+| `tools/agent-tool.ts` | `AgentToolDeps.getDefaultMaxTurns` — reads the runtime default for the Agent tool.                                                                                                                                      |
+
+### Architecture reference
+
+Phase 7, Step A2 in `docs/architecture/architecture.md`.
+Predecessor A1 (`AgentTypeRegistry`, #108) is complete.
+
+### Applicable constraints (from AGENTS.md / code-design)
+
+- One concern per file — the class consolidates what is currently scattered.
+- Prefer explicit configuration over hidden behavior.
+- Dependency inversion — consumers accept narrow interfaces, not the concrete class.
+- No output arguments — the current `SettingsAppliers` callback pattern writes into external state; the class owns the state directly.
+- ES2024 target; pnpm only.
+
+## Design Overview
+
+### SettingsManager class
+
+```typescript
+export class SettingsManager {
+  // Private fields with built-in defaults
+  private _defaultMaxTurns: number | undefined = undefined;
+  private _graceTurns: number = 5;
+  private _maxConcurrent: number = 4; // DEFAULT_MAX_CONCURRENT
+
+  private readonly emit: SettingsEmit;
+  private readonly cwd: string;
+
+  constructor(deps: { emit: SettingsEmit; cwd: string });
+
+  // ── Property accessors with normalization ──
+  get defaultMaxTurns(): number | undefined;
+  set defaultMaxTurns(n: number | undefined);  // 0 or undefined → undefined; else max(1, n)
+
+  get graceTurns(): number;
+  set graceTurns(n: number);                    // max(1, n)
+
+  get maxConcurrent(): number;
+  set maxConcurrent(n: number);                 // max(1, n)
+
+  // ── Lifecycle methods ──
+
+  /** Load merged settings (global + project), apply to in-memory, emit settings_loaded. */
+  load(): SubagentsSettings;
+
+  /** Snapshot current values for persistence (defaultMaxTurns uses 0 for unlimited). */
+  snapshot(): { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number };
+
+  /** Persist snapshot, emit settings_changed, return toast. */
+  saveAndNotify(successMsg: string): { message: string; level: "info" | "warning" };
+}
+```
+
+The setter for `defaultMaxTurns` inlines the `normalizeMaxTurns` logic (`0 → undefined`, else `Math.max(1, n)`) to avoid a new dependency from `settings.ts` → `agent-runner.ts`.
+The `normalizeMaxTurns` export in `agent-runner.ts` stays for per-invocation normalization in the Agent tool.
+
+### maxConcurrent ownership transfer
+
+`AgentManager` currently owns `maxConcurrent` and calls `this.drainQueue()` in `setMaxConcurrent`.
+After the change:
+
+1. `SettingsManager` owns the value.
+2. `AgentManager` accepts a `getMaxConcurrent: () => number` function (injected via `AgentManagerOptions`).
+   All internal reads (`spawn` queue check, `drainQueue` loop) use `this.getMaxConcurrent()` instead of `this.maxConcurrent`.
+3. `AgentManager.setMaxConcurrent(n)` is replaced with `notifyConcurrencyChanged()` — it only drains the queue; the value has already been set on `SettingsManager` by the caller.
+4. `AgentMenuManager` loses `getMaxConcurrent` and `setMaxConcurrent`; gains `notifyConcurrencyChanged`.
+   The menu reads `settings.maxConcurrent` directly for display.
+
+### Consumer interface narrowing
+
+Each consumer gets the narrowest type it needs:
+
+| Consumer                               | Interface                                                                                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AgentMenuDeps.settings`               | `{ maxConcurrent: number; defaultMaxTurns: number \| undefined; graceTurns: number; saveAndNotify(msg: string): { message: string; level: "info" \| "warning" } }` |
+| `AgentToolDeps.settings`               | `{ readonly defaultMaxTurns: number \| undefined }`                                                                                                                |
+| `AgentManagerOptions.getMaxConcurrent` | `() => number` (function, not object)                                                                                                                              |
+| `AgentManagerOptions.getRunConfig`     | Unchanged — `SettingsManager` satisfies `RunConfig` structurally.                                                                                                  |
+
+### RunConfig compatibility
+
+`SettingsManager` has `defaultMaxTurns` and `graceTurns` as readable properties, so it structurally satisfies the existing `RunConfig` interface.
+In `index.ts`, the `getRunConfig` option becomes `() => settings` (returning the `SettingsManager` instance directly).
+
+### SubagentRuntime cleanup
+
+`SubagentRuntime.defaultMaxTurns` and `.graceTurns` are removed.
+These fields exist solely for settings; after the extraction, `SubagentRuntime` only retains session state and widget delegation.
+
+## Module-Level Changes
+
+### `src/settings.ts`
+
+- **Add** `SettingsManager` class (constructor, 3 property accessors, `load`, `snapshot`, `saveAndNotify`).
+- **Keep** `SubagentsSettings`, `SettingsEmit`, `loadSettings`, `saveSettings`, `sanitize`, `persistToastFor` as internal helpers (some may become unexported).
+- **Remove** `SettingsAppliers` interface.
+- **Remove** `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` functions.
+
+### `src/runtime.ts`
+
+- **Remove** `defaultMaxTurns` and `graceTurns` fields from `SubagentRuntime`.
+- **Remove** `RunConfig` interface (no longer needed — consumers read from `SettingsManager` directly).
+
+### `src/agent-manager.ts`
+
+- **Change** `AgentManagerOptions`: remove `maxConcurrent?: number`; add `getMaxConcurrent?: () => number`.
+- **Change** constructor: store `getMaxConcurrent` function instead of a value.
+- **Replace** `private maxConcurrent: number` with `private readonly getMaxConcurrent: () => number`.
+- **Replace** `setMaxConcurrent(n)` with `notifyConcurrencyChanged()` (public, just calls `drainQueue()`).
+- **Keep** `getRunConfig` — wiring changes in `index.ts` to point at settings.
+
+### `src/ui/agent-menu.ts`
+
+- **Remove** from `AgentMenuDeps`: `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns`, `snapshotSettings`, `saveSettings`.
+- **Add** to `AgentMenuDeps`: `settings` with the narrow inline interface.
+- **Remove** from `AgentMenuManager`: `getMaxConcurrent`, `setMaxConcurrent`.
+- **Add** to `AgentMenuManager`: `notifyConcurrencyChanged: () => void`.
+- **Update** `showSettings`: read from `deps.settings`, write to `deps.settings`, call `deps.manager.notifyConcurrencyChanged()` after concurrency change.
+- **Update** `notifyApplied`: call `deps.settings.saveAndNotify(msg)`.
+
+### `src/tools/agent-tool.ts`
+
+- **Remove** `getDefaultMaxTurns` from `AgentToolDeps`.
+- **Add** `settings: { readonly defaultMaxTurns: number | undefined }` to `AgentToolDeps`.
+- **Update** usage: `deps.getDefaultMaxTurns()` → `deps.settings.defaultMaxTurns`.
+
+### `src/index.ts`
+
+- **Create** `SettingsManager` before `AgentManager`; call `.load()`.
+- **Pass** `getMaxConcurrent: () => settings.maxConcurrent` to `AgentManager`.
+- **Pass** `getRunConfig: () => settings` to `AgentManager`.
+- **Pass** `settings` to `AgentMenuDeps` and `AgentToolDeps`.
+- **Remove** the ad-hoc `applyAndEmitLoaded` call and the 6 callback fields.
+- **Remove** `runtime.defaultMaxTurns` and `runtime.graceTurns` references.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+- **Integrated settings lifecycle**: construct → `load()` → mutate → `saveAndNotify()` → verify snapshot and events, all on a single object.
+  Previously impossible because state was scattered across free functions, callbacks, and two separate objects.
+- **Normalization in setters**: direct tests for `set defaultMaxTurns(0) → undefined`, `set graceTurns(0) → 1`, `set maxConcurrent(0) → 1`.
+  Previously tested only indirectly through `applySettings` + callback mocks.
+- **Snapshot consistency**: verify that `snapshot()` reflects the current in-memory state after mutations.
+
+### Existing tests that become redundant
+
+- `applySettings` tests — the SettingsAppliers callback pattern is removed; normalization logic moves into the class setters.
+- `applyAndEmitLoaded` tests — absorbed into `SettingsManager.load()` tests.
+- `saveAndEmitChanged` tests — absorbed into `SettingsManager.saveAndNotify()` tests.
+
+### Existing tests that must stay
+
+- All `loadSettings` / `saveSettings` / sanitizer tests — these test the I/O + validation layer, which remains as internal helpers.
+- `persistToastFor` tests — pure function, still used internally by `saveAndNotify`.
+- `agent-menu.test.ts` settings tests — still needed; mock shape changes from 6 fields to a settings object.
+- `agent-tool.test.ts` — mock shape changes from `getDefaultMaxTurns` function to `settings` object.
+- `agent-manager.test.ts` — mock shape changes from `maxConcurrent` number to `getMaxConcurrent` function.
+
+## TDD Order
+
+### Cycle 1: SettingsManager — constructor, defaults, get/set normalization
+
+1. Red: test constructor produces correct defaults (`defaultMaxTurns: undefined`, `graceTurns: 5`, `maxConcurrent: 4`).
+   Test setter normalization: `defaultMaxTurns = 0 → undefined`, `graceTurns = 0 → 1`, `maxConcurrent = 0 → 1`, `defaultMaxTurns = 10 → 10`.
+2. Green: implement `SettingsManager` class with private fields, constructor, and property accessors.
+3. Commit: `feat: add SettingsManager class with get/set normalization`
+
+### Cycle 2: SettingsManager — load, snapshot, saveAndNotify, events
+
+1. Red: test `load()` reads merged settings from disk, applies to in-memory values, emits `subagents:settings_loaded`.
+   Test `snapshot()` returns current values with `defaultMaxTurns ?? 0`.
+   Test `saveAndNotify()` persists to disk, emits `subagents:settings_changed`, returns toast.
+   Test save failure returns warning-level toast.
+2. Green: implement `load()`, `snapshot()`, `saveAndNotify()` using existing `loadSettings`, `saveSettings`, `persistToastFor`.
+3. Commit: `feat: SettingsManager load, save, snapshot, and lifecycle events`
+
+### Cycle 3: Narrow AgentMenuDeps — collapse 6 fields to settings
+
+1. Red: update `makeDeps` in `agent-menu.test.ts` — replace 6 settings fields with a `settings` mock object; replace `getMaxConcurrent`/`setMaxConcurrent` on manager with `notifyConcurrencyChanged`.
+   All existing menu tests fail due to mock shape change.
+2. Green: update `AgentMenuDeps` and `AgentMenuManager` interfaces; update `showSettings` and `notifyApplied` to use `deps.settings`.
+3. Run `pnpm run check` to verify types.
+4. Commit: `refactor: collapse settings fields in AgentMenuDeps to SettingsManager`
+
+### Cycle 4: Narrow AgentToolDeps — replace getDefaultMaxTurns
+
+1. Red: update `makeDeps` in `agent-tool.test.ts` — replace `getDefaultMaxTurns` with `settings: { defaultMaxTurns: undefined }`.
+2. Green: update `AgentToolDeps` interface; update `createAgentTool` to read `deps.settings.defaultMaxTurns`.
+3. Run `pnpm run check`.
+4. Commit: `refactor: replace getDefaultMaxTurns with settings in AgentToolDeps`
+
+### Cycle 5: Move maxConcurrent from AgentManager to SettingsManager
+
+1. Red: update `agent-manager.test.ts` — replace `maxConcurrent` option with `getMaxConcurrent` function; replace `setMaxConcurrent` calls with `notifyConcurrencyChanged`.
+2. Green: update `AgentManagerOptions` (replace `maxConcurrent?: number` with `getMaxConcurrent?: () => number`), update constructor, replace `private maxConcurrent` with `private readonly getMaxConcurrent`, rename `setMaxConcurrent` → `notifyConcurrencyChanged`.
+3. Run `pnpm run check`.
+4. Commit: `refactor: AgentManager reads maxConcurrent from SettingsManager`
+
+### Cycle 6: Wire SettingsManager in index.ts
+
+1. Update `index.ts`: create `SettingsManager` before `AgentManager`; call `.load()`; pass to all consumers; remove `applyAndEmitLoaded` call and ad-hoc callback closures.
+2. Run full test suite.
+3. Commit: `refactor: wire SettingsManager in extension init`
+
+### Cycle 7: Remove SubagentRuntime settings fields
+
+1. Remove `defaultMaxTurns` and `graceTurns` from `SubagentRuntime`.
+2. Remove `RunConfig` interface from `runtime.ts` (import from `settings.ts` if still needed, or inline).
+3. Run `pnpm run check`.
+4. Commit: `refactor: remove settings fields from SubagentRuntime`
+
+### Cycle 8: Remove superseded free functions and types
+
+1. Remove `SettingsAppliers`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` from `settings.ts`.
+2. Remove corresponding test sections from `settings.test.ts`.
+3. Make `loadSettings`, `saveSettings` unexported if no external consumers remain (keep exported if tests import them directly for the sanitizer/IO tests).
+4. Run full test suite.
+5. Commit: `refactor: remove superseded settings free functions and SettingsAppliers`
+
+## Risks and Mitigations
+
+| Risk                                                                    | Mitigation                                                                                                                                                                                                                        |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxConcurrent` ownership transfer breaks queue drain timing            | `notifyConcurrencyChanged()` preserves the drain-on-change behavior; `AgentManager` reads via function on every queue decision, so the value is always current.                                                                   |
+| Large mock updates in agent-menu.test.ts cause merge conflicts          | Lift-and-shift: cycles 1–2 add the new class without touching existing code; cycles 3–5 migrate one consumer at a time.                                                                                                           |
+| `normalizeMaxTurns` logic duplicated between setter and agent-runner.ts | The setter inlines trivial normalization (`0 → undefined`, else `max(1, n)`); `normalizeMaxTurns` stays in `agent-runner.ts` for per-invocation use. Both are simple enough that duplication is cheaper than a shared dependency. |
+| `RunConfig` removal from `runtime.ts` breaks imports                    | Grep all `RunConfig` imports before removing; move the type to `settings.ts` or inline at the use site if needed.                                                                                                                 |
+
+## Open Questions
+
+- Should `loadSettings` and `saveSettings` remain exported (for the standalone sanitizer/IO tests) or become private to the module?
+  Defer until cycle 8 — check whether any test imports them directly.

package/docs/retro/0108-extract-agent-type-registry.md

@@ -0,0 +1,41 @@
+---
+issue: 108
+issue_title: "refactor(pi-subagents): extract AgentTypeRegistry class from module-scoped state"
+---
+
+# Retro: #108 — extract AgentTypeRegistry class
+
+## Final Retrospective (2026-05-21T13:30:00Z)
+
+### Session summary
+
+Planned and implemented the `AgentTypeRegistry` class extraction from module-scoped state in `agent-types.ts`.
+The lift-and-shift approach across 7 TDD steps (9 commits including plan and docs) migrated 11 source files and 11 test files while keeping 574 tests green at every commit.
+The `reloadCustomAgents` callback was removed from `AgentToolDeps` and `AgentMenuDeps`, replaced by `deps.registry.reload()`.
+
+### Observations
+
+#### What went well
+
+- The `AgentConfigLookup` narrow interface (ISP) for `session-config.ts` kept tests simple — plain objects with 2 methods, no class instantiation needed.
+- Using `vi.spyOn` on a real `AgentTypeRegistry` instance in `agent-menu.test.ts` was cleaner than `vi.hoisted` + `vi.fn()` factories: correct types, automatic cleanup via `vi.restoreAllMocks()`.
+- Step 2 (inject through 4-file config-assembly chain) was the riskiest single step but landed cleanly because the `vi.mock("agent-types.js")` stubs were narrowed to only the free functions that `session-config.ts` still imports (`getMemoryToolNames`, `getReadOnlyMemoryToolNames`).
+
+#### What caused friction (agent side)
+
+1. `missing-context` — The plan's "Test files affected" table listed 8 files but missed 3 (`prompts.test.ts`, `tools/get-result-tool.test.ts`, `conversation-viewer.test.ts`) that directly import symbols being removed in step 7.
+   The grep during planning found `prompts.test.ts` as an importer of `registerAgents` but didn't include it in the table.
+   Impact: 3 extra test files needed updating in step 7; caught by the full-suite run, not by surprise in CI.
+
+2. `wrong-abstraction` — First `perl -0777` regex for bulk-updating 16 `ConversationViewer` constructor calls in `conversation-viewer.test.ts` failed because the character class `[^)]+` didn't match the multi-line arguments.
+   A simpler pattern targeting just the `vi.fn(),\n  );` suffix worked on the second try.
+   Impact: added friction but no rework — ~2 minutes.
+
+3. `missing-context` — Type check after step 7 revealed `promptMode: string` vs `"replace" | "append"` narrowing issue in `agent-runner-extension-tools.test.ts`.
+   The `agentConfigMock.current` object had `promptMode: "replace"` which TypeScript widened to `string` when spread into the mock `AgentConfigLookup` return.
+   Impact: one additional edit with a return-type annotation; caught by `pnpm run check` as recommended by the testing skill.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The issue description was clear, the architecture doc had the design already sketched, and no mid-session redirects were needed.

package/package.json

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