@gotgenes/pi-subagents 18.0.0 → 18.0.2

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

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

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