@gotgenes/pi-subagents 6.6.0 → 6.8.0

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

@@ -0,0 +1,40 @@
+---
+issue: 118
+issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
+---
+
+# Retro: #118 — SettingsManager apply methods
+
+## Final Retrospective (2026-05-21T21:00:00Z)
+
+### Session summary
+
+Planned and implemented 3 `apply*` methods on `SettingsManager` (`applyMaxConcurrent`, `applyDefaultMaxTurns`, `applyGraceTurns`) across 5 TDD cycles plus doc updates, released as `pi-subagents-v6.6.0`.
+Each method owns the full consequence chain (normalize → set → callback → persist → emit → return toast), eliminating the LoD/Tell-Don't-Ask violation in `showSettings` that was identified during the #109 retro.
+`notifyConcurrencyChanged` was removed from `AgentMenuManager`; the menu no longer coordinates between settings and the agent manager.
+
+### Observations
+
+#### What went well
+
+- **Retro-driven improvement validated.**
+  Issue #118 was filed during the #109 retro as a LoD/Tell-Don't-Ask follow-up, and the plan-issue prompt's consumer call-site sketch heuristic (added in #109's retro) was already in the plan template.
+  The plan for #118 included concrete before/after call-site sketches that made the design unambiguous — no `ask-user` decision needed.
+- **Interface-then-wiring TDD order worked cleanly.**
+  The #109 retro noted that interface changes propagate to `index.ts` immediately, forcing unplanned bridge edits.
+  This time the plan accounted for it: Cycle 4 committed only menu files (leaving a known `index.ts` type error), and Cycle 5 fixed the wiring in a separate commit.
+  The intermediate type error was contained and expected.
+- **`defaultMaxTurns` branch consolidation.**
+  During Cycle 4, the separate `n === 0` and `n >= 1` branches in `showSettings` were consolidated to a single `n >= 0` check, since `applyDefaultMaxTurns` handles the 0→unlimited mapping internally.
+  This was a minor but correct simplification that emerged naturally from the Tell-Don't-Ask refactor.
+
+#### What caused friction (agent side)
+
+- No material friction.
+  All 5 TDD cycles completed without rework, failed edits, or unexpected test failures.
+  The plan was tight and the issue's "Proposed change" section was unambiguous.
+
+#### What caused friction (user side)
+
+- No material friction observed.
+  The session ran end-to-end (plan → implement → ship → release) without user intervention.

package/package.json

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

package/src/agent-manager.ts

@@ -13,11 +13,13 @@ import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
+import type { ExecutionState } from "./execution-state.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 import type { WorktreeManager } from "./worktree.js";
+import { WorktreeState } from "./worktree-state.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
@@ -92,6 +94,8 @@ export class AgentManager {
   private queue: { id: string; args: SpawnArgs }[] = [];
   /** Number of currently running background agents. */
   private runningBackground = 0;
+  /** Steers buffered for agents whose session hasn’t been created yet. */
+  private pendingSteers = new Map<string, string[]>();
 
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
@@ -116,6 +120,19 @@ export class AgentManager {
     this.drainQueue();
   }
 
+  /**
+   * Buffer a steer message for an agent whose session isn’t ready yet.
+   * Returns false if the agent id is not tracked (already cleaned up or unknown).
+   * Called by steer-tool and service-adapter when record.execution is undefined.
+   */
+  queueSteer(id: string, message: string): boolean {
+    if (!this.agents.has(id)) return false;
+    const steers = this.pendingSteers.get(id) ?? [];
+    steers.push(message);
+    this.pendingSteers.set(id, steers);
+    return true;
+  }
+
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
@@ -173,7 +190,7 @@ export class AgentManager {
           'Initialize git and commit at least once, or omit `isolation`.',
         );
       }
-      record.worktree = wt;
+      record.worktreeState = new WorktreeState(wt);
       worktreeCwd = wt.path;
     }
 
