@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0116-type-housekeeping.md

@@ -1,351 +0,0 @@
----
-issue: 116
-issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
----
-
-# Type housekeeping and small structural cleanups
-
-## Problem Statement
-
-`types.ts` is a type dumping ground — it collects types that don't have a natural home because the module that should own them didn't exist yet.
-With foundation extractions (#108 registry, `parent-snapshot.ts`, `env.ts`, `notification.ts`) now in place, most of these types have a natural home.
-Several other small housekeeping items share the same "polish" character: a closure-bag factory that is a class in disguise, a positional constructor that creates test friction, and a 22-field `AgentConfig` interface consumed by modules that touch 2–4 of its fields.
-
-## Goals
-
-- Move `NotificationDetails` to `notification.ts`, `ParentSnapshot` to `parent-snapshot.ts`, and `EnvInfo` to `env.ts`.
-- Convert `createNotificationSystem` closure to a `NotificationManager` class.
-- Convert `ConversationViewer` constructor from 7 positional parameters to an options bag.
-- Define narrow `AgentConfig` subset interfaces for consumers that use only a few fields.
-- Leave `types.ts` containing only genuinely cross-cutting types: `SubagentType`, `MemoryScope`, `IsolationMode`, `AgentConfig`, `AgentInvocation`, `ShellExec`, and re-exports (`AgentRecord`, `ThinkingLevel`).
-
-## Non-Goals
-
-- Refactoring `AgentConfig` itself (field additions, removals, renames).
-- Changing the `NotificationDeps` interface shape.
-- Modifying `agent-menu.ts` to use narrow subsets — it legitimately reads most `AgentConfig` fields as a config editor/viewer.
-- Touching `invocation-config.ts` — it already receives `AgentConfig | undefined` and only reads invocation-default fields; narrowing its parameter is a separate concern.
-
-## Background
-
-### Prerequisite status
-
-| Issue | Title                             | Status  |
-| ----- | --------------------------------- | ------- |
-| #108  | Extract `AgentTypeRegistry` class | ✅ Done |
-
-`DEFAULT_AGENT_NAMES` was already moved to `AgentTypeRegistry.DEFAULT_AGENT_NAMES` as part of #108.
-The remaining work from the issue's checklist is type relocations, two structural conversions, and narrow subset interfaces.
-
-### Current `types.ts` exports
-
-| Export                                             | Kind      | Should stay?                    |
-| -------------------------------------------------- | --------- | ------------------------------- |
-| `AgentRecord` (re-export)                          | class     | ✅ Cross-cutting                |
-| `AgentRecordInit`, `AgentRecordStatus` (re-export) | type      | ✅ Cross-cutting                |
-| `ThinkingLevel` (re-export)                        | type      | ✅ Cross-cutting                |
-| `SubagentType`                                     | type      | ✅ Cross-cutting                |
-| `MemoryScope`                                      | type      | ✅ Cross-cutting                |
-| `IsolationMode`                                    | type      | ✅ Cross-cutting                |
-| `AgentConfig`                                      | interface | ✅ Cross-cutting                |
-| `AgentInvocation`                                  | interface | ✅ Cross-cutting                |
-| `ShellExec`                                        | type      | ✅ Cross-cutting                |
-| `NotificationDetails`                              | interface | ❌ Move to `notification.ts`    |
-| `ParentSnapshot`                                   | interface | ❌ Move to `parent-snapshot.ts` |
-| `EnvInfo`                                          | interface | ❌ Move to `env.ts`             |
-
-### `createNotificationSystem` closure analysis
-
-The factory in `notification.ts` shares `pendingNudges` (a `Map`) and timer state across 4 inner functions (`cancelNudge`, `scheduleNudge`, `sendCompletion`, `cleanupCompleted`, `dispose`).
-This is a class in disguise — mutable state + methods that read/write it.
-Converting to a `NotificationManager` class makes the state explicit and lets tests use instance methods directly.
-
-### `ConversationViewer` constructor
-
-The constructor takes 7 positional parameters:
-
-```typescript
-constructor(tui, session, record, activity, theme, done, registry)
-```
-
-Every test must reconstruct all 7 in order.
-An options bag reduces friction and is resilient to new parameters.
-
-### `AgentConfig` field usage by consumer
-
-| Consumer                                                   | Fields used                                                                                  |
-| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `agent-widget.ts` (`getDisplayName`, `getPromptModeLabel`) | `name`, `displayName`, `promptMode`                                                          |
-| `tools/helpers.ts` (`formatAgentList`)                     | `name`, `description`, `model`                                                               |
-| `prompts.ts` (`buildAgentPrompt`)                          | `name`, `promptMode`, `systemPrompt`                                                         |
-| `session-config.ts` (`assembleSessionConfig`)              | `name`, `model`, `thinking`, `maxTurns`, `extensions`, `skills`, `memory`, `disallowedTools` |
-| `agent-menu.ts`                                            | Nearly all fields (config viewer/editor)                                                     |
-
-Natural clusters for narrow interfaces:
-
-- **`AgentIdentity`**: `name`, `displayName`, `description`, `promptMode` — UI display and agent listing.
-- **`AgentPromptConfig`**: `name`, `promptMode`, `systemPrompt` — prompt assembly.
-
-`session-config.ts` uses 8 fields; narrowing it yields limited value vs. complexity.
-`invocation-config.ts` receives `AgentConfig | undefined` and reads invocation-default fields; this is a separate concern.
-
-## Design Overview
-
-### Type relocations
-
-Move each type to its natural home module and re-export from `types.ts` during an interim step.
-After updating all importers to point at the new home, remove the re-export.
-This two-phase approach (move + re-export, then update importers + remove re-export) avoids a big-bang commit.
-
-However, since importers are few (2–4 each) and the types are only used internally, a single step per type is simpler: move the type, update all importers in the same commit.
-
-### `NotificationManager` class
-
-Replace the `createNotificationSystem` factory with a class that owns its state:
-
-```typescript
-export class NotificationManager {
-  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
-
-  constructor(private deps: NotificationDeps) {}
-
-  cancelNudge(key: string): void { /* ... */ }
-  sendCompletion(record: AgentRecord): void { /* ... */ }
-  cleanupCompleted(id: string): void { /* ... */ }
-  dispose(): void { /* ... */ }
-
-  // private helpers
-  private scheduleNudge(key: string, send: () => void, delay?: number): void { /* ... */ }
-  private emitIndividualNudge(record: AgentRecord): void { /* ... */ }
-}
-```
-
-The `NotificationSystem` interface stays as-is — `NotificationManager implements NotificationSystem`.
-The `NotificationDeps` interface is unchanged.
-Callers in `index.ts` switch from `createNotificationSystem(deps)` to `new NotificationManager(deps)`.
-
-Consumer call site (index.ts):
-
-```typescript
-const notifications = new NotificationManager({
-  sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
-  agentActivity: runtime.agentActivity,
-  markFinished: (id) => runtime.markFinished(id),
-  updateWidget: () => runtime.updateWidget(),
-});
-```
-
-### `ConversationViewer` options bag
-
-Replace positional parameters with a named options interface:
-
-```typescript
-export interface ConversationViewerOptions {
-  tui: TUI;
-  session: AgentSession;
-  record: AgentRecord;
-  activity: AgentActivityTracker | undefined;
-  theme: Theme;
-  done: (result: undefined) => void;
-  registry: AgentConfigLookup;
-}
-
-export class ConversationViewer {
-  constructor(private options: ConversationViewerOptions) {
-    // destructure into private fields or use options.field access
-  }
-}
-```
-
-The existing private fields (`tui`, `session`, `record`, etc.) become reads from `this.options.*` or are destructured in the constructor to named private fields.
-The constructor body (session subscription) is unchanged.
-
-### Narrow `AgentConfig` subset interfaces
-
-Define two narrow interfaces in `types.ts` and make `AgentConfig` extend them:
-
-```typescript
-/** UI display and agent listing — name, display name, description, prompt mode. */
-export interface AgentIdentity {
-  name: string;
-  displayName?: string;
-  description: string;
-  promptMode: "replace" | "append";
-}
-
-/** Prompt assembly — name, prompt mode, system prompt. */
-export interface AgentPromptConfig {
-  name: string;
-  promptMode: "replace" | "append";
-  systemPrompt: string;
-}
-
-export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
-  // remaining fields unchanged
-}
-```
-
-Then update consumers to accept the narrow interface:
-
-- `agent-widget.ts`: `getDisplayName(type, registry)` and `getPromptModeLabel(type, registry)` — these go through `AgentConfigLookup.resolveAgentConfig()`, which returns `AgentConfig`.
-  The narrowing applies to the *return type usage*, not the function signature.
-  No change needed here — the function already destructures only `displayName`, `name`, `promptMode`.
-- `tools/helpers.ts`: `formatAgentList` reads `description`, `model` — these are not in `AgentIdentity`.
-  `model` is session-config territory.
-  Leave as-is.
-- `prompts.ts`: `buildAgentPrompt(config: AgentPromptConfig, ...)` — narrow the parameter type.
-- `AgentConfigLookup.resolveAgentConfig()` return type stays `AgentConfig` — the registry always has the full config.
-
-Since `AgentConfig extends AgentIdentity, AgentPromptConfig`, any code passing an `AgentConfig` to a function expecting the narrow type works without casts.
-
-## Module-Level Changes
-
-### Modified files
-
-1. **`src/types.ts`**
-   - Remove `NotificationDetails`, `ParentSnapshot`, `EnvInfo` interface definitions.
-   - Add `AgentIdentity` and `AgentPromptConfig` interfaces.
-   - Make `AgentConfig` extend `AgentIdentity` and `AgentPromptConfig`.
-   - Remove fields from `AgentConfig` body that are now inherited (`name`, `displayName`, `description`, `promptMode`, `systemPrompt`).
-
-2. **`src/notification.ts`**
-   - Add `NotificationDetails` interface (moved from `types.ts`).
-   - Replace `createNotificationSystem` factory with `NotificationManager` class implementing `NotificationSystem`.
-   - Export `NotificationManager` (named export) and keep `NotificationSystem` interface export.
-   - Remove `createNotificationSystem` export.
-
-3. **`src/parent-snapshot.ts`**
-   - Add `ParentSnapshot` interface (moved from `types.ts`).
-
-4. **`src/env.ts`**
-   - Add `EnvInfo` interface (moved from `types.ts`).
-
-5. **`src/prompts.ts`**
-   - Change `config` parameter type from `AgentConfig` to `AgentPromptConfig`.
-   - Update import to use `AgentPromptConfig` from `./types.js`.
-
-6. **`src/index.ts`**
-   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
-   - Replace `createNotificationSystem(deps)` with `new NotificationManager(deps)`.
-   - Update import: `NotificationManager` from `./notification.js`.
-
-7. **`src/renderer.ts`**
-   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
-
-8. **`src/agent-runner.ts`**
-   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
-
-9. **`src/agent-manager.ts`**
-   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
-
-10. **`src/session-config.ts`**
-    - Update `EnvInfo` import from `./types.js` to `./env.js`.
-
-11. **`src/ui/conversation-viewer.ts`**
-    - Define `ConversationViewerOptions` interface.
-    - Replace 7 positional constructor parameters with single `options: ConversationViewerOptions` parameter.
-    - Assign private fields from `options` in constructor body.
-
-### Unchanged files
-
-- `src/agent-types.ts` — `DEFAULT_AGENT_NAMES` already moved in #108.
-- `src/invocation-config.ts` — narrowing is a separate concern.
-- `src/ui/agent-menu.ts` — legitimately uses most `AgentConfig` fields.
-
-### Test files
-
-12. **`test/notification.test.ts`**
-    - Replace `createNotificationSystem(deps)` calls with `new NotificationManager(deps)`.
-    - Update import.
-    - All existing assertions stay — the public API is identical.
-
-13. **`test/conversation-viewer.test.ts`**
-    - Replace positional `new ConversationViewer(tui, session, record, activity, theme, done, registry)` calls with `new ConversationViewer({ tui, session, record, activity, theme, done, registry })`.
-    - All existing assertions stay.
-
-14. **`test/prompts.test.ts`**
-    - Verify existing test fixtures satisfy `AgentPromptConfig` (they should — tests already pass `name`, `promptMode`, `systemPrompt`).
-    - May need to narrow mock type annotations.
-
-15. **Other test files importing relocated types** (`test/parent-snapshot.test.ts`, `test/renderer.test.ts`)
-    - Update import paths if they import directly from `types.ts` (most import from the source module already).
-
-## Test Impact Analysis
-
-1. **New unit tests enabled:**
-   - `NotificationManager` as a class can be tested with standard `new` + method calls — no factory indirection.
-     However, the existing factory tests are already clean and simply switch to `new NotificationManager(deps)`.
-     No fundamentally new test capabilities.
-
-2. **Existing tests that simplify:**
-   - `conversation-viewer.test.ts` — the options bag makes test construction more readable and resilient to parameter additions.
-     Each test only needs to specify the fields it cares about (with a helper providing defaults).
-   - `prompts.test.ts` — narrower `AgentPromptConfig` parameter means test fixtures can omit 19 irrelevant `AgentConfig` fields.
-
-3. **Existing tests that must stay as-is:**
-   - `notification.test.ts` — all factory tests stay, just switch constructor syntax.
-   - `conversation-viewer.test.ts` — all render and input tests stay, just switch constructor syntax.
-   - `parent-snapshot.test.ts`, `env.test.ts`, `renderer.test.ts` — behavior unchanged.
-
-## TDD Order
-
-1. **Move `NotificationDetails` from `types.ts` to `notification.ts`.**
-   Cut the interface from `types.ts`, paste into `notification.ts`.
-   Update importers: `index.ts`, `renderer.ts` (change import from `./types.js` to `./notification.js`).
-   `notification.ts` already imports from `./types.js` for `AgentRecord` — no circular dependency.
-   Run `pnpm run check`.
-   Commit: `refactor: move NotificationDetails to notification.ts`
-
-2. **Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.**
-   Cut the interface from `types.ts`, paste into `parent-snapshot.ts`.
-   Update importers: `agent-manager.ts`, `agent-runner.ts` (change import from `./types.js` to `./parent-snapshot.js`).
-   Run `pnpm run check`.
-   Commit: `refactor: move ParentSnapshot to parent-snapshot.ts`
-
-3. **Move `EnvInfo` from `types.ts` to `env.ts`.**
-   Cut the interface from `types.ts`, paste into `env.ts`.
-   Update importers: `session-config.ts`, `prompts.ts` (change import from `./types.js` to `./env.js`).
-   `env.ts` already imports `ShellExec` from `./types.js` — no circular dependency.
-   Run `pnpm run check`.
-   Commit: `refactor: move EnvInfo to env.ts`
-
-4. **Convert `createNotificationSystem` to `NotificationManager` class.**
-   Replace the factory with a class implementing `NotificationSystem`.
-   Move `pendingNudges` and timer logic to private instance state.
-   Convert inner functions to methods.
-   Keep `NotificationSystem` interface, `NotificationDeps` interface, and `NUDGE_HOLD_MS` constant unchanged.
-   Remove `createNotificationSystem` export, add `NotificationManager` export.
-   Update `index.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`.
-   Update `test/notification.test.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`, update import.
-   Run `pnpm vitest run test/notification.test.ts`.
-   Commit: `refactor: convert createNotificationSystem to NotificationManager class`
-
-5. **Convert `ConversationViewer` constructor to options bag.**
-   Define `ConversationViewerOptions` interface.
-   Replace 7 positional parameters with `options: ConversationViewerOptions`.
-   Assign private fields from options in constructor body.
-   Update all call sites in `test/conversation-viewer.test.ts` and `src/index.ts` (or wherever `new ConversationViewer(...)` is called).
-   Run `pnpm vitest run test/conversation-viewer.test.ts`.
-   Commit: `refactor: convert ConversationViewer to options bag constructor`
-
-6. **Define narrow `AgentIdentity` and `AgentPromptConfig` interfaces.**
-   Add interfaces to `types.ts`.
-   Make `AgentConfig` extend both; remove inherited fields from `AgentConfig` body.
-   Narrow `prompts.ts` `buildAgentPrompt` parameter from `AgentConfig` to `AgentPromptConfig`.
-   Update `test/prompts.test.ts` type annotations if needed.
-   Run `pnpm run check` and `pnpm vitest run`.
-   Commit: `refactor: define AgentIdentity and AgentPromptConfig subset interfaces`
-
-## Risks and Mitigations
-
-| Risk                                                                                    | Mitigation                                                                                                                                    |
-| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| Moving types breaks import paths in files not caught by grep                            | Run `pnpm run check` (full `tsc --noEmit`) after each type relocation step.                                                                   |
-| `NotificationManager` class changes test mock patterns (e.g., spreading instances)      | Tests already use the factory return as an opaque object — switching to `new` is mechanical. No spread patterns in notification tests.        |
-| `ConversationViewer` options bag breaks all test call sites at once                     | All 314 lines of tests use the same 7-arg pattern. A search-and-replace handles it. The options bag is a single-step change.                  |
-| `AgentConfig extends AgentIdentity, AgentPromptConfig` changes structural compatibility | `extends` is purely additive — existing code passing `AgentConfig` anywhere still works. Narrowed consumers gain type safety, nothing breaks. |
-| `prompts.ts` parameter narrowing breaks callers passing `AgentConfig`                   | `AgentConfig extends AgentPromptConfig`, so all existing call sites are compatible without changes.                                           |
-
-## Open Questions
-
-- Whether to define an `AgentSessionConfig` subset for `session-config.ts` (8 fields) — deferred because the narrowing ratio (8 of 22) yields less clarity benefit than `AgentIdentity` (4 of 22) or `AgentPromptConfig` (3 of 22).

package/docs/plans/0118-settings-manager-apply-methods.md

@@ -1,271 +0,0 @@
----
-issue: 118
-issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
----
-
-# SettingsManager apply methods — eliminate cross-collaborator orchestration
-
-## Problem Statement
-
-`showSettings` in `agent-menu.ts` orchestrates across two collaborators when changing a setting — it mutates `settings` properties directly (output arguments), separately pokes `manager.notifyConcurrencyChanged()`, then calls `settings.saveAndNotify()`.
-The menu knows too much about the consequence chain of a settings change.
-
-This is a Law of Demeter / Tell-Don't-Ask violation: the menu should *tell* settings what the user wants, not coordinate the mechanics of persistence and queue drain.
-
-## Goals
-
-- Add `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` methods to `SettingsManager` that own the full consequence chain: normalize → set in memory → notify interested parties → persist → emit lifecycle event → return toast.
-- Accept an optional `onMaxConcurrentChanged` callback in `SettingsManager` constructor deps, wired to `manager.notifyConcurrencyChanged()` at init.
-- Narrow `AgentMenuSettings` — replace writable property setters and `saveAndNotify` with 3 read-only getters and 3 apply methods.
-- Remove `notifyConcurrencyChanged` from `AgentMenuManager` — the menu no longer needs to know about the manager for settings changes.
-- This is a non-breaking refactoring — no public API surface changes.
-
-## Non-Goals
-
-- Narrowing `AgentToolDeps` or `AgentMenuDeps` further (#114) — that is a separate issue.
-- Changing the persistence format or the global-vs-project merge strategy.
-- Removing `saveAndNotify` from `SettingsManager` — it remains as a public method; the apply methods delegate to it internally.
-- Removing the property setters from `SettingsManager` — they remain for `load()` and direct test use; only the `AgentMenuSettings` interface narrows.
-
-## Background
-
-### Current flow (max concurrency example)
-
-```text
-showSettings (agent-menu.ts)
-  ├── deps.settings.maxConcurrent = n        ← output argument
-  ├── deps.manager.notifyConcurrencyChanged()← cross-collaborator orchestration
-  └── notifyApplied(ctx, message)
-        └── deps.settings.saveAndNotify(msg) ← separate persist + emit call
-```
-
-### Target flow
-
-```text
-showSettings (agent-menu.ts)
-  └── deps.settings.applyMaxConcurrent(n)    ← one call, toast returned
-        ├── this.maxConcurrent = n           ← internal set
-        ├── this.onMaxConcurrentChanged?.()  ← callback to manager
-        └── this.saveAndNotify(message)      ← internal persist + emit
-```
-
-### Module map (affected files only)
-
-| Module                 | Current role                                           | Change                                                        |
-| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
-| `src/settings.ts`      | `SettingsManager` class with setters, `saveAndNotify`  | Add `onMaxConcurrentChanged` callback; add 3 `apply*` methods |
-| `src/ui/agent-menu.ts` | `showSettings` orchestrates across manager + settings  | Simplify to single apply call per setting                     |
-| `src/agent-manager.ts` | `notifyConcurrencyChanged()` public method             | No change — still called via callback                         |
-| `src/index.ts`         | Wires `notifyConcurrencyChanged` on `AgentMenuManager` | Wire `onMaxConcurrentChanged` on settings constructor instead |
-
-### Architecture reference
-
-Follow-up to Phase 7, Step A2 (#109, closed/implemented).
-Sequenced before D2 (#114, open).
-
-### Applicable constraints
-
-- Law of Demeter — eliminate cross-collaborator reach-through (code-design skill).
-- No output arguments — the menu should not write into received deps (code-design skill).
-- Dependency inversion — consumers accept narrow interfaces (code-design skill).
-- One concern per file — `SettingsManager` already owns the concern; this deepens encapsulation.
-
-## Design Overview
-
-### SettingsManager constructor deps change
-
-```typescript
-constructor(deps: {
-  emit: SettingsEmit;
-  cwd: string;
-  onMaxConcurrentChanged?: () => void;  // ← new
-})
-```
-
-The callback is stored as a private field and called from `applyMaxConcurrent` only.
-
-### Apply methods
-
-Each method normalizes the input, sets the in-memory value, calls any interested-party callback, and delegates to `saveAndNotify` for persist + emit + toast:
-
-```typescript
-applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" } {
-  this.maxConcurrent = n;   // setter normalizes (max(1, n))
-  this.onMaxConcurrentChanged?.();
-  return this.saveAndNotify(`Max concurrency set to ${this.maxConcurrent}`);
-}
-
-applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" } {
-  this.defaultMaxTurns = n === 0 ? undefined : n;  // setter normalizes
-  const label = this.defaultMaxTurns == null ? "unlimited" : String(this.defaultMaxTurns);
-  return this.saveAndNotify(`Default max turns set to ${label}`);
-}
-
-applyGraceTurns(n: number): { message: string; level: "info" | "warning" } {
-  this.graceTurns = n;      // setter normalizes (max(1, n))
-  return this.saveAndNotify(`Grace turns set to ${this.graceTurns}`);
-}
-```
-
-The toast message uses the *post-normalization* value (e.g., `max(1, n)`) so the user sees what was actually applied.
-
-### Consumer call-site sketch (agent-menu.ts)
-
-```typescript
-// Max concurrency — before:
-deps.settings.maxConcurrent = n;
-deps.manager.notifyConcurrencyChanged();
-notifyApplied(ctx, `Max concurrency set to ${n}`);
-
-// Max concurrency — after:
-const toast = deps.settings.applyMaxConcurrent(n);
-ctx.ui.notify(toast.message, toast.level);
-```
-
-Three property writes + one cross-collaborator call + one persist call → one method call.
-The menu never touches the manager for settings changes.
-
-### Narrowed AgentMenuSettings interface
-
-```typescript
-export interface AgentMenuSettings {
-  readonly maxConcurrent: number;
-  readonly defaultMaxTurns: number | undefined;
-  readonly graceTurns: number;
-  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" };
-  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" };
-  applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
-}
-```
-
-### Narrowed AgentMenuManager interface
-
-```typescript
-export interface AgentMenuManager {
-  listAgents: () => AgentRecord[];
-  getRecord: (id: string) => AgentRecord | undefined;
-  spawnAndWait: (...) => Promise<AgentRecord>;
-  // notifyConcurrencyChanged removed — settings owns the callback
-}
-```
-
-### index.ts wiring change
-
-```typescript
-// Before:
-const settings = new SettingsManager({ emit, cwd });
-// ... later in menu deps:
-manager: { ..., notifyConcurrencyChanged: () => manager.notifyConcurrencyChanged() },
-
-// After:
-const settings = new SettingsManager({
-  emit,
-  cwd,
-  onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
-});
-// ... menu deps no longer includes notifyConcurrencyChanged
-```
-
-The closure captures `manager` by reference — safe because the callback is never invoked before `manager` is constructed.
-
-## Module-Level Changes
-
-### `src/settings.ts`
-
-- **Add** `onMaxConcurrentChanged?: () => void` to constructor deps.
-- **Add** `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` methods.
-- **Keep** property setters, `saveAndNotify`, `load`, `snapshot` — apply methods delegate to them.
-
-### `src/ui/agent-menu.ts`
-
-- **Change** `AgentMenuSettings`: replace writable properties + `saveAndNotify` with readonly properties + 3 apply methods.
-- **Change** `AgentMenuManager`: remove `notifyConcurrencyChanged`.
-- **Change** `showSettings`: replace 3-step orchestration with single apply call per setting.
-- **Remove** `notifyApplied` helper — no longer needed; each branch calls `ctx.ui.notify(toast.message, toast.level)` directly.
-
-### `src/index.ts`
-
-- **Add** `onMaxConcurrentChanged` to `SettingsManager` constructor call.
-- **Remove** `notifyConcurrencyChanged` from the menu's manager dep.
-
-### `src/agent-manager.ts`
-
-- **No change** — `notifyConcurrencyChanged()` remains as a public method, now called via callback instead of menu.
-
-## Test Impact Analysis
-
-### New unit tests enabled
-
-- **Apply method integration**: construct `SettingsManager` with an `onMaxConcurrentChanged` spy → call `applyMaxConcurrent(n)` → verify the spy was called, value was set, `saveAndNotify` persisted, and the returned toast is correct.
-  Previously impossible because the consequence chain was spread across the menu and two collaborators.
-- **Toast message accuracy**: verify that apply methods use post-normalization values in the toast (e.g., `applyMaxConcurrent(0)` sets to 1 and reports "set to 1", not "set to 0").
-- **Callback not invoked for non-concurrency settings**: verify `onMaxConcurrentChanged` is *not* called when `applyDefaultMaxTurns` or `applyGraceTurns` is used.
-
-### Existing tests that become simpler
-
-- `agent-menu.test.ts` settings tests: currently assert 3 side effects per setting (property mutation, `notifyConcurrencyChanged` call, `saveAndNotify` call).
-  After: assert a single `apply*` call with the correct argument.
-  The mock object shrinks (no writable setters, no `saveAndNotify`).
-
-### Existing tests that must stay
-
-- `settings.test.ts` — `saveAndNotify()` tests stay; the apply methods delegate to it.
-- `settings.test.ts` — property setter normalization tests stay; apply methods delegate to setters.
-- `agent-menu.test.ts` — settings navigation tests stay; only the assertions change.
-- `agent-manager.test.ts` — `notifyConcurrencyChanged` / drain-queue tests stay unchanged.
-
-## TDD Order
-
-### Cycle 1: Add `onMaxConcurrentChanged` callback to SettingsManager constructor
-
-1. Red: test that constructing with `onMaxConcurrentChanged` stores the callback (verified indirectly in cycle 2).
-   Test that constructing without it does not throw.
-2. Green: add optional `onMaxConcurrentChanged` to constructor deps, store as private field.
-3. Commit: `feat: accept onMaxConcurrentChanged callback in SettingsManager constructor`
-
-### Cycle 2: Add `applyMaxConcurrent` method
-
-1. Red: test `applyMaxConcurrent(8)` — sets `maxConcurrent` to 8, calls `onMaxConcurrentChanged` spy, persists, emits event, returns info toast with "Max concurrency set to 8".
-   Test `applyMaxConcurrent(0)` — normalizes to 1, toast says "set to 1".
-   Test without callback — no throw, still persists and returns toast.
-2. Green: implement `applyMaxConcurrent`.
-3. Commit: `feat: add SettingsManager.applyMaxConcurrent method`
-
-### Cycle 3: Add `applyDefaultMaxTurns` and `applyGraceTurns` methods
-
-1. Red: test `applyDefaultMaxTurns(0)` — sets to unlimited, toast says "unlimited".
-   Test `applyDefaultMaxTurns(10)` — sets to 10, toast says "set to 10".
-   Test `applyGraceTurns(3)` — sets to 3, toast says "set to 3".
-   Test that neither calls `onMaxConcurrentChanged`.
-2. Green: implement both methods.
-3. Commit: `feat: add SettingsManager.applyDefaultMaxTurns and applyGraceTurns methods`
-
-### Cycle 4: Narrow `AgentMenuSettings` and `AgentMenuManager`, simplify `showSettings`
-
-1. Red: update `makeDeps` in `agent-menu.test.ts` — replace writable settings properties + `saveAndNotify` with readonly properties + 3 `apply*` mocks; remove `notifyConcurrencyChanged` from manager mock.
-   Update assertions: `expect(deps.settings.applyMaxConcurrent).toHaveBeenCalledWith(8)` instead of checking property + `saveAndNotify` + `notifyConcurrencyChanged`.
-2. Green: update `AgentMenuSettings` interface (readonly getters + apply methods), update `AgentMenuManager` (remove `notifyConcurrencyChanged`), rewrite `showSettings` to use apply methods, remove `notifyApplied` helper.
-3. Run `pnpm run check`.
-4. Commit: `refactor: simplify showSettings to use SettingsManager apply methods`
-
-### Cycle 5: Wire `onMaxConcurrentChanged` in index.ts
-
-1. Update `SettingsManager` constructor in `index.ts` — add `onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged()`.
-2. Remove `notifyConcurrencyChanged` from the menu's manager dep object.
-3. Run full test suite.
-4. Commit: `refactor: wire onMaxConcurrentChanged callback in extension init (#118)`
-
-## Risks and Mitigations
-
-| Risk                                                                                                                               | Mitigation                                                                                                                                                                                    |
-| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Closure ordering: `onMaxConcurrentChanged` references `manager` before it's constructed                                            | The closure captures by reference; `manager` is assigned before any runtime invocation of the callback. Verified by the `index.ts` construction order (`settings` → `manager` → menu wiring). |
-| Toast message drift: apply methods generate messages internally, so changes require updating `SettingsManager` instead of the menu | Each method has exactly one message template; the coupling is intentional — the owner of the setting knows how to describe the change.                                                        |
-| Apply methods duplicate the 3-step pattern (set → callback → save)                                                                 | The duplication is incidental across 3 settings — extracting a shared helper would need a discriminator for the callback, adding complexity for 3 call sites.                                 |
-| `saveAndNotify` remains public but is no longer in `AgentMenuSettings`                                                             | It's still useful for programmatic callers and tests; keeping it public is intentional.                                                                                                       |
-
-## Open Questions
-
-- Should the property setters on `SettingsManager` be demoted to `private` (with only apply methods for external mutation)?
-  Defer — `load()` uses them internally, and narrowing is done via the `AgentMenuSettings` interface.
-  If a future consumer needs direct set access, the setters are there.