@gotgenes/pi-subagents 16.2.1 → 16.3.0

package/docs/retro/0376-extract-manager-observer.md

@@ -0,0 +1,81 @@
+---
+issue: 376
+issue_title: "Extract the manager observer from index.ts into a class"
+---
+
+# Retro: #376 — Extract the manager observer from index.ts into a class
+
+## Stage: Planning (2026-06-15T00:00:00Z)
+
+### Session summary
+
+Planned Phase 17 Step 5: extracting the inline `SubagentManagerObserver` literal from `index.ts` into a `SubagentEventsObserver` class under `src/observation/`, constructed with narrow `emit` / `appendEntry` / `NotificationSystem` deps.
+The plan is a single red→green→commit extraction (class + tests + `index.ts` wiring in one commit) plus a docs commit marking the step complete.
+Classified as a non-breaking, pure internal extraction with no observable behavior change.
+
+### Observations
+
+- The issue is the operator's own (author `gotgenes` matches the gh user) and the architecture doc already specifies Step 5 precisely, so the `ask-user` gate was skipped.
+- The class + `index.ts` swap must land in one commit: `index.ts` is the sole call site of the literal being replaced, and the new class needs a consumer to satisfy `pnpm fallow dead-code`.
+- Kept `buildEventData` in `notification.ts` (it is tested there) and imported it into the new module — avoids churning `notification.test.ts`.
+- Used `refactor:` for the extraction commit, matching the precedent of Phase 17 Step 4 (#375); `refactor` is hidden from the release-please changelog.
+- Two structural smells were noted as out of scope: the `record.notification?.resultConsumed` Law-of-Demeter chain (track-and-watch) and narrowing `NotificationSystem` to a two-method `CompletionNotifier` per ISP (the issue prescribes passing `NotificationSystem`).
+- Wiring `pi.events.emit` / `pi.appendEntry` as arrow callbacks in `index.ts` avoids the `@typescript-eslint/unbound-method` trap; mirrors the existing `SettingsManager` emit pattern.
+- Step 6 (#377) depends on this step; the plan pins the previously-untested event/notification dispatch invariants so Step 6 cannot regress them.
+
+## Stage: Implementation — TDD (2026-06-15T18:40:00Z)
+
+### Session summary
+
+Completed 2 TDD cycles: (1) extracted `SubagentEventsObserver` into `src/observation/subagent-events-observer.ts`, added 15 tests covering all four observer methods, and updated `src/index.ts` to replace the inline literal — all in one coupled commit; (2) marked Phase 17 Step 5 ✅ Complete in the architecture doc with a Landed note.
+Test delta: 994 → 1009 (+15); file count 63 → 64 test files; `index.ts` 226 → 177 lines.
+Pre-completion reviewer: PASS.
+
+### Observations
+
+- The typed `vi.fn<(channel: string, data: unknown) => void>()` mock triggered `@typescript-eslint/no-unnecessary-type-assertion` on `mock.calls[0]!` indexing — fixed by switching the error-status assertions to `toHaveBeenCalledWith("subagents:failed", expect.anything())` and the success-status assertion to `toHaveBeenCalledWith("subagents:completed", buildEventData(record))`.
+  This eliminated all raw `mock.calls[0]` indexing from the file, which is cleaner.
+- The autoformatter (`pi-autoformat`) ran after writing `index.ts`, so the import block was reflowed; re-reading before further edits would be required in any follow-up session.
+- Architecture doc: Step 4's header was already missing its ✅ Complete marker (it had a Landed note); the reviewer noted this was corrected correctly, not a regression.
+- All five previously-untested observer-behavior invariants are now pinned by tests for the first time.
+
+## Stage: Final Retrospective (2026-06-15T22:55:15Z)
+
+### Session summary
+
+Phase 17 Step 5 ran cleanly end-to-end across planning, TDD, ship, and retro: one `refactor:` extraction commit plus a `docs:` roadmap update, +15 tests, `index.ts` 226 → 177 lines, released as `pi-subagents-v16.2.2`.
+The plan correctly anticipated the class/`index.ts` coupling (one commit) and the `unbound-method` trap (arrow callbacks), so implementation followed the plan with a single minor test-assertion adjustment.
+The pre-completion reviewer (on `claude-sonnet-4-6`) returned PASS and incidentally flagged a stale Step 4 checkmark that was corrected.
+
+### Observations
+
+#### What went well
+
+- The lint feedback loop caught the only defect before it was committed: typed `vi.fn` made `mock.calls[0]!` an unnecessary assertion, surfaced by `pnpm run lint` between green and commit, fixed by switching to `toHaveBeenCalledWith(...)`.
+  No follow-up commit was needed — verification ran incrementally (lint + test before each commit, `fallow dead-code` before push).
+- The `pre-completion-reviewer` subagent earned its dispatch: beyond confirming the deterministic gates, it caught that Phase 17 Step 4's header was missing its `✅ Complete` marker (a prior-session oversight) and validated all six Mermaid diagrams.
+- The plan's pre-work paid off — the coupling note (class + consumer + import removal in one commit to satisfy `fallow`) and the arrow-callback note for `emit`/`appendEntry` meant zero rework at those two known-risk points.
+
+#### What caused friction (agent side)
+
+- `missing-context` (self-identified) — the TDD test was written with `mock.calls[0]!` non-null assertions; typed `vi.fn<(channel: string, data: unknown) => void>()` makes the call tuple non-optional, so `@typescript-eslint/no-unnecessary-type-assertion` fired on every `!`.
+  Impact: ~5 tool calls (turns 1–6) to diagnose and rewrite four assertions to `toHaveBeenCalledWith(...)`; caught by lint before commit, no rework.
+- `missing-context` (self-identified) — the ship stage used `grep -oP` (Perl regex) to extract issue numbers; macOS BSD `grep` has no `-P`.
+  Impact: one wasted tool call (turn 38), self-recovered with `sed` on turn 39.
+
+#### What caused friction (user side)
+
+- None.
+  The single `ask_user` gate (release batching) was the appropriate strategic checkpoint and the user answered "close now"; no mechanical oversight was required.
+
+### Diagnostic details
+
+- **Model-performance correlation** — TDD ran on `claude-sonnet-4-6` (appropriate for judgment + code authoring); the `pre-completion-reviewer` subagent ran on `claude-sonnet-4-6` per its agent frontmatter (appropriate for review).
+  The ship stage ran on `opencode-go/deepseek-v4-flash` — a cheaper model on a mostly-mechanical workflow (git, CI watch, issue close).
+  It handled the one judgment call (release batching) correctly by asking the user and read the release-PR body for sibling bumps, but the `grep -oP` slip is the kind of environment mistake a weaker model is likelier to make; net match was acceptable.
+- **Escalation-delay tracking** — no `rabbit-hole`; the longest single-issue run was the ~5-call `mock.calls[0]!` diagnosis, which was methodical (read → read → edit → lint → test), not thrashing.
+- **Feedback-loop gap analysis** — no gap: `pnpm run lint` and `vitest run` ran before each commit and `fallow dead-code` ran from the repo root before push, exactly as the templates prescribe.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added a § Test assertions bullet: assert mock calls with `toHaveBeenCalledWith(...)` rather than `fn.mock.calls[0]![0]`, since a typed `vi.fn` makes the call tuple non-optional and the `!` trips `@typescript-eslint/no-unnecessary-type-assertion`.

package/docs/retro/0377-split-widget-delegation-from-runtime.md

@@ -0,0 +1,49 @@
+---
+issue: 377
+issue_title: "Split widget delegation out of SubagentRuntime"
+---
+
+# Retro: #377 — Split widget delegation out of SubagentRuntime
+
+## Stage: Planning (2026-06-15T23:16:29Z)
+
+### Session summary
+
+Produced the implementation plan for removing the `widget` field and five relay methods from `SubagentRuntime`.
+Investigation surfaced that the issue's stated approach ("construct the widget before its consumers, pass the handle to `NotificationManager`") is infeasible as written — `NotificationManager` is a transitive *dependency* of the widget, forming a genuine construction cycle (`NotificationManager → widget → manager → observer → NotificationManager`).
+The plan dissolves the cycle instead of relocating its late seam.
+
+### Observations
+
+- **Operator steer #1 (seam placement):** rejected both a setter on the observer and a forward-referenced `let widget` closure, citing "no setters, instantiate ready-to-work, constructor DI" (principle 8).
+  The forward-ref option would also have trip `prefer-const` and reintroduced the exact eslint-disable smell Phase 17 Step 1 deleted.
+- **Operator steer #2 (tidy-first, Kent Beck):** prompted the prep/easy decomposition.
+  The hard, cycle-breaking work (dissolve `NotificationManager`'s widget dependency by giving `AgentWidget` self-seeding of `finishedTurnAge`) lands first as a behavior-preserving commit; the relay-method removal then becomes a mechanical "easy change."
+- **Behavior-preservation argument:** the widget's 80ms timer is always running at a background completion (the agent was active), and linger expiry is turn-based, so seeding ≤80ms later lands in the same turn — rendered outcome is identical.
+  This is the load-bearing claim; the new `agent-widget.test.ts` self-seed test pins it.
+- **Three seam options recorded** in the plan's Design Overview for traceability: late-observer setter (rejected), forward-ref closure (rejected), dissolve (chosen).
+- **Scope guard:** kept foreground-runner's explicit `markFinished` (idempotent) rather than removing it, and deferred the event-subscription widget model to Phase 18.
+  Two open questions logged (single `AgentToolWidget` vs. split deps; redundancy of foreground `markFinished`).
+- **Not breaking / not public:** `runtime.ts` is internal (not in the rolled `service.ts` type bundle), so `verify:public-types` is not required.
+- **Invariants at risk** flagged against Phase 17 Steps 1 and 5 (forward-ref dance, `index.ts` line budget); grep acceptance checks fold into the final implementation step.
+
+## Stage: Implementation — TDD (2026-06-15T20:19:00Z)
+
+### Session summary
+
+Executed all four planned steps in order: widget self-seeding (`feat`), `NotificationManager` widget-dependency dissolve (`refactor`), direct widget injection + relay-method removal (`refactor`), and the architecture-roadmap update (`docs`).
+Test count went 1009 → 1005 (+3 widget self-seed tests, −7 removed relay/field tests).
+All deterministic checks green; pre-completion reviewer returned WARN (non-blocking).
+
+### Observations
+
+- The tidy-first sequencing held up exactly as planned: Step 2 broke the cycle while the runtime relay methods were still in place (repo stayed green), making Step 3's export/field removal a clean atomic change.
+- The cycle dissolve produced two **stale fallow suppressions** on `AgentWidget.setUICtx`/`onTurnStart` — they were `unused-class-member`-suppressed because the methods were previously reached only through the runtime relay; direct injection made them visibly used.
+  Removed both; amended into the Step 3 refactor commit.
+- Widget-class testing required constructing `AgentWidget` with a cast manager stub (`as unknown as SubagentManager`) and a recording `UICtx`; observability of the private `finishedTurnAge` is via the `setWidget` clear-vs-register signal, which cleanly distinguishes seeded-then-aged-out from never-seeded.
+- `sed` was needed for the runner/spawner test files because the widget arg appeared both inline and as standalone multiline-call lines; a `^\s*runtime,$` line match safely retargeted only the widget positional arg (never `runtime.agentActivity`).
+- Two commit-hygiene corrections: an `index.ts` comment-trim fixup was first amended into the `docs` commit by mistake, then moved into the Step 3 `refactor` commit via `reset --soft` + selective re-stage (fixups must not land in `docs:` commits).
+- **Reviewer verdict: WARN.**
+  Sole finding: `index.ts` is 177 lines (Step 5's aspirational "<170" was already overshot at its own landing, 177); the comment trim kept Step 6 net-neutral.
+  Cosmetic, prose-pinned only, non-blocking.
+- Cross-step invariants verified by grep: no `let widget` / `prefer-const` forward-ref (Step 1), no `runtime.widget` / `.widget =` / `WidgetLike` anywhere (the issue's core outcome).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.2.1",
+  "version": "16.3.0",
   "type": "module",
   "exports": {
     ".": {

package/src/handlers/tool-start.ts

@@ -5,8 +5,8 @@
  * with a mocked narrow runtime interface.
  */
 
-/** Narrow runtime interface — only the widget-delegation methods the handler calls. */
-export interface ToolStartRuntime {
+/** Narrow widget interface — only the methods the handler calls. */
+export interface ToolStartWidget {
   setUICtx(ctx: unknown): void;
   onTurnStart(): void;
 }
@@ -23,10 +23,10 @@ interface ToolStartCtx {
  * and signals the widget to clear lingering state.
  */
 export class ToolStartHandler {
-  constructor(private readonly runtime: ToolStartRuntime) {}
+  constructor(private readonly widget: ToolStartWidget) {}
 
   handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void {
-    this.runtime.setUICtx(ctx.ui);
-    this.runtime.onTurnStart();
+    this.widget.setUICtx(ctx.ui);
+    this.widget.onTurnStart();
   }
 }

package/src/index.ts

@@ -27,9 +27,10 @@ import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import { SubagentManager, type SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
-import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
+import { SubagentManager } from "#src/lifecycle/subagent-manager";
+import { type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
+import { SubagentEventsObserver } from "#src/observation/subagent-events-observer";
 import { createSubagentRuntime } from "#src/runtime";
 import { publishSubagentsService, unpublishSubagentsService } from "#src/service/service";
 import { SubagentsServiceAdapter } from "#src/service/service-adapter";
@@ -56,13 +57,12 @@ export default function (pi: ExtensionAPI) {
   const runtime = createSubagentRuntime();
 
   // ---- Notification system ----
-  // runtime.widget is assigned after SubagentManager construction; arrow closures
-  // capture `runtime` by reference so they always read the current value.
+  // Owns completion nudges and live-activity cleanup. The widget detects finished
+  // agents itself (AgentWidget.update self-seeds), so NotificationManager has no
+  // widget dependency — keeping the construction graph a cycle-free DAG.
   const notifications = new NotificationManager(
     (msg, opts) => pi.sendMessage(msg, opts),
     runtime.agentActivity,
-    (id) => runtime.markFinished(id),
-    () => runtime.update(),
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -76,61 +76,11 @@ export default function (pi: ExtensionAPI) {
   settings.load();
 
   // Observer: receives agent lifecycle notifications and dispatches events/notifications.
-  const observer: SubagentManagerObserver = {
-    onSubagentStarted(record) {
-      // Emit started event when agent transitions to running (including from queue).
-      pi.events.emit("subagents:started", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-      });
-    },
-    onSubagentCompleted(record) {
-      // Emit lifecycle event based on terminal status.
-      const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-      const eventData = buildEventData(record);
-      if (isError) {
-        pi.events.emit("subagents:failed", eventData);
-      } else {
-        pi.events.emit("subagents:completed", eventData);
-      }
-
-      // Persist final record for cross-extension history reconstruction.
-      pi.appendEntry("subagents:record", {
-        id: record.id, type: record.type, description: record.description,
-        status: record.status, result: record.result, error: record.error,
-        startedAt: record.startedAt, completedAt: record.completedAt,
-      });
-
-      // Skip notification if result was already consumed via get_subagent_result.
-      if (record.notification?.resultConsumed) {
-        notifications.cleanupCompleted(record.id);
-        return;
-      }
-
-      notifications.sendCompletion(record);
-    },
-    onSubagentCompacted(record, info) {
-      // Emit compacted event when agent's session compacts (preserves count on record).
-      pi.events.emit("subagents:compacted", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-        reason: info.reason,
-        tokensBefore: info.tokensBefore,
-        compactionCount: record.compactionCount,
-      });
-    },
-    onSubagentCreated(record) {
-      // Emit created event for background agents (before limiter admission).
-      pi.events.emit("subagents:created", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-        isBackground: true,
-      });
-    },
-  };
+  const observer = new SubagentEventsObserver({
+    emit: (channel, data) => pi.events.emit(channel, data),
+    appendEntry: (customType, data) => pi.appendEntry(customType, data),
+    notifications,
+  });
 
   const subagentSessionDeps: SubagentSessionDeps = {
     io: {
@@ -178,11 +128,12 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
 
-  // Live widget: show running agents above editor
-  runtime.widget = new AgentWidget(manager, runtime.agentActivity, registry);
+  // Live widget: constructed after the manager (it polls listAgents()) and
+  // injected directly into its consumers — no post-construction field write.
+  const widget = new AgentWidget(manager, runtime.agentActivity, registry);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
-  const toolStart = new ToolStartHandler(runtime);
+  const toolStart = new ToolStartHandler(widget);
   pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
   // Abort all subagents when the parent agent loop is interrupted (ESC).
@@ -191,7 +142,7 @@ export default function (pi: ExtensionAPI) {
 
   // ---- Agent tool ----
 
-  pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
+  pi.registerTool(new AgentTool(manager, runtime, widget, settings, registry, getAgentDir()).toToolDefinition());
 
   // ---- get_subagent_result tool ----
 

package/src/observation/notification.ts

@@ -142,8 +142,6 @@ export class NotificationManager implements NotificationSystem {
       opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
     ) => void,
     private agentActivity: Map<string, AgentActivityTracker>,
-    private markFinished: (id: string) => void,
-    private updateWidget: () => void,
   ) {}
 
   cancelNudge(key: string): void {
@@ -156,15 +154,11 @@ export class NotificationManager implements NotificationSystem {
 
   sendCompletion(record: Subagent): void {
     this.agentActivity.delete(record.id);
-    this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
-    this.updateWidget();
   }
 
   cleanupCompleted(id: string): void {
     this.agentActivity.delete(id);
-    this.markFinished(id);
-    this.updateWidget();
   }
 
   dispose(): void {

package/src/observation/subagent-events-observer.ts

@@ -0,0 +1,97 @@
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import { buildEventData, type NotificationSystem } from "#src/observation/notification";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+	emit: EventEmit;
+	appendEntry: AppendEntry;
+	notifications: NotificationSystem;
+}
+
+/**
+ * Receives agent lifecycle notifications from SubagentManager and dispatches
+ * them to three concerns: pi.events lifecycle events, session-entry persistence,
+ * and completion notifications.
+ *
+ * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
+ * three concerns are unit-testable without booting the extension.
+ */
+export class SubagentEventsObserver implements SubagentManagerObserver {
+	private readonly emit: EventEmit;
+	private readonly appendEntry: AppendEntry;
+	private readonly notifications: NotificationSystem;
+
+	constructor(deps: SubagentEventsObserverDeps) {
+		this.emit = deps.emit;
+		this.appendEntry = deps.appendEntry;
+		this.notifications = deps.notifications;
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		// Emit started event when agent transitions to running (including from queue).
+		this.emit("subagents:started", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+		});
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		// Emit lifecycle event based on terminal status.
+		const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+		const eventData = buildEventData(record);
+		if (isError) {
+			this.emit("subagents:failed", eventData);
+		} else {
+			this.emit("subagents:completed", eventData);
+		}
+
+		// Persist final record for cross-extension history reconstruction.
+		this.appendEntry("subagents:record", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			status: record.status,
+			result: record.result,
+			error: record.error,
+			startedAt: record.startedAt,
+			completedAt: record.completedAt,
+		});
+
+		// Skip notification if result was already consumed via get_subagent_result.
+		if (record.notification?.resultConsumed) {
+			this.notifications.cleanupCompleted(record.id);
+			return;
+		}
+
+		this.notifications.sendCompletion(record);
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		// Emit compacted event when agent's session compacts (preserves count on record).
+		this.emit("subagents:compacted", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			reason: info.reason,
+			tokensBefore: info.tokensBefore,
+			compactionCount: record.compactionCount,
+		});
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		// Emit created event for background agents (before limiter admission).
+		this.emit("subagents:created", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			isBackground: true,
+		});
+	}
+}

package/src/runtime.ts

@@ -10,19 +10,6 @@ import { buildParentSnapshot, type ParentSnapshot } from "#src/lifecycle/parent-
 import type { ModelInfo } from "#src/tools/spawn-config";
 import type { SessionContext } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
-import type { UICtx } from "#src/ui/agent-widget";
-
-/**
- * Narrow widget interface consumed by SubagentRuntime delegation methods.
- * AgentWidget satisfies this structurally; tests use plain stubs.
- */
-export interface WidgetLike {
-  setUICtx(ctx: UICtx): void;
-  onTurnStart(): void;
-  markFinished(id: string): void;
-  update(): void;
-  ensureTimer(): void;
-}
 
 /**
  * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
@@ -48,11 +35,6 @@ export class SubagentRuntime {
    * widget, and tool handlers. The Map itself is never replaced.
    */
   readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
-  /**
-   * Persistent widget reference. Null until constructed after SubagentManager.
-   * Delegation methods use optional chaining so callers never need `widget!`.
-   */
-  widget: WidgetLike | null = null;
 
   // ── Session-context methods ──────────────────────────────────────────────
 
@@ -90,33 +72,6 @@ export class SubagentRuntime {
       parentSessionId: this.currentCtx?.sessionManager.getSessionId() ?? "",
     };
   }
-
-  // ── Widget delegation methods ─────────────────────────────────────────────
-
-  /** Delegate to widget.setUICtx — no-op when widget is null. */
-  setUICtx(ctx: UICtx): void {
-    this.widget?.setUICtx(ctx);
-  }
-
-  /** Delegate to widget.onTurnStart — no-op when widget is null. */
-  onTurnStart(): void {
-    this.widget?.onTurnStart();
-  }
-
-  /** Delegate to widget.markFinished — no-op when widget is null. */
-  markFinished(id: string): void {
-    this.widget?.markFinished(id);
-  }
-
-  /** Delegate to widget.update — no-op when widget is null. */
-  update(): void {
-    this.widget?.update();
-  }
-
-  /** Delegate to widget.ensureTimer — no-op when widget is null. */
-  ensureTimer(): void {
-    this.widget?.ensureTimer();
-  }
 }
 
 /**

package/src/tools/agent-tool.ts

@@ -41,13 +41,21 @@ export interface AgentToolManager {
 /** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */
 export interface AgentToolRuntime {
 	readonly agentActivity: AgentActivityAccess;
+	buildSnapshot(inheritContext: boolean): ParentSnapshot;
+	getModelInfo(): ModelInfo;
+	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
+}
+
+/**
+ * Narrow widget interface the Agent tool drives directly.
+ * Superset of the runner/spawner widget deps plus `setUICtx`.
+ * AgentWidget satisfies it structurally.
+ */
+export interface AgentToolWidget {
 	setUICtx(ctx: UICtx): void;
 	ensureTimer(): void;
 	update(): void;
 	markFinished(id: string): void;
-	buildSnapshot(inheritContext: boolean): ParentSnapshot;
-	getModelInfo(): ModelInfo;
-	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
 }
 
 /** Narrow settings accessor — only the fields the Agent tool reads. */
@@ -65,6 +73,7 @@ export class AgentTool {
 	constructor(
 		private readonly manager: AgentToolManager,
 		private readonly runtime: AgentToolRuntime,
+		private readonly widget: AgentToolWidget,
 		private readonly settings: AgentToolSettings,
 		private readonly registry: AgentTypeRegistry,
 		private readonly agentDir: string,
@@ -81,7 +90,7 @@ export class AgentTool {
 		ctx: any,
 	) {
 		// Ensure we have UI context for widget rendering
-		this.runtime.setUICtx(ctx.ui as UICtx);
+		this.widget.setUICtx(ctx.ui as UICtx);
 
 		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
 		this.registry.reload();
@@ -131,7 +140,7 @@ export class AgentTool {
 		if (config.execution.runInBackground) {
 			return spawnBackground(
 				this.manager,
-				this.runtime,
+				this.widget,
 				this.runtime.agentActivity,
 				{ config, snapshot, parentSession, settings: this.settings },
 			);
@@ -140,7 +149,7 @@ export class AgentTool {
 		// ---- Foreground execution — stream progress via onUpdate ----
 		return runForeground(
 			this.manager,
-			this.runtime,
+			this.widget,
 			this.runtime.agentActivity,
 			{ config, snapshot, parentSession },
 			signal,

package/src/ui/agent-widget.ts

@@ -84,7 +84,6 @@ export class AgentWidget {
   ) {}
 
   /** Set the UI context (grabbed from first tool execution). */
-  // fallow-ignore-next-line unused-class-member
   setUICtx(ctx: UICtx) {
     if (ctx !== this.uiCtx) {
       // UICtx changed — the widget registered on the old context is gone.
@@ -100,7 +99,6 @@ export class AgentWidget {
    * Called on each new turn (tool_execution_start).
    * Ages finished agents and clears those that have lingered long enough.
    */
-  // fallow-ignore-next-line unused-class-member
   onTurnStart() {
     // Age all finished agents
     for (const [id, age] of this.finishedTurnAge) {
@@ -184,11 +182,27 @@ export class AgentWidget {
     }
   }
 
+  /**
+   * Seed linger tracking for any newly-observed finished agent.
+   * Replaces the external `markFinished` call NotificationManager used to make:
+   * the widget owns detection of completions it sees via `listAgents()`.
+   * Idempotent — only seeds when an entry is absent, so repeated updates within
+   * a turn neither reset nor advance the age.
+   */
+  private seedFinishedAgents(agents: readonly AgentSummary[]): void {
+    for (const a of agents) {
+      if (a.completedAt && !this.finishedTurnAge.has(a.id)) {
+        this.finishedTurnAge.set(a.id, 0);
+      }
+    }
+  }
+
   /** Force an immediate widget update. */
   update() {
     if (!this.uiCtx) return;
 
     const allAgents = this.manager.listAgents();
+    this.seedFinishedAgents(allAgents);
     const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
 
     if (!state.hasActive && !state.hasFinished) {