@@ -207,17 +224,18 @@ export class AgentManager {
       signal: record.abortController!.signal,
       registry: this.registry,
       onSessionCreated: (session) => {
-        record.session = session;
         // Capture the session file path early so it's available for display
         // before the run completes (e.g. in background agent status messages).
-        const file = session.sessionManager?.getSessionFile?.();
-        if (file) record.outputFile = file;
+        const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
+        // Set the execution-state collaborator — born complete at session creation.
+        record.execution = { session, outputFile };
         // Flush any steers that arrived before the session was ready
-        if (record.pendingSteers?.length) {
-          for (const msg of record.pendingSteers) {
+        const buffered = this.pendingSteers.get(id);
+        if (buffered?.length) {
+          for (const msg of buffered) {
             session.steer(msg).catch(() => {});
           }
-          record.pendingSteers = undefined;
+          this.pendingSteers.delete(id);
         }
         // Subscribe record observer for stats accumulation
         unsubRecordObserver = subscribeRecordObserver(session, record, {
@@ -232,9 +250,9 @@ export class AgentManager {
 
         // Clean up worktree before transition so the final result includes branch text
         let finalResult = responseText;
-        if (record.worktree) {
-          const wtResult = this.worktrees.cleanup(record.worktree, options.description);
-          record.worktreeResult = wtResult;
+        if (record.worktreeState) {
+          const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
+          record.worktreeState.recordCleanup(wtResult);
           if (wtResult.hasChanges && wtResult.branch) {
             finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
           }
@@ -245,8 +263,8 @@ export class AgentManager {
         else if (steered) record.markSteered(finalResult);
         else record.markCompleted(finalResult);
 
-        record.session = session;
-        if (sessionFile) record.outputFile = sessionFile;
+        // Update execution collaborator with final session/outputFile from runner
+        record.execution = { session, outputFile: sessionFile ?? record.execution?.outputFile };
 
         if (options.isBackground) {
           this.runningBackground--;
@@ -262,10 +280,11 @@ export class AgentManager {
         detach();
 
         // Best-effort worktree cleanup on error
-        if (record.worktree) {
+        if (record.worktreeState) {
           try {
-            const wtResult = this.worktrees.cleanup(record.worktree, options.description);
-            record.worktreeResult = wtResult;
+            const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
+            record.worktreeState.recordCleanup(wtResult);
+
           } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
 
@@ -322,16 +341,17 @@ export class AgentManager {
     signal?: AbortSignal,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id);
-    if (!record?.session) return undefined;
+    const session = record?.execution?.session;
+    if (!session) return undefined;
 
     record.resetForResume(Date.now());
 
-    const unsubResume = subscribeRecordObserver(record.session, record, {
+    const unsubResume = subscribeRecordObserver(session, record, {
       onCompact: (r, info) => this.onCompact?.(r, info),
     });
 
     try {
-      const responseText = await this.runner.resume(record.session, prompt, {
+      const responseText = await this.runner.resume(session, prompt, {
         signal,
       });
       record.markCompleted(responseText);
@@ -373,9 +393,9 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.session?.dispose?.();
-    record.session = undefined;
+    record.execution?.session?.dispose?.();
     this.agents.delete(id);
+    this.pendingSteers.delete(id);
   }
 
   private cleanup() {
@@ -448,7 +468,7 @@ export class AgentManager {
     // Clear queue
     this.queue = [];
     for (const record of this.agents.values()) {
-      record.session?.dispose();
+      record.execution?.session?.dispose();
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)

package/src/agent-record.ts

@@ -5,12 +5,19 @@
  * by the class and exposed via transition methods. External code reads these
  * fields through public properties but cannot write them directly.
  *
- * Non-transition state (session, toolUses, lifetimeUsage, etc.) remains public.
+ * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
+ * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
+ *
+ * Phase-specific collaborators (execution, worktreeState, notification) are attached
+ * after construction as lifecycle information becomes available.
  */
 
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { ExecutionState } from "./execution-state.js";
+import type { NotificationState } from "./notification-state.js";
 import type { AgentInvocation, SubagentType } from "./types.js";
 import type { LifetimeUsage } from "./usage.js";
+import { addUsage } from "./usage.js";
+import type { WorktreeState } from "./worktree-state.js";
 
 export type AgentRecordStatus =
 	| "queued"
@@ -30,19 +37,9 @@ export interface AgentRecordInit {
 	completedAt?: number;
 	result?: string;
 	error?: string;
-	toolUses?: number;
-	lifetimeUsage?: LifetimeUsage;
-	compactionCount?: number;
 	abortController?: AbortController;
 	invocation?: AgentInvocation;
-	session?: AgentSession;
 	promise?: Promise<string>;
-	resultConsumed?: boolean;
-	pendingSteers?: string[];
-	worktree?: { path: string; branch: string };
-	worktreeResult?: { hasChanges: boolean; branch?: string };
-	toolCallId?: string;
-	outputFile?: string;
 }
 
 export class AgentRecord {
@@ -68,19 +65,25 @@ export class AgentRecord {
 	private _completedAt?: number;
 	get completedAt(): number | undefined { return this._completedAt; }
 
-	// Non-transition mutable state
-	toolUses: number;
-	lifetimeUsage: LifetimeUsage;
-	compactionCount: number;
-	session?: AgentSession;
-	abortController?: AbortController;
+	// Stats — accumulated via mutation methods, readable via getters
+	private _toolUses: number;
+	get toolUses(): number { return this._toolUses; }
+
+	private _lifetimeUsage: LifetimeUsage;
+	get lifetimeUsage(): Readonly<LifetimeUsage> { return this._lifetimeUsage; }
+
+	private _compactionCount: number;
+	get compactionCount(): number { return this._compactionCount; }
+
+	/** AbortController for cancelling this agent. Set at construction; used only by AgentManager. */
+	readonly abortController?: AbortController;
+	/** Promise for the full agent run (including post-processing). Set once by AgentManager. */
 	promise?: Promise<string>;
-	resultConsumed?: boolean;
-	pendingSteers?: string[];
-	worktree?: { path: string; branch: string };
-	worktreeResult?: { hasChanges: boolean; branch?: string };
-	toolCallId?: string;
-	outputFile?: string;
+
+	// Phase-specific collaborators — each born complete when their info becomes available
+	execution?: ExecutionState;
+	worktreeState?: WorktreeState;
+	notification?: NotificationState;
 
 	constructor(init: AgentRecordInit) {
 		this.id = init.id;
@@ -94,18 +97,26 @@ export class AgentRecord {
 		this._startedAt = init.startedAt ?? Date.now();
 		this._completedAt = init.completedAt;
 
-		this.toolUses = init.toolUses ?? 0;
-		this.lifetimeUsage = init.lifetimeUsage ?? { input: 0, output: 0, cacheWrite: 0 };
-		this.compactionCount = init.compactionCount ?? 0;
+		this._toolUses = 0;
+		this._lifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
+		this._compactionCount = 0;
 		this.abortController = init.abortController;
-		this.session = init.session;
 		this.promise = init.promise;
-		this.resultConsumed = init.resultConsumed;
-		this.pendingSteers = init.pendingSteers;
-		this.worktree = init.worktree;
-		this.worktreeResult = init.worktreeResult;
-		this.toolCallId = init.toolCallId;
-		this.outputFile = init.outputFile;
+	}
+
+	/** Increment tool use count. Called by record-observer on tool_execution_end. */
+	incrementToolUses(): void {
+		this._toolUses++;
+	}
+
+	/** Accumulate a usage delta into lifetimeUsage. Called by record-observer on message_end. */
+	addUsage(delta: { input: number; output: number; cacheWrite: number }): void {
+		addUsage(this._lifetimeUsage, delta);
+	}
+
+	/** Increment compaction count. Called by record-observer on compaction_end. */
+	incrementCompactions(): void {
+		this._compactionCount++;
 	}
 
 	/** Transition to running state. Sets status and startedAt. */

package/src/execution-state.ts

@@ -0,0 +1,17 @@
+/**
+ * execution-state.ts — ExecutionState: execution-phase state for a running agent.
+ *
+ * Constructed and attached to AgentRecord when onSessionCreated fires inside startAgent().
+ * Contains the session and output file — the two fields that become known once the
+ * runner creates the session. promise stays as a separate AgentRecord field because
+ * it is set at a different moment (after runner.run() returns).
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+
+export interface ExecutionState {
+	/** The active agent session — available from the moment the session is created. */
+	readonly session: AgentSession;
+	/** Path to the agent's session JSONL file, or undefined if not yet available. */
+	readonly outputFile: string | undefined;
+}

package/src/index.ts

@@ -88,7 +88,7 @@ export default function (pi: ExtensionAPI) {
       });
 
       // Skip notification if result was already consumed via get_subagent_result
-      if (record.resultConsumed) {
+      if (record.notification?.resultConsumed) {
         notifications.cleanupCompleted(record.id);
         return;
       }
@@ -215,6 +215,7 @@ export default function (pi: ExtensionAPI) {
     getRecord: (id) => manager.getRecord(id),
     emitEvent: (name, data) => pi.events.emit(name, data),
     steerAgent: (session, message) => steerAgent(session, message),
+    queueSteer: (id, message) => manager.queueSteer(id, message),
   })));
 
   // ---- /agents interactive menu ----

package/src/notification-state.ts

@@ -0,0 +1,27 @@
+/**
+ * notification-state.ts — NotificationState: notification-scoped tracking per background agent.
+ *
+ * Constructed once when agent-tool assigns the tool call ID (background agents only).
+ * Foreground agents never get a NotificationState — record.notification stays undefined.
+ */
+
+export class NotificationState {
+	/** The tool call ID that spawned this background agent. Used in task-notification XML. */
+	readonly toolCallId: string;
+
+	private _resultConsumed = false;
+
+	constructor(toolCallId: string) {
+		this.toolCallId = toolCallId;
+	}
+
+	/** Whether the parent agent has already consumed this result (suppresses duplicate notifications). */
+	get resultConsumed(): boolean {
+		return this._resultConsumed;
+	}
+
+	/** Mark the result as consumed — suppresses the completion notification. */
+	markConsumed(): void {
+		this._resultConsumed = true;
+	}
+}

package/src/notification.ts

@@ -1,6 +1,6 @@
 import { debugLog } from "./debug.js";
 import type { AgentRecord, NotificationDetails } from "./types.js";
-import type { AgentActivity } from "./ui/agent-widget.js";
+import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 
 // ---- Pure helpers (exported for unit testing) ----
@@ -31,7 +31,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.session);
+  const contextPercent = getSessionContextPercent(record.execution?.session);
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 
@@ -41,11 +41,13 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
       : record.result
     : "No output.";
 
+  const toolCallId = record.notification?.toolCallId;
+  const outputFile = record.execution?.outputFile;
   return [
     "<task-notification>",
     `<task-id>${record.id}</task-id>`,
-    record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
-    record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
+    toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
+    outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
     `<status>${escapeXml(status)}</status>`,
     `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
     `<result>${escapeXml(resultPreview)}</result>`,
@@ -60,7 +62,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
 export function buildNotificationDetails(
   record: AgentRecord,
   resultMaxLen: number,
-  activity?: AgentActivity,
+  activity?: AgentActivityTracker,
 ): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
@@ -73,7 +75,7 @@ export function buildNotificationDetails(
     maxTurns: activity?.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-    outputFile: record.outputFile,
+    outputFile: record.execution?.outputFile,
     error: record.error,
     resultPreview: record.result
       ? record.result.length > resultMaxLen
@@ -113,7 +115,7 @@ export interface NotificationDeps {
     msg: { customType: string; content: string; display: boolean; details?: unknown },
     opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
   ) => void;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   markFinished: (id: string) => void;
   updateWidget: () => void;
 }
@@ -154,10 +156,11 @@ export function createNotificationSystem(deps: NotificationDeps): NotificationSy
   }
 
   function emitIndividualNudge(record: AgentRecord) {
-    if (record.resultConsumed) return;
+    if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
-    const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : "";
+    const outputFile = record.execution?.outputFile;
+    const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
     deps.sendMessage(
       {

package/src/record-observer.ts

@@ -7,7 +7,6 @@
 
 import type { CompactionInfo } from "./agent-manager.js";
 import type { AgentRecord } from "./agent-record.js";
-import { addUsage } from "./usage.js";
 
 /** Narrow session interface — only the subscribe method needed by the observer. */
 interface SubscribableSession {
@@ -22,9 +21,9 @@ export interface RecordObserverOptions {
  * Subscribe to session events and accumulate stats on the agent record.
  *
  * Handles:
- * - `tool_execution_end` → `record.toolUses++`
- * - `message_end` (assistant, with usage) → `addUsage(record.lifetimeUsage, …)`
- * - `compaction_end` (not aborted) → `record.compactionCount++`, call `onCompact`
+ * - `tool_execution_end` → `record.incrementToolUses()`
+ * - `message_end` (assistant, with usage) → `record.addUsage(…)`
+ * - `compaction_end` (not aborted) → `record.incrementCompactions()`, call `onCompact`
  *
  * @returns An unsubscribe function.
  */
@@ -35,13 +34,13 @@ export function subscribeRecordObserver(
 ): () => void {
   return session.subscribe((event: any) => {
     if (event.type === "tool_execution_end") {
-      record.toolUses++;
+      record.incrementToolUses();
     }
 
     if (event.type === "message_end" && event.message?.role === "assistant") {
       const u = event.message.usage;
       if (u) {
-        addUsage(record.lifetimeUsage, {
+        record.addUsage({
           input: u.input ?? 0,
           output: u.output ?? 0,
           cacheWrite: u.cacheWrite ?? 0,
@@ -50,7 +49,7 @@ export function subscribeRecordObserver(
     }
 
     if (event.type === "compaction_end" && !event.aborted && event.result) {
-      record.compactionCount++;
+      record.incrementCompactions();
       options?.onCompact?.(record, {
         reason: event.reason,
         tokensBefore: event.result.tokensBefore,

package/src/runtime.ts

@@ -6,7 +6,8 @@
  * Follows the same pattern as pi-permission-system's ExtensionRuntime.
  */
 
-import type { AgentActivity, AgentWidget, UICtx } from "./ui/agent-widget.js";
+import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
+import type { AgentWidget, UICtx } from "./ui/agent-widget.js";
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -31,7 +32,7 @@ export class SubagentRuntime {
    * Per-agent live activity state shared across the notification system,
    * widget, and tool handlers. The Map itself is never replaced.
    */
-  readonly agentActivity: Map<string, AgentActivity> = new Map();
+  readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
   /**
    * Persistent widget reference. Null until constructed after AgentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.

package/src/service-adapter.ts

@@ -17,6 +17,7 @@ export interface AgentManagerLike {
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
+  queueSteer(id: string, message: string): boolean;
 }
 
 /** Dependencies injected into the adapter factory. */
@@ -85,13 +86,12 @@ export function createSubagentsService(deps: AdapterDeps): SubagentsService {
       if (!record || record.status !== "running") {
         return false;
       }
-      if (!record.session) {
-        // Session not ready yet — queue for delivery once initialized
-        if (!record.pendingSteers) record.pendingSteers = [];
-        record.pendingSteers.push(message);
-        return true;
+      const session = record.execution?.session;
+      if (!session) {
+        // Session not ready yet — queue via manager for delivery once initialized
+        return manager.queueSteer(id, message);
       }
-      await record.session.steer(message);
+      await session.steer(message);
       return true;
     },
 
@@ -124,7 +124,8 @@ export function toSubagentRecord(record: AgentRecord): SubagentRecord {
   if (record.result !== undefined) out.result = record.result;
   if (record.error !== undefined) out.error = record.error;
   if (record.completedAt !== undefined) out.completedAt = record.completedAt;
-  if (record.worktreeResult !== undefined) out.worktreeResult = record.worktreeResult;
+  const worktreeResult = record.worktreeState?.cleanupResult;
+  if (worktreeResult !== undefined) out.worktreeResult = worktreeResult;
 
   return out;
 }