@gotgenes/pi-subagents 6.4.0 → 6.6.0

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

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

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/docs/retro/0109-extract-settings-manager.md

@@ -0,0 +1,55 @@
+---
+issue: 109
+issue_title: "refactor(pi-subagents): extract SettingsManager class"
+---
+
+# Retro: #109 — extract SettingsManager class
+
+## Final Retrospective (2026-05-21T17:30:00Z)
+
+### Session summary
+
+Planned and implemented the `SettingsManager` class extraction across 8 TDD cycles plus doc updates.
+The class owns `defaultMaxTurns`, `graceTurns`, and `maxConcurrent` with normalizing property accessors, a `load()` method for merged config, and `saveAndNotify()` for persistence + lifecycle events.
+Six settings-related callback fields in `AgentMenuDeps` collapsed to a single `settings` collaborator (13 → 8 fields), and `SettingsAppliers`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` were removed.
+A follow-up issue (#118) was filed for a LoD/Tell-Don't-Ask violation the user identified in the post-implementation review.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift TDD approach worked cleanly: the new class was built and tested in isolation (cycles 1–2), consumers migrated one at a time (cycles 3–5), wiring consolidated (cycle 6), and old code removed last (cycles 7–8).
+  Each commit left the repo in a valid state.
+- The user's design critique (LoD / Tell-Don't-Ask on `deps.settings.saveAndNotify()` orchestration) was sharp and led to a concrete follow-up issue (#118) with a clear fix.
+  The session handled it well — acknowledged, designed the fix, filed the issue, updated the architecture doc, and stopped without scope-creeping into implementation.
+
+#### What caused friction (agent side)
+
+1. `wrong-abstraction` — The plan did not anticipate that changing `AgentMenuDeps` (cycle 3) would immediately break `index.ts` type-checking.
+   Each interface change in cycles 3, 4, and 5 required a same-commit bridge fix in `index.ts` to keep `pnpm run check` clean.
+   The plan's separation of "migrate consumers" (cycles 3–5) from "wire in index.ts" (cycle 6) was too coarse — interface changes propagate to the call site immediately.
+   Impact: three unplanned bridge edits in `index.ts`, each small but requiring context-switching mid-cycle.
+
+2. `missing-context` — The `sed` command in cycle 5 (`sed -i '' 's/maxConcurrent: 1,/getMaxConcurrent: () => 1,/g'`) missed two call sites where `maxConcurrent: 1` had no trailing comma (end of object literal).
+   A `grep` check after the `sed` would have caught this immediately.
+   Impact: two tests failed unexpectedly; required a follow-up read + manual edit before the cycle could complete.
+
+3. `missing-context` — The Edit tool failed on `runtime.ts` because the file uses `─` (U+2500, BOX DRAWINGS LIGHT HORIZONTAL) in section separators, not `—` (U+2014, EM DASH).
+   The Unicode characters looked identical in the terminal, and the Edit tool's exact-match requirement meant the mismatch was silent until the replacement failed.
+   Impact: three failed Edit attempts before falling back to a Python script for the replacement.
+   This is the same class of issue seen in previous sessions with Unicode characters in source files.
+
+4. `premature-convergence` — The plan designed `SettingsManager` as a data holder with persistence methods but didn't consider whether the menu should orchestrate across `settings` and `manager` or whether `SettingsManager` should own the full consequence chain.
+   The user caught this as a LoD/Tell-Don't-Ask violation in post-implementation review.
+   Impact: no rework (filed as follow-up #118), but the design could have been better from the start if the plan had applied the design-review checklist's LoD check to the proposed `showSettings` interaction pattern.
+
+#### What caused friction (user side)
+
+- The user's LoD critique was well-timed — after implementation was complete, avoiding mid-stream rework.
+  If the critique had surfaced during planning (e.g., by the agent applying the design-review checklist to the proposed consumer interaction pattern), the follow-up issue might have been part of the original scope.
+  This is an opportunity for the planning step to simulate the consumer's call sites before finalizing the design, not just the class interface.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — Added consumer call-site sketch heuristic to the "Design Overview" section: when a new collaborator is introduced, sketch 3–5 lines of consumer pseudocode to verify Tell-Don't-Ask and LoD.
+2. `.pi/skills/testing/SKILL.md` — Added TDD planning rule: when a step changes an interface with a single call site, the step must include updating that call site (type checker enforces co-location).

package/package.json

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

package/src/agent-manager.ts

@@ -32,7 +32,8 @@ export interface AgentManagerOptions {
   worktrees: WorktreeManager;
   exec: ShellExec;
   registry: AgentTypeRegistry;
-  maxConcurrent?: number;
+  /** Injected getter for the concurrency limit — owned by SettingsManager. */
+  getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
   onStart?: OnAgentStart;
   onComplete?: OnAgentComplete;
@@ -84,7 +85,7 @@ export class AgentManager {
   private readonly worktrees: WorktreeManager;
   private readonly exec: ShellExec;
   private readonly registry: AgentTypeRegistry;
-  private maxConcurrent: number;
+  private readonly _getMaxConcurrent: () => number;
   private getRunConfig?: () => RunConfig;
 
   /** Queue of background agents waiting to start. */
@@ -101,23 +102,20 @@ export class AgentManager {
     this.onStart = options.onStart;
     this.onCompact = options.onCompact;
     this.getRunConfig = options.getRunConfig;
-    this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
   }
 
-  /** Update the max concurrent background agents limit. */
-  setMaxConcurrent(n: number) {
-    this.maxConcurrent = Math.max(1, n);
-    // Start queued agents if the new limit allows
+  /**
+   * Drain the concurrency queue after SettingsManager has updated maxConcurrent.
+   * Call this whenever the concurrency limit increases so queued agents can start.
+   */
+  notifyConcurrencyChanged(): void {
     this.drainQueue();
   }
 
-  getMaxConcurrent(): number {
-    return this.maxConcurrent;
-  }
-
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
@@ -144,7 +142,7 @@ export class AgentManager {
     const snapshot = buildParentSnapshot(ctx, options.inheritContext);
     const args: SpawnArgs = { snapshot, type, prompt, options };
 
-    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
       // Queue it — will be started when a running agent completes
       this.queue.push({ id, args });
       return id;
@@ -284,7 +282,7 @@ export class AgentManager {
 
   /** Start queued agents up to the concurrency limit. */
   private drainQueue() {
-    while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+    while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
       if (!record || record.status !== "queued") continue;

package/src/index.ts

@@ -13,7 +13,7 @@
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
@@ -23,7 +23,7 @@ import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
 import { createSubagentsService } from "./service-adapter.js";
-import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
+import { SettingsManager } from "./settings.js";
 import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
@@ -55,6 +55,15 @@ export default function (pi: ExtensionAPI) {
     updateWidget: () => runtime.updateWidget(),
   });
 
+  // Settings: owns all three in-memory values and handles load/save/emit.
+  // onMaxConcurrentChanged is wired after manager is constructed (closure captures by reference).
+  const settings = new SettingsManager({
+    emit: (event, payload) => pi.events.emit(event, payload),
+    cwd: process.cwd(),
+    onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
+  });
+  settings.load();
+
   // Background completion: emit lifecycle event and delegate to notification system
   const manager = new AgentManager({
     runner: { run: runAgent, resume: resumeAgent },
@@ -105,7 +114,8 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
-    getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }),
+    getMaxConcurrent: () => settings.maxConcurrent,
+    getRunConfig: () => settings,
   });
 
   // Typed service published via Symbol.for() for cross-extension access.
@@ -164,18 +174,6 @@ export default function (pi: ExtensionAPI) {
 
   const typeListText = buildTypeListText();
 
-  // Apply persisted settings on startup and emit `subagents:settings_loaded`.
-  // Global + project merged; missing → defaults; corrupt file emits a warning
-  // to stderr and falls back to defaults.
-  applyAndEmitLoaded(
-    {
-      setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
-      setDefaultMaxTurns: (n) => { runtime.defaultMaxTurns = normalizeMaxTurns(n); },
-      setGraceTurns: (n) => { runtime.graceTurns = Math.max(1, n); },
-    },
-    (event, payload) => pi.events.emit(event, payload),
-  );
-
   // ---- Agent tool ----
 
   pi.registerTool(defineTool(createAgentTool({
@@ -184,7 +182,7 @@ export default function (pi: ExtensionAPI) {
       spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
-      getMaxConcurrent: () => manager.getMaxConcurrent(),
+      getMaxConcurrent: () => settings.maxConcurrent,
       listAgents: () => manager.listAgents(),
     },
     widget: {
@@ -199,7 +197,7 @@ export default function (pi: ExtensionAPI) {
     typeListText,
     availableTypesText: registry.getAvailableTypes().join(", "),
     agentDir: getAgentDir(),
-    getDefaultMaxTurns: () => runtime.defaultMaxTurns,
+    settings,
   })));
 
   // ---- get_subagent_result tool ----
@@ -226,8 +224,6 @@ export default function (pi: ExtensionAPI) {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
       spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
-      getMaxConcurrent: () => manager.getMaxConcurrent(),
-      setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
     },
     registry,
     agentActivity: runtime.agentActivity,
@@ -240,24 +236,7 @@ export default function (pi: ExtensionAPI) {
       }
       return getModelLabelFromConfig(cfg.model);
     },
-    snapshotSettings: () => ({
-      maxConcurrent: manager.getMaxConcurrent(),
-      defaultMaxTurns: runtime.defaultMaxTurns ?? 0,
-      graceTurns: runtime.graceTurns,
-    }),
-    getDefaultMaxTurns: () => runtime.defaultMaxTurns,
-    getGraceTurns: () => runtime.graceTurns,
-    setDefaultMaxTurns: (n) => {
-      runtime.defaultMaxTurns = normalizeMaxTurns(n);
-    },
-    setGraceTurns: (n) => {
-      runtime.graceTurns = Math.max(1, n);
-    },
-    saveSettings: (settings, successMsg) => saveAndEmitChanged(
-      settings,
-      successMsg,
-      (event, payload) => pi.events.emit(event, payload),
-    ),
+    settings,
     emitEvent: (name, data) => pi.events.emit(name, data),
     personalAgentsDir: join(getAgentDir(), 'agents'),
     projectAgentsDir: join(process.cwd(), '.pi', 'agents'),

package/src/runtime.ts

@@ -24,12 +24,6 @@ export interface RunConfig {
  * Tests construct a fresh runtime per test for full isolation.
  */
 export class SubagentRuntime {
-  // ── Execution config (was module-scope in agent-runner.ts) ──────────────
-  /** Default max turns for all agents. undefined = unlimited. */
-  defaultMaxTurns: number | undefined = undefined;
-  /** Additional turns allowed after the soft-limit steer message. */
-  graceTurns: number = 5;
-
   // ── Session state (was closure-scoped in index.ts) ───────────────────────
   /** Active Pi session context — set on session_start, cleared on session_shutdown. */
   currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;