@gotgenes/pi-subagents 16.2.1 → 16.3.0

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

@@ -0,0 +1,232 @@
+---
+issue: 376
+issue_title: "Extract the manager observer from index.ts into a class"
+---
+
+# Extract the manager observer from index.ts into a class
+
+## Problem Statement
+
+`index.ts` constructs an inline `SubagentManagerObserver` object literal (~50 lines, four methods) at the composition root and hands it to `SubagentManager`.
+The literal mixes three concerns: emitting `pi.events` lifecycle events, persisting the final record via `pi.appendEntry`, and dispatching completion notifications through the `NotificationManager`.
+Per code-design principle 9 (state and behavior belong in a class, not a closure-captured literal), these three concerns cannot be unit-tested today without booting the entire extension.
+`index.ts` is the package's dominant churn hotspot (31.3, 91 commits); shrinking it is the goal of Phase 17 Track B.
+
+## Goals
+
+- Extract the inline observer literal into a `SubagentEventsObserver` class under `src/observation/`, constructed with narrow deps: an `emit` function, an `appendEntry` function, and the `NotificationSystem`.
+- `index.ts` instantiates the class and passes it to `SubagentManager` in place of the literal.
+- Unit-test the observer's three concerns directly (event shapes, record persistence payload, notification dispatch branching) without booting the extension.
+- Preserve every emitted event payload and `appendEntry` shape byte-for-byte — this is a pure extraction with no observable behavior change (not breaking).
+- Bring `index.ts` below 170 lines.
+
+## Non-Goals
+
+- Splitting widget delegation out of `SubagentRuntime` (Phase 17 Step 6, Issue [#377]) — Step 5 is its prerequisite but lands separately.
+- Moving `buildEventData` out of `notification.ts` — it stays where it is tested and is imported by the new observer.
+- Pushing event-payload construction onto `Subagent` (a Tell-Don't-Ask improvement) — tracked as an Open Question, out of scope here.
+- Narrowing `NotificationSystem` to a two-method interface — see Open Questions.
+- Any other Phase 17 step.
+
+## Background
+
+Relevant modules:
+
+- `src/index.ts` (226 lines) — composition root.
+  Defines `const observer: SubagentManagerObserver = { … }` at lines 79–134 and passes it to `new SubagentManager({ …, observer, … })`.
+- `src/lifecycle/subagent-manager.ts` — owns the `SubagentManagerObserver` interface (four methods: `onSubagentStarted`, `onSubagentCompleted`, `onSubagentCompacted`, `onSubagentCreated`).
+  This interface is the manager's contract and stays here.
+- `src/observation/notification.ts` — exports `buildEventData(record)` (pure, tested in `notification.test.ts`), the `NotificationSystem` interface (`cancelNudge`, `sendCompletion`, `cleanupCompleted`, `dispose`), and `NotificationManager`.
+- `src/observation/record-observer.ts` — the established pattern for an observation-domain module that subscribes/dispatches with narrow deps; the new class is a sibling.
+
+The current literal's four methods:
+
+- `onSubagentStarted(record)` → `emit("subagents:started", { id, type, description })`.
+- `onSubagentCompleted(record)` → branch on terminal status to `emit("subagents:failed" | "subagents:completed", buildEventData(record))`; `appendEntry("subagents:record", { …8 fields… })`; then either `notifications.cleanupCompleted(record.id)` (when `record.notification?.resultConsumed`) or `notifications.sendCompletion(record)`.
+- `onSubagentCompacted(record, info)` → `emit("subagents:compacted", { id, type, description, reason, tokensBefore, compactionCount })`.
+- `onSubagentCreated(record)` → `emit("subagents:created", { id, type, description, isBackground: true })`.
+
+SDK signatures the narrow deps mirror:
+
+- `EventBus.emit(channel: string, data: unknown): void`.
+- `ExtensionAPI.appendEntry<T = unknown>(customType: string, data?: T): void`.
+
+The applicable AGENTS.md constraints: Pi SDK imports stay out of the observation module — the class accepts `emit`/`appendEntry` as injected callbacks (the same pattern `SettingsManager` uses with `SettingsEmit`), and `index.ts` wires them to `pi.events.emit`/`pi.appendEntry` via arrows (avoids `@typescript-eslint/unbound-method`).
+
+## Design Overview
+
+### Class shape
+
+```typescript
+/** 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;
+}
+
+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 */ }
+  onSubagentCompleted(record: Subagent): void { /* emit failed|completed, appendEntry, dispatch */ }
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void { /* emit compacted */ }
+  onSubagentCreated(record: Subagent): void { /* emit created */ }
+}
+```
+
+The four method bodies are moved verbatim from the literal — same event channels, same payload fields, same branching.
+`buildEventData` is imported from `#src/observation/notification`.
+
+### Call site in index.ts
+
+```typescript
+const observer = new SubagentEventsObserver({
+  emit: (channel, data) => pi.events.emit(channel, data),
+  appendEntry: (customType, data) => pi.appendEntry(customType, data),
+  notifications,
+});
+
+const manager = new SubagentManager({
+  createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
+  baseCwd: process.cwd(),
+  observer,
+  limiter,
+  getRunConfig: () => settings,
+});
+```
+
+`notifications` (the `NotificationManager`) is already constructed earlier in `index.ts`, so the observer construction slots in where the literal was.
+
+### Extracted-module interaction with upstream deps
+
+The observer only *reads* from its inputs and *tells* its collaborators — no output-argument mutation, no reverse-search, no reach-back into the manager:
+
+```text
+onSubagentCompleted(record):
+  reads   record.status / record.id / …            (Subagent getters)
+  calls   buildEventData(record)                    (pure helper)
+  tells   this.emit("subagents:completed", data)    (injected callback)
+  tells   this.appendEntry("subagents:record", {…}) (injected callback)
+  reads   record.notification?.resultConsumed       (LoD chain — pre-existing)
+  tells   this.notifications.cleanupCompleted | sendCompletion
+```
+
+The one Law-of-Demeter chain (`record.notification?.resultConsumed`) is carried over unchanged from the literal; it is pre-existing and out of scope (see Open Questions).
+
+### Design-review checklist result
+
+| Smell            | Location                              | Evidence                                                 | Disposition                                  |
+| ---------------- | ------------------------------------- | -------------------------------------------------------- | -------------------------------------------- |
+| Dependency width | `SubagentEventsObserverDeps` (3 deps) | all methods use `emit`; `onSubagentCompleted` uses all 3 | OK — narrow                                  |
+| LoD violation    | `onSubagentCompleted`                 | `record.notification?.resultConsumed`                    | Track and watch — pre-existing, out of scope |
+| Output argument  | —                                     | none                                                     | Clean                                        |
+| ISP              | `NotificationSystem` (4 methods)      | observer uses `sendCompletion`, `cleanupCompleted`       | Accept per issue spec — see Open Questions   |
+
+The extraction introduces a real collaborator (a class that owns three behaviors and is independently testable), not a procedure split — each method returns no value but performs a distinct side-effecting concern that was previously untestable in isolation.
+
+## Module-Level Changes
+
+- `src/observation/subagent-events-observer.ts` (new)
+  - Export `SubagentEventsObserver implements SubagentManagerObserver`, plus `EventEmit`, `AppendEntry`, and `SubagentEventsObserverDeps` types.
+  - Imports: `SubagentManagerObserver` from `#src/lifecycle/subagent-manager`, `buildEventData` and `NotificationSystem` from `#src/observation/notification`, `Subagent` and `CompactionInfo` from `#src/types`.
+- `src/index.ts` (changed)
+  - Remove the inline `const observer: SubagentManagerObserver = { … }` literal (lines 79–134).
+  - Add `import { SubagentEventsObserver } from "#src/observation/subagent-events-observer"`.
+  - Construct `const observer = new SubagentEventsObserver({ emit, appendEntry, notifications })`.
+  - Remove now-unused imports: `buildEventData` (moves to the new module) and the `type SubagentManagerObserver` import (the literal annotation is gone).
+  - Keep `NotificationDetails` and `NotificationManager` imports (still used by `registerMessageRenderer` and the `notifications` construction).
+- `test/observation/subagent-events-observer.test.ts` (new)
+  - Unit tests for all four methods (see TDD Order).
+- `docs/architecture/architecture.md` (changed)
+  - Mark Phase 17 Step 5 `✅ Complete` and add a "Landed" note (index.ts line count, file/test counts).
+  - Update the "Total LOC … (60 files …)" listings to 61 files and refresh the test count.
+  - The churn-hotspot note for `index.ts` stays — Step 5 continues the shrink trend.
+
+Grep confirms no `package-*/SKILL.md` documents the inline observer literal or `SubagentEventsObserver` by name; no skill-doc update needed.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled.**
+   All four observer methods become directly testable with `vi.fn()` stubs for `emit`/`appendEntry` and a stubbed `NotificationSystem`.
+   Previously the only way to exercise these paths was through `SubagentManager` integration tests that drove the manager's `buildObserver` forwarding — the index-level observer body itself had zero coverage.
+2. **No existing tests become redundant.**
+   The `subagent-manager.test.ts` observer tests (lines 76–148) exercise the manager's *forwarding* (`buildObserver` → `this.observer?.onSubagent…`), a different layer that stays.
+   `notification.test.ts` keeps the `buildEventData` tests.
+   `agent-tool.test.ts:153` keeps its note that `subagents:created` is delegated to the observer.
+3. **Tests that must stay as-is.**
+   The manager forwarding tests and the `buildEventData` purity tests genuinely exercise layers the extraction does not touch.
+
+## Invariants at risk
+
+This step touches `index.ts`, which prior Phase 17 steps shrank, and the event/notification dispatch surface.
+Step 6 ([#377]) depends on this step; it must not regress the index.ts shrink.
+
+| Invariant                                                                                                                    | Pinned by                                     |
+| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| Completion of a successful background agent emits `subagents:completed` (not `subagents:failed`) with `buildEventData` shape | new `onSubagentCompleted` success test        |
+| Terminal `error`/`stopped`/`aborted` status emits `subagents:failed`                                                         | new `onSubagentCompleted` error test          |
+| `appendEntry("subagents:record", …)` persists the eight-field record on every completion                                     | new `onSubagentCompleted` appendEntry test    |
+| Already-consumed result skips `sendCompletion` and calls `cleanupCompleted`                                                  | new `onSubagentCompleted` resultConsumed test |
+| `subagents:created` carries `isBackground: true`                                                                             | new `onSubagentCreated` test                  |
+
+These invariants lived only in the untested inline literal before; the new tests pin them for the first time.
+
+## TDD Order
+
+1. **Red → Green → Commit: extract `SubagentEventsObserver` and wire `index.ts`.**
+
+   Write `test/observation/subagent-events-observer.test.ts` first (red), covering:
+   - `onSubagentStarted` emits `subagents:started` with `{ id, type, description }`.
+   - `onSubagentCompleted` (success status) emits `subagents:completed` with `buildEventData(record)`, calls `appendEntry("subagents:record", …)` with the eight fields, and calls `notifications.sendCompletion(record)`.
+   - `onSubagentCompleted` (error/stopped/aborted) emits `subagents:failed`.
+   - `onSubagentCompleted` with `record.notification?.resultConsumed` calls `notifications.cleanupCompleted(record.id)` and does *not* call `sendCompletion`.
+   - `onSubagentCompacted` emits `subagents:compacted` with `{ id, type, description, reason, tokensBefore, compactionCount }`.
+   - `onSubagentCreated` emits `subagents:created` with `{ id, type, description, isBackground: true }`.
+
+   Use `createTestSubagent({ … })` from `#test/helpers/make-subagent` for records (it provides status, result, error, `toolCallId` for `NotificationState`, `compactionCount`); `vi.fn()` for `emit`/`appendEntry`; a stub object for `NotificationSystem`.
+
+   Then create `src/observation/subagent-events-observer.ts` (green) and update `index.ts` in the **same commit**: replace the literal with `new SubagentEventsObserver({ … })` and drop the now-unused `buildEventData` / `type SubagentManagerObserver` imports.
+   The class and the index.ts swap are coupled — 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`.
+
+   Run `pnpm --filter @gotgenes/pi-subagents run check` and `pnpm --filter @gotgenes/pi-subagents exec vitest run`.
+   Commit: `refactor: extract SubagentEventsObserver from index.ts (#376)`
+
+2. **Commit: mark Phase 17 Step 5 complete in the architecture doc.**
+
+   In `docs/architecture/architecture.md`, mark Step 5 `✅ Complete`, add a "Landed" note (new index.ts line count, file count 60 → 61, refreshed test count), and update the two "(60 files …)" LOC listings.
+   Commit: `docs: mark Phase 17 Step 5 complete in architecture.md (#376)`
+
+## Risks and Mitigations
+
+- **Risk:** the extracted methods drift from the literal's exact event payloads or `appendEntry` shape.
+  **Mitigation:** move the bodies verbatim; the new tests assert each payload field explicitly, pinning the shapes.
+- **Risk:** passing `pi.events.emit` / `pi.appendEntry` as bare values trips `@typescript-eslint/unbound-method`.
+  **Mitigation:** wire them as arrow callbacks in `index.ts` (`(channel, data) => pi.events.emit(channel, data)`), matching the existing `SettingsManager` emit wiring.
+- **Risk:** the new class is flagged as dead code by `pnpm fallow dead-code` if it lands before its consumer.
+  **Mitigation:** the class and the `index.ts` wiring land in one commit (TDD step 1).
+- **Risk:** `index.ts` does not drop below 170 lines.
+  **Mitigation:** the literal is ~50 lines and the replacement is ~6; 226 − ~50 + ~6 ≈ 182 minus the removed import lines lands it near/below 170 — verify with `wc -l` during implementation and, if just over, the net is still a clear shrink (the Outcome target is directional, not a hard gate).
+
+## Open Questions
+
+- Should `NotificationSystem` be narrowed to a two-method `CompletionNotifier` (`sendCompletion`, `cleanupCompleted`) for the observer per ISP?
+  Deferred: the issue prescribes passing `NotificationSystem`, and the interface is already cohesive.
+  Revisit only if a third consumer wants the narrow slice.
+- Should event-payload construction (and the `record.notification?.resultConsumed` read) move onto `Subagent` as Tell-Don't-Ask methods (`record.toEventData()`, `record.isResultConsumed()`)?
+  Deferred: out of scope for a faithful extraction; `buildEventData` already exists as a pure helper.
+
+[#377]: https://github.com/gotgenes/pi-packages/issues/377

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

@@ -0,0 +1,254 @@
+---
+issue: 377
+issue_title: "Split widget delegation out of SubagentRuntime"
+---
+
+# Split widget delegation out of SubagentRuntime
+
+## Problem Statement
+
+`SubagentRuntime.widget` is assigned after construction (`runtime.widget = new AgentWidget(...)` in `index.ts`), violating construct-complete (principle 8).
+The runtime then carries five relay-only delegation methods — `setUICtx`, `onTurnStart`, `markFinished`, `update`, `ensureTimer` — that do nothing but forward to `this.widget?`.
+That is a relay-only dependency (design-review check 5): the runtime holds the widget purely to hand it to others, and the coupling leaks into tests, where the `AgentToolRuntime` fixture stubs all five widget methods on the runtime mock.
+
+The issue's "Proposed change" — construct the widget before its consumers and pass the `WidgetLike` handle directly to the tool deps and `NotificationManager` — is the right intent but is **not directly feasible** as stated.
+`NotificationManager` is not just a consumer of the widget; it is a transitive *dependency* of the widget.
+The construction graph contains a genuine cycle:
+
+```text
+NotificationManager → widget → manager → observer (SubagentEventsObserver) → NotificationManager
+```
+
+The widget needs the manager (`listAgents()`); the manager needs the observer; the observer needs the `NotificationSystem`; and `NotificationManager` needs the widget (`markFinished`/`update`).
+The current `runtime.widget` lazy field exists precisely to break this cycle.
+Removing it forces the single unavoidable late seam to move — and the operator's design principles (no setters, instantiate ready-to-work, constructor DI) rule out relocating it to a setter or a forward-referenced `let`.
+
+The cycle has exactly one weak edge: `NotificationManager → widget`.
+Dissolving that edge collapses the cycle entirely, after which the remaining relay removal is mechanical.
+
+## Goals
+
+- Remove the `widget` field and the five relay methods (`setUICtx`, `onTurnStart`, `markFinished`, `update`, `ensureTimer`) from `SubagentRuntime`.
+- Eliminate the post-construction `runtime.widget =` write from `index.ts`.
+- Inject the `AgentWidget` handle directly into its real consumers (`AgentTool`, `ToolStartHandler`) via constructor DI.
+- Dissolve `NotificationManager`'s widget dependency so the construction graph is a clean linear DAG (`notifications → observer → manager → widget → tool/handler`) with no cycle, no setter, and no forward-referenced `let`.
+- Narrow `AgentToolRuntime` to drop the four widget methods it currently declares.
+- Behavior-preserving: no observable change to widget rendering, the finished-agent linger countdown, or completion notifications.
+
+This change is **not breaking** — it is an internal refactor.
+`SubagentRuntime` is not part of the published service surface (`src/service/service.ts`); no exported API, event channel, or config default changes.
+
+## Non-Goals
+
+- Reworking how the widget is rendered, the `/agents` menu, the conversation viewer, or any first-principles UI reconsideration — that is Phase 18.
+- Replacing the widget's poll-based refresh with an event-subscription model — heavier machinery, deferred.
+- Changing `NotificationManager`'s nudge scheduling, `sendMessage` wiring, or `agentActivity` ownership.
+- Touching the foreground-runner / background-spawner direct widget calls (they are already clean consumers that receive the widget from `AgentTool`) beyond the type of the handle they accept.
+- Phase 17 Steps 7–9 (test-fixture consolidation, settings-loader duplication).
+
+## Background
+
+Relevant modules and their current widget coupling:
+
+| Module                            | Current widget coupling                                                                                                                                                      | Disposition                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `src/runtime.ts`                  | `WidgetLike` interface, `widget` field, 5 relay methods                                                                                                                      | Remove all widget knowledge                                       |
+| `src/index.ts`                    | `runtime.widget = new AgentWidget(...)` post-construction; wires `runtime.markFinished`/`runtime.update` into `NotificationManager`                                          | Construct widget as a `const`; inject directly; reorder           |
+| `src/observation/notification.ts` | `NotificationManager` ctor takes `markFinished` + `updateWidget` callbacks; `sendCompletion`/`cleanupCompleted` call them                                                    | Drop both callbacks; keep `agentActivity.delete` + nudge          |
+| `src/ui/agent-widget.ts`          | `AgentWidget(manager, agentActivity, registry)`; `markFinished(id)` seeds `finishedTurnAge`; `update()` renders                                                              | Self-seed `finishedTurnAge` from `listAgents()` during `update()` |
+| `src/tools/agent-tool.ts`         | `AgentToolRuntime` declares `setUICtx`/`ensureTimer`/`update`/`markFinished`; `execute` calls `this.runtime.setUICtx`; passes `this.runtime` as the widget to runner/spawner | Add a `widget` ctor param; narrow `AgentToolRuntime`              |
+| `src/handlers/tool-start.ts`      | `ToolStartRuntime` declares `setUICtx`/`onTurnStart`; calls them on `this.runtime`                                                                                           | Accept a widget instead of the runtime                            |
+| `src/tools/foreground-runner.ts`  | `ForegroundWidgetDeps { ensureTimer, markFinished }`                                                                                                                         | Unchanged interface; receives the real widget                     |
+| `src/tools/background-spawner.ts` | `BackgroundWidgetDeps { ensureTimer, update }`                                                                                                                               | Unchanged interface; receives the real widget                     |
+
+Key facts establishing behavior preservation for the dissolve:
+
+- The widget timer (`ensureTimer()` → `setInterval(update, 80)`) runs while any agent is active or lingering, and is cleared only on `update()`'s idle path (`!hasActive && !hasFinished`).
+  A background agent is **active at the moment it completes**, so the timer is always running then, and `hasFinished` keeps it running through the linger window.
+- The linger countdown is **turn-based**: `markFinished` seeds `finishedTurnAge[id] = 0`, `onTurnStart` ages every entry by 1, and `shouldShowFinished` hides an agent once its age reaches `maxAge` (1 for completed, 2 for error/aborted).
+  Seeding ≤80ms later (on the next timer tick) lands in the same turn, so the expiry behavior is identical.
+- `NotificationManager.sendCompletion`/`cleanupCompleted` only deletes the live `AgentActivityTracker` (running-display state) — finished agents render from `listAgents()` + `finishedTurnAge`, so the deletion is orthogonal to linger.
+
+AGENTS.md / architecture constraints that apply:
+
+- Principle 8 (construct complete; no post-construction field writes from external code) is the motivating rule — the fix must not relocate the smell to a setter or forward-ref `let` (operator steer).
+- Phase 17 Step 1 deleted a `prefer-const` eslint-disable dance; reintroducing a forward-referenced `let widget` (which trips `prefer-const`, per the `code-design` skill) would regress that and is explicitly avoided.
+- `src/runtime.ts` is **not** in the rolled public type bundle (`exports` points at `src/service/service.ts`), so this change does not require `pnpm run verify:public-types`.
+
+`AgentWidget`, `NotificationManager`, and the runtime are all internal; the published `SubagentsService` (via `service-adapter.ts`, which consumes the runtime's `currentCtx`/`buildSnapshot` only) is untouched.
+
+## Design Overview
+
+### Decision: dissolve the cycle, don't relocate the seam
+
+Three candidate seam placements were considered (recorded for the retro):
+
+1. **Late-bind notifications into the observer via a setter** — rejected: violates the no-setters principle; leaves a post-construction write.
+2. **Forward-referenced `let widget` + closures into `NotificationManager`** — rejected: trips `prefer-const` → eslint-disable, reintroducing the exact smell Phase 17 Step 1 removed; not "ready-to-work."
+3. **Dissolve `NotificationManager`'s widget dependency (chosen)** — the widget owns its own finished-agent detection; `NotificationManager` no longer references the widget; the cycle disappears and every object is constructible ready-to-work in a single linear pass.
+
+### Tidy-first sequencing
+
+Per "make the change that makes the change easy, then make the easy change," the work splits into a hard preparatory refactor and a mechanical follow-up:
+
+- **Prep (Step 1, the hard part):** make the widget self-sufficient and remove the widget callbacks from `NotificationManager`.
+  This breaks the cycle while `SubagentRuntime` still carries its relay methods (so `AgentTool`/`ToolStartHandler` are untouched and the repo stays green).
+- **Easy (Step 2):** with the cycle gone, the widget becomes a `const` injected directly into `AgentTool` and `ToolStartHandler`; the five relay methods, the `widget` field, and the post-construction write delete cleanly.
+
+### Widget self-seeding
+
+Add a private helper invoked at the top of `update()`, before state assembly:
+
+```ts
+/** Seed linger tracking for any newly-observed finished agent (replaces external markFinished). */
+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);
+    }
+  }
+}
+```
+
+`update()` calls `this.seedFinishedAgents(allAgents)` immediately after `const allAgents = this.manager.listAgents()`.
+The existing public `markFinished(id)` stays (foreground-runner still calls it directly for immediacy, and it remains idempotent — `seedFinishedAgents` only seeds when absent).
+
+### NotificationManager after the dissolve
+
+Constructor drops the last two params:
+
+```ts
+constructor(
+  private sendMessage: (msg: {...}, opts?: {...}) => void,
+  private agentActivity: Map<string, AgentActivityTracker>,
+) {}
+```
+
+`sendCompletion(record)` → `agentActivity.delete(record.id)`; `scheduleNudge(...)` (drop `markFinished` + `updateWidget`).
+`cleanupCompleted(id)` → `agentActivity.delete(id)` (drop `markFinished` + `updateWidget`).
+The `NotificationSystem` interface is unchanged (method signatures identical).
+
+### Consumer interfaces after the easy change (ISP — narrow per consumer)
+
+Drop the shared 5-method `WidgetLike` from `runtime.ts`.
+Each consumer declares only what it uses; `AgentWidget` satisfies all structurally:
+
+```ts
+// agent-tool.ts — the slice AgentTool + its runner/spawner need
+export interface AgentToolWidget {
+  setUICtx(ctx: UICtx): void;
+  ensureTimer(): void;
+  markFinished(id: string): void;
+  update(): void;
+}
+
+// tool-start.ts — the slice the turn handler needs
+export interface ToolStartWidget {
+  setUICtx(ctx: unknown): void;
+  onTurnStart(): void;
+}
+```
+
+`AgentTool` gains a `widget: AgentToolWidget` constructor param; `execute` calls `this.widget.setUICtx(...)` and passes `this.widget` to `runForeground`/`spawnBackground` (which already accept the narrow `ForegroundWidgetDeps`/`BackgroundWidgetDeps`).
+`ToolStartHandler` accepts a `ToolStartWidget` instead of `ToolStartRuntime` (rename).
+`AgentToolRuntime` loses `setUICtx`, `ensureTimer`, `update`, `markFinished` — keeping `agentActivity`, `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
+
+### Final construction order in `index.ts`
+
+```text
+registry → runtime → notifications(sendMessage, agentActivity)
+        → settings → observer(notifications) → limiter → manager(observer)
+        → service → lifecycle(runtime) → session handlers
+        → const widget = new AgentWidget(manager, agentActivity, registry)
+        → toolStart = new ToolStartHandler(widget)
+        → AgentTool(manager, runtime, widget, settings, registry, agentDir)
+        → GetResultTool / SteerTool / agentsMenu
+```
+
+No object is mutated after construction; the widget is a `const`.
+`service-adapter.ts` and `lifecycle.ts` keep consuming `runtime` for `currentCtx`/`buildSnapshot`/`setSessionContext` — none of which involve the widget.
+
+## Module-Level Changes
+
+- `src/observation/notification.ts` — remove `markFinished` and `updateWidget` constructor params; drop their calls in `sendCompletion`/`cleanupCompleted`.
+  `NotificationSystem` interface unchanged.
+- `src/ui/agent-widget.ts` — add private `seedFinishedAgents(agents)`; call it at the top of `update()` after `listAgents()`.
+  `markFinished` retained (idempotent).
+- `src/runtime.ts` — delete the `WidgetLike` interface, the `widget` field, and the five relay methods (`setUICtx`, `onTurnStart`, `markFinished`, `update`, `ensureTimer`); remove the now-unused `UICtx` import.
+  Update the class/file doc comment to drop "Persistent widget reference" / "Widget delegation methods."
+- `src/tools/agent-tool.ts` — add `AgentToolWidget` interface; add `widget` constructor param; `execute` uses `this.widget` for `setUICtx` and passes it to runner/spawner; narrow `AgentToolRuntime` (drop 4 widget methods); remove now-unused `WidgetLike`-related imports if any.
+- `src/handlers/tool-start.ts` — rename `ToolStartRuntime` → `ToolStartWidget`; constructor takes the widget; `handleToolExecutionStart` calls `this.widget.setUICtx`/`this.widget.onTurnStart`.
+- `src/index.ts` — construct `NotificationManager` with two args; construct `const widget = new AgentWidget(...)` after the manager; pass `widget` to `new ToolStartHandler(...)` and `new AgentTool(...)`; remove the `runtime.widget =` line and the stale comment block above the `NotificationManager` construction.
+- `test/observation/notification.test.ts` — drop the `markFinished`/`updateWidget` stub fields and the two `toHaveBeenCalled` assertions; assert `agentActivity.delete` + nudge behavior instead.
+- `test/ui/agent-widget.test.ts` — add coverage: `update()` self-seeds `finishedTurnAge` for a completed agent in `listAgents()`; the agent then expires after `maxAge` turns via `onTurnStart`; an already-seeded agent is not re-seeded.
+- `test/runtime.test.ts` — remove the "widget delegation methods" describe block, the "widget field accepts a `WidgetLike` stub" test, the `runtime.widget` default assertion, the `WidgetLike` import, and the `createWidgetStub` helper.
+- `test/helpers/make-deps.ts` — add a `widget` field (stub satisfying `AgentToolWidget`) to `AgentToolFixture`; narrow the `runtime` stub (drop `setUICtx`/`ensureTimer`/`update`/`markFinished`); update the doc comment that claims the runtime "also satisfies `BackgroundWidgetDeps`/`ForegroundWidgetDeps`."
+- `test/tools/agent-tool.test.ts` — `makeTool` passes `deps.widget`; the "sets UI context on runtime" test asserts on `deps.widget.setUICtx`.
+- `test/handlers/tool-start.test.ts` — construct `ToolStartHandler` with a widget stub; assert on `widget.setUICtx`/`widget.onTurnStart`.
+- `docs/architecture/architecture.md` — rewrite the Step 6 `- Change:` / `- Outcome:` bullets to the dissolve approach; add a `- Landed:` bullet and mark the heading `✅ Complete`.
+  The findings-summary line (~915) describing the smell stays accurate and is left unchanged.
+
+No `.pi/skills/package-pi-subagents/SKILL.md` references to `runtime.widget`, `WidgetLike`, or the relay methods exist (grep-verified), so no skill update is required.
+
+## Test Impact Analysis
+
+1. **New tests enabled by the extraction.**
+   Widget self-seeding (`seedFinishedAgents`) becomes directly unit-testable on `AgentWidget` via a stub manager whose `listAgents()` returns a completed record — previously the seeding path was only reachable through `NotificationManager.markFinished`.
+   `NotificationManager` becomes testable without any widget stub at all.
+2. **Tests simplified / made redundant.**
+   The two `NotificationManager` assertions on `markFinished`/`updateWidget` are deleted (the behavior moved to the widget).
+   The entire `SubagentRuntime` "widget delegation methods" describe block (5 trivial pass-through tests) and the `WidgetLike` stub plumbing are removed — pure relay tests with no remaining subject.
+3. **Tests that must stay as-is.**
+   The widget's render/linger/timer tests in `agent-widget.test.ts` (turn-aging via `onTurnStart`, `shouldShowFinished` thresholds, idle-path `clearWidget`) genuinely exercise the layer and are unchanged — the new self-seed test sits alongside them.
+   `NotificationManager`'s nudge-scheduling and `sendMessage` tests are unchanged.
+
+## Invariants at risk
+
+This step touches surfaces refactored by earlier Phase 17 steps; their documented outcomes must not regress:
+
+- **Step 1 (`#381`) — "every spawned agent has a `promise` at spawn; no forward-ref `prefer-const` eslint-disable."**
+  Pinned by the limiter/manager tests in `test/lifecycle/`.
+  Reintroducing a forward-ref `let widget` would regress this spirit — the chosen dissolve approach specifically avoids it.
+- **Step 5 (`#376`) — "`index.ts` < 170 lines; observer's three concerns unit-tested directly."**
+  This step removes lines from `index.ts` (relay wiring + `runtime.widget =`), so the line budget is preserved or improved; `SubagentEventsObserver` is untouched.
+  No new behavior is added to `index.ts`.
+- **Construct-complete (principle 8), the roadmap-wide Category-B/C invariant.**
+  Pinned after this change by the absence of any `runtime.widget =` (grep-verifiable) and by `test/runtime.test.ts` no longer constructing a widget — add the grep check to the acceptance criteria.
+
+## TDD Order
+
+1. **Widget self-detects finished agents (prep — make it easy).**
+   - Red: in `test/ui/agent-widget.test.ts`, assert `update()` seeds `finishedTurnAge` for a completed agent returned by `listAgents()` (rendered as finished), that it expires after `maxAge` turns via `onTurnStart`, and that an already-tracked agent is not re-seeded.
+   - Green: add `private seedFinishedAgents(agents)` and call it at the top of `update()`.
+   - Commit: `test:` then `feat:` — or a single `feat: self-seed finished agents in AgentWidget.update (#377)`.
+2. **Drop widget callbacks from NotificationManager (prep — breaks the cycle).**
+   - Red/Green: update `test/observation/notification.test.ts` to construct `NotificationManager` with two args and assert `agentActivity.delete` + nudge (drop the `markFinished`/`updateWidget` assertions); remove the two callbacks from the constructor and from `sendCompletion`/`cleanupCompleted`; update the `index.ts` construction site in the same commit (sole call site — the type checker requires it atomic).
+   - Commit: `refactor: dissolve NotificationManager widget dependency (#377)`.
+   - Outcome: the construction cycle is gone; `SubagentRuntime` still carries its relay methods (repo green).
+3. **Inject the widget directly; remove relay methods and the widget field from SubagentRuntime (the easy change).**
+   - This is one atomic commit: removing the `widget` field, the five relay methods, and narrowing `AgentToolRuntime` breaks `AgentTool`, `ToolStartHandler`, `index.ts`, and their tests at the type level simultaneously (export/field removal — per the workflow rule, fold all consumer and consumer-test updates into one step).
+   - Changes: add `AgentToolWidget` + `widget` param to `AgentTool`; rename `ToolStartRuntime` → `ToolStartWidget` and accept the widget in `ToolStartHandler`; delete `WidgetLike` + `widget` + 5 relay methods from `runtime.ts`; construct `const widget` and reorder `index.ts` (remove the `runtime.widget =` write); update `make-deps.ts` (add `widget` stub, narrow `runtime`), `agent-tool.test.ts`, `tool-start.test.ts`, and `runtime.test.ts` (delete the delegation describe block + `WidgetLike` plumbing).
+   - Commit: `refactor: inject widget directly, remove relay methods from SubagentRuntime (#377)`.
+   - Acceptance: `rg 'runtime\.widget|\.widget =' src/` returns nothing; `rg 'WidgetLike' src/ test/` returns nothing; `pnpm run check && pnpm run lint && pnpm -r run test && pnpm fallow dead-code` clean.
+4. **Update the architecture roadmap.**
+   - Rewrite Step 6 `- Change:`/`- Outcome:` to the dissolve approach, add `- Landed:`, mark `✅ Complete`.
+   - Commit: `docs: record Phase 17 Step 6 widget-delegation split (#377)`.
+
+## Risks and Mitigations
+
+- **Risk: self-seed timing differs from the old immediate `markFinished`/`update`.**
+  Mitigation: the timer is always running at a background completion (the agent was active); the seed lands ≤80ms later within the same turn; linger expiry is turn-based, so the rendered outcome is identical.
+  The new widget test pins the seed-then-expire behavior.
+- **Risk: a completed agent never expires if it is never seeded.**
+  Mitigation: `seedFinishedAgents` runs on every `update()` tick while the widget is live; the idle-path `clearWidget` only fires once nothing is active or finished, so a finished agent is always seeded before the widget can go idle.
+- **Risk: removing exports/fields breaks consumers mid-refactor.**
+  Mitigation: Step 2 breaks the cycle while leaving the relay methods in place (repo green); Step 3 folds the export/field removal and all consumers + tests into one atomic commit.
+- **Risk: regressing an earlier Phase 17 invariant (forward-ref dance, `index.ts` budget).**
+  Mitigation: the dissolve approach introduces no `let widget` and only removes lines from `index.ts`; the Invariants-at-risk grep checks are in the Step 3 acceptance criteria.
+
+## Open Questions
+
+- Should `AgentTool` receive one `AgentToolWidget` and forward it, or should it receive the narrower `ForegroundWidgetDeps`/`BackgroundWidgetDeps` separately?
+  Plan assumes a single `AgentToolWidget` superset (it also calls `setUICtx` itself) forwarded to the runner/spawner — revisit only if ISP pressure appears during implementation.
+- Whether foreground-runner's explicit `markFinished(fgId)` is now redundant given widget self-seeding.
+  Plan keeps it (immediacy; idempotent) to hold scope tight; a follow-up could remove it if the self-seed proves sufficient.

package/docs/retro/0375-extract-run-listener-workspace-bracket.md

@@ -49,3 +49,56 @@ Pre-completion reviewer returned WARN (2 non-blocking findings; the doc metric r
 - **Pre-completion reviewer WARN findings** (both addressed inline):
   1. `architecture.md` health-metric rows still carried "→ 59 after Step 4" annotations after landing — updated to actual counts (60 files, 8,356 LOC) and the docs commit amended.
   2. `WorkspaceBracket.hasProvider()` TDA trade-off — documented in the `run()` call-site comment; noted here for Phase 18 awareness.
+
+## Stage: Final Retrospective (2026-06-15T02:04:42Z)
+
+### Session summary
+
+Shipped issue #375 (Phase 17 Step 4) cleanly across four stages in one continuous session: planning produced a 4-step plan, TDD implemented it in 4 commits (suite 982 → 994), shipping pushed/verified-CI/closed-the-issue and merged release-please PR #406 (`pi-subagents-v16.2.1`, which actually carried #374's `fix:` — #375's `refactor:`/`docs:` commits trigger no bump).
+The only substantive friction was a single self-identified plan deviation in TDD (a microtask-boundary timing trap), resolved inside the same commit with no rework, reorder, or user correction.
+
+### Observations
+
+#### What went well
+
+- **The cross-step-invariant discipline from the #374 retro paid off a second time.**
+  The #374 process retro added the "Invariants at risk" plan section; the #375 plan used it to list the three prior Phase 17 invariants (at-spawn `promise`, construct-complete, zero external field writes), each already pinned by a named test.
+  All three held through the extraction with a green suite — the regression class that bit #374 did not recur.
+  This is the first time the new section was load-bearing on a *fresh* issue rather than as a post-hoc correction.
+- **Planning corrected the issue's own design sketch instead of implementing it literally.**
+  The issue proposed `RunListeners.attach(unsub, detach)` and "three dispose paths collapse into one"; the plan recognized the two handles attach at different lifecycle moments (so `attach` had to split into `wireSignal`/`attachObserver`/`release`) and that the two dispose sites have genuinely different error-handling semantics (so they stay separate per the structural-duplication heuristic).
+  Treating the issue body as a hypothesis, not a spec, avoided a wrong abstraction.
+
+#### What caused friction (agent side)
+
+- `missing-context` — the plan's Design Overview sketched `const cwd = await this.workspaceBracket.prepare(...)` **unconditionally**, but the original `run()` only awaited inside `if (provider) { ... }`, keeping the no-provider path synchronous up to the factory call.
+  An always-`async` helper adds a microtask boundary even when it returns immediately, so the queued-abort test in `subagent-manager.test.ts` ("abort removes a queued agent without ever running it") failed: it asserts `factory.toHaveBeenCalledOnce()` synchronously, and the factory call had been deferred a tick.
+  The first fix attempt (`if (this.execution.getWorkspaceProvider)`) also failed because `SubagentManager.spawn()` always injects `getWorkspaceProvider: () => this._workspaceProvider` as a function regardless of whether a provider is registered, so the guard was always true.
+  Resolved by adding `WorkspaceBracket.hasProvider()` (a synchronous predicate) and guarding the `await` with it.
+  Impact: ~2 test-run cycles inside TDD step 3, one extra method (`hasProvider`) plus 2 unit tests not in the plan, and a mild Tell-Don't-Ask trade-off the pre-completion reviewer flagged as WARN.
+  Self-identified via the failing test; no commit reorder, no rework beyond the in-commit fix.
+- `other` (minor) — `subagent.ts` first landed at 469 LOC, above the plan's ≤ 450 gate; two trim passes (stale module-level doc comment, redundant field comments) brought it to 448.
+  The trimmed comments were genuinely stale post-extraction, so the trim was legitimate, but the LOC estimate ("≈ 40 lines removed") was optimistic about the structural change alone.
+  Impact: 2 extra edits, no rework.
+
+#### What caused friction (user side)
+
+- None.
+  The four-stage flow ran end-to-end on prompt templates with zero mid-stream user corrections or strategic interventions — the work was clean enough that none were needed.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning ran on `anthropic/claude-opus-4-8` (pinned via `plan-issue.md`, appropriate for judgment-heavy design); TDD on `anthropic/claude-sonnet-4-6` (appropriate); the pre-completion reviewer subagent on its frontmatter default; Retro on `anthropic/claude-opus-4-8` (pinned).
+  The **ship stage ran on `opencode-go/deepseek-v4-flash`** — the same weak-model-on-release-management pattern flagged in the #374 retro.
+  It again executed cleanly, including the non-trivial reasoning that PR #406 mapped to #374 not #375 and the `UNSTABLE`/empty-rollup `GITHUB_TOKEN` diagnosis.
+  Second consecutive clean run, so the risk remains theoretical (irreversible ops on a weak model) rather than demonstrated harm.
+- **Escalation-delay tracking** — the microtask friction was not a rabbit hole: the diagnosis moved methodically (failing test → `concurrency-limiter.ts` → `subagent-manager.ts:156` injection point → root cause) across ~2 test-run cycles, under the 5-call flag threshold.
+- **Unused-tool detection** — the friction was exact-symbol tracing (`grep` for `getWorkspaceProvider`), which `grep` handled correctly; no Explore/colgrep dispatch was warranted.
+- **Feedback-loop gap analysis** — verification was incremental throughout: per-file `vitest` after each red/green, `pnpm run check` after the interface-change step, full suite + lint + `fallow dead-code` before the pre-completion review.
+  No end-only-verification gap.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added a bullet under `### Interface and type changes` on the conditional-`await` → always-`async` microtask-boundary trap (sibling to the existing runtime-vs-typecheck timing rule).
+2. `packages/pi-subagents/docs/retro/0375-extract-run-listener-workspace-bracket.md` — added this Final Retrospective stage entry.
+3. Considered but not landed (operator-declined or out of scope): pinning `/ship-issue` to a stronger model (recurrence of the #374 finding, no demonstrated harm this session), a `plan-issue` rule on preserving conditional awaits in extracted-method sketches, and a rule against trimming comments to hit a LOC gate.