@gotgenes/pi-subagents 16.5.0 → 17.0.0

package/docs/retro/0423-widget-self-drive-from-lifecycle.md

@@ -0,0 +1,112 @@
+---
+issue: 423
+issue_title: "pi-subagents: make the agent widget self-drive from lifecycle events"
+---
+
+# Retro: #423 — Make the agent widget self-drive from lifecycle events
+
+## Stage: Planning (2026-06-17T00:00:00Z)
+
+### Session summary
+
+Planned Phase 18 Step 4 of the widget/tool decoupling track: making `AgentWidget` a `SubagentManagerObserver` that self-drives its 80 ms timer from lifecycle notifications, wired via a new `CompositeSubagentObserver` fan-out, and removing all inbound widget calls from the spawn tools.
+Wrote a four-step plan (three `refactor:` commits + a `docs:` sweep) at `packages/pi-subagents/docs/plans/0423-widget-self-drive-from-lifecycle.md`.
+
+### Observations
+
+- **Wiring mechanism was the live design decision.**
+  `SubagentManager` has a single `observer` slot.
+  Three options surfaced: (A) a `CompositeSubagentObserver` fan-out in `index.ts`, (B) make the manager hold an observer list, (C) subscribe the widget to the public `pi.events` channels.
+  The operator initially leaned toward B (matching the issue's literal file list) but was unsure; after reframing around the decouple + overridable-UI north star, they chose **A**.
+  Rationale recorded in the plan: A keeps the core closed for modification, B moves fan-out *into* the core (wrong direction), and C front-runs the Step 6 ([#425]) public-event-contract reconciliation.
+  Key insight that flattened the decision: all three options keep the widget's `manager.listAgents()` reference, so they only change the *trigger*, not the data source — full broadcast-plus-query decoupling is the Step 8 ([#427]) concern.
+- **`markFinished` is fully redundant** and is deleted, not relocated: `seedFinishedAgents()` (added in [#421] / [#422]) already seeds any agent with `completedAt` on each poll tick.
+  This matters because the manager **never fires `onSubagentCompleted` for foreground agents** (`onRunFinished` guards on `isBackground`), so the widget could not learn of foreground completion via the observer anyway — polling covers it.
+- **Construction cycle** (widget needs manager → manager needs observer → observer includes widget) is broken by constructing the composite with `[eventsObserver]`, passing it to the manager, then `observer.add(widget)` after the widget is built; the manager consults the observer only lazily at spawn time.
+- **TDD ordering avoids a behavior gap:** Step 2 wires the widget as an observer *while the spawn tools still drive it* (idempotent double-drive), strictly before Step 3 removes the spawn-tool calls — so no commit leaves the widget without a timer-start signal.
+  The new widget observer methods need no `fallow-ignore` because they are invoked polymorphically through `SubagentManagerObserver` (the `SubagentEventsObserver` precedent).
+- This step narrows `AgentToolWidget` to `setUICtx` only but keeps the `AgentTool` widget constructor param; full removal is Step 5 ([#424]).
+- Non-breaking and internal-only (no public service/settings surface touched), so `refactor:`/`docs:` commits, no `BREAKING CHANGE` footer.
+
+## Stage: Implementation — TDD (2026-06-17T10:00:00Z)
+
+### Session summary
+
+Executed the four-step plan exactly as written: added `CompositeSubagentObserver` (Step 1), made `AgentWidget` a `SubagentManagerObserver` and wired the composite in `index.ts` (Step 2), removed all spawn-tool widget wiring and deleted `markFinished` (Step 3), then swept the architecture doc + SKILL.md (Step 4).
+Four commits (three `refactor:`, one `docs:`); test count `1032 → 1039` (+7 composite, +4 widget observer, −4 removed spawner/fixture widget-driving tests).
+`check`, root `lint`, full `test`, and `fallow dead-code` all green; pre-completion reviewer returned PASS.
+
+### Observations
+
+- **Mid-step correction (not a separate commit):** in Step 2 I initially over-reached by deleting `markFinished` and privatizing `ensureTimer`, which breaks `index.ts` typing because `AgentToolWidget` still required those methods until Step 3.
+  Caught it before committing and reverted both to Step 3 per the plan; Step 2 kept them public.
+  The plan's ordering (narrow `AgentToolWidget` and delete `markFinished` only in the atomic Step 3 removal) was correct — the lesson is to trust the step boundaries.
+- **Biome `useIterableCallbackReturn` false trigger:** naming the composite's private fan-out helper `forEach` made Biome treat the call as `Array.prototype.forEach` and reject the value-returning arrow.
+  Renamed it to `dispatch` — a strictly better name anyway.
+- **`vi.getTimerCount()` cleanly proves the timer started:** the widget observer tests assert `getTimerCount()` goes `0 → 1` on `onSubagentStarted`/`onSubagentCreated`, distinguishing `startLoop` (ensureTimer + render) from a bare `update()` (render only), with the manager-stub creating no other timers.
+- **No dead-code window:** the widget's new observer methods are invoked polymorphically through `SubagentManagerObserver` (the `SubagentEventsObserver` precedent), so `fallow` saw them as used from Step 2 onward; `ensureTimer` became `private` in Step 3, dropping its now-stale `fallow-ignore`.
+- **The Step 2 transient double-drive was harmless** as predicted: both the spawn tools and the composite drove the widget in that commit, and every driven method is idempotent — full suite green at that commit.
+- **Reviewer notes (non-blocking, both PASS):** a pre-existing "six domains" vs "seven domains" inconsistency in `architecture.md` (Phase 17, out of scope, left alone); and `observer.add(widget)` is a justified post-construction write documented as the only construction-cycle break (widget needs manager, manager needs observer).
+- **Pre-completion reviewer: PASS** — all deterministic checks, code-design, test-artifact, Mermaid (`mmdc` parsed all 6 blocks), dead-code, and cross-step-invariant lenses passed.
+
+## Stage: Final Retrospective (2026-06-17T18:30:00Z)
+
+### Session summary
+
+Shipped Phase 18 Step 4 across plan → TDD → ship in a single session: the `AgentWidget` became a `SubagentManagerObserver` that self-drives its 80 ms timer through a new `CompositeSubagentObserver` fan-out, and the spawn tools shed every widget call.
+Four implementation commits (three `refactor:`, one `docs:`), pre-completion reviewer PASS, CI green, issue closed; no release (all commits non-releasing).
+Execution was clean — two self-caught agent-side slips, no rework commits, and the only user input was one productive redirect plus a release-timing answer.
+
+### Observations
+
+#### What went well
+
+- **Two-round `ask_user` on the wiring decision (planning).**
+  The first round offered three mechanisms (composite / manager-list / `pi.events`); the operator picked B but flagged uncertainty.
+  Reframing around the decouple + overridable-UI north star and re-asking flipped the choice to A (`CompositeSubagentObserver`) with explicit buy-in.
+  The reframe surfaced the insight that flattened the decision: all three options keep the widget's `manager.listAgents()` reference, so they change only the *trigger*, not the data source.
+- **`vi.getTimerCount()` as a precise timer-start assertion.**
+  The widget observer tests assert `getTimerCount()` goes `0 → 1` on `onSubagentStarted`/`onSubagentCreated`, cleanly distinguishing `startLoop` (timer + render) from a bare `update()` (render only).
+- **"Double-drive" lift-and-shift ordering.**
+  Step 2 wired the new observer while the spawn tools still drove the widget (idempotent overlap), and Step 3 removed the old path — no commit left the widget without a timer-start signal, and the full suite was green at every commit.
+- **Incremental verification cadence.**
+  `pnpm run check` after each shared-type change, `vitest` per-file in red/green, `mmdc` on all 6 Mermaid blocks, and `fallow`/`lint`/full-suite at the end of Step 3 — no end-only verification.
+
+#### What caused friction (agent side)
+
+- `scope-drift` (self-identified) — in TDD Step 2 I deleted `markFinished` and privatized `ensureTimer` ahead of schedule; both belonged to the atomic Step 3 removal because `AgentToolWidget` still required them until then (deleting early breaks `index.ts` typing).
+  Caught by reasoning before committing and reverted to Step 3.
+  Impact: a few corrective edits, no extra commit, no rework.
+  Lesson: re-read the step's exact scope before editing, rather than editing from the overall design held in memory.
+- `missing-context` (self-identified) — naming the composite's private fan-out helper `forEach` tripped Biome's `useIterableCallbackReturn` (it treated the call as `Array.prototype.forEach` and rejected the value-returning arrow).
+  Renamed to `dispatch`.
+  Impact: one rename, caught immediately by the `pi-autoformat` hook; no rework.
+- `other` — the ship stage asked the batch-vs-release question for a multi-issue sequence, but every unreleased commit was `refactor:`/`docs:`, so release-please produced no PR regardless of the answer.
+  The operator's "release now" answer was therefore unactionable (the work auto-batches until a `feat`/`fix` lands).
+  Impact: one unactionable `ask_user` round; correct outcome reached, but the question implied a choice that did not exist.
+
+#### What caused friction (user side)
+
+- None blocking — the planning redirect ("I'm not confident in my choice… the goal is to decouple… an event system would make sense but isn't on the roadmap") was the ideal intervention: a redirecting question that handed over the north star instead of a post-hoc correction, and it directly produced the better design.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning ran on `anthropic/claude-opus-4-8` (design + the two-round wiring `ask_user`; appropriate).
+  TDD ran on `anthropic/claude-sonnet-4-6` (implementation; handled the Step 2 self-correction and the Biome rename; adequate).
+  The `pre-completion-reviewer` subagent ran on `anthropic/claude-sonnet-4-6` (its frontmatter) and returned a thorough PASS.
+  Ship ran on `opencode-go/deepseek-v4-flash` — a reasoning-weak model carrying the batch-vs-release judgment and the "no release PR expected" inference.
+  It reached the correct outcome, but this is the same latent risk the #422 retro flagged: a weak model on the one ship-stage judgment call.
+  Proposal 1 mitigates it by making the release-trigger check deterministic so the stage needs no judgment.
+- **Escalation-delay tracking** — no `rabbit-hole`s; both agent-side slips resolved in one tool call each (one rename, one revert); no sequence exceeded 5 calls on one error.
+- **Unused-tool detection** — no `missing-context` gaps requiring a subagent; `grep` (not `colgrep`) was used in planning, correctly — every search was an exact symbol match (`ensureTimer`, `markFinished`, `observer`).
+- **Feedback-loop gap analysis** — no gap; verification was incremental, not end-only (see "What went well").
+
+### Changes made
+
+1. `.pi/prompts/ship-issue.md` — step 4b now opens with a release-trigger gate: check `git log --oneline <last-tag>..HEAD`, and when every commit is a non-releasing type (`refactor:`/`docs:`/`style:`/`chore:`/`test:`), state that release-please cuts nothing now and skip the batch-vs-release question.
+
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#424]: https://github.com/gotgenes/pi-packages/issues/424
+[#425]: https://github.com/gotgenes/pi-packages/issues/425
+[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/retro/0424-drop-widget-dep-from-subagent-tool.md

@@ -0,0 +1,89 @@
+---
+issue: 424
+issue_title: "pi-subagents: drop the widget and activity-map dependencies from the subagent tool"
+---
+
+# Retro: #424 — pi-subagents: drop the widget and activity-map dependencies from the subagent tool
+
+## Stage: Planning (2026-06-18T15:01:42Z)
+
+### Session summary
+
+Planned Phase 18 Step 5: dropping the `widget` constructor dependency from `AgentTool` and shedding the widget stub from `createToolDeps`.
+Verified against current `main` that the `agentActivity` / activity-map dependency named in the issue and roadmap was already removed in Phase 18 Step 3 ([#422]) — only `widget` remains to drop, so the plan corrects that stale wording.
+Produced `docs/plans/0424-drop-widget-dep-from-subagent-tool.md` and committed it.
+
+### Observations
+
+- The issue body and the architecture roadmap's Step 5 entry both still say `agentActivity`, but `grep` found no live `agentActivity`/`AgentActivity` references in `src/` — the only hit is a comment in `test/lifecycle/usage.test.ts`.
+  Flagged the roadmap Step 5 description for a stale-wording fix during implementation.
+- This is a purely subtractive, non-breaking refactor: `AgentTool` is internal (public exports are only the service and settings entries), and `ToolStartHandler` already captures UICtx on every `tool_execution_start`, which fires before any tool's `execute`.
+  So removing the tool's own `setUICtx` call loses no behavior — `test/handlers/tool-start.test.ts` already pins UICtx capture on its true owner.
+- Folded all edits into one refactor commit because removing the constructor parameter breaks the `index.ts:152` call site, the `make-deps.ts` fixture, and `agent-tool.test.ts` at typecheck time — they cannot land separately.
+- Two obsolete tests to remove: `agent-tool.test.ts` → `"sets UI context on runtime at start of execute"` and `make-deps.test.ts` → `describe("widget defaults")`.
+  The `UICtx` type itself stays (used by `agent-widget.ts`, `tool-start.ts`, and the widget test) — only the `UICtx` import in `agent-tool.ts` and the `AgentToolWidget` interface go.
+- Skipped the `ask-user` gate: operator-authored issue (`gotgenes`), unambiguous proposed change following an established roadmap, clearly non-breaking.
+
+## Stage: Implementation — TDD (2026-06-18T15:10:13Z)
+
+### Session summary
+
+Executed the two-step plan: one `refactor:` commit dropping the `widget` constructor dependency from `AgentTool` (plus the `UICtx` import, `AgentToolWidget` interface, the redundant `setUICtx` call, the `index.ts` call site, the `createToolDeps` field/stub, and two obsolete tests), and one `docs:` commit marking Phase 18 Step 5 complete in the architecture doc.
+Test count went from 1039 to 1037 (−2 removed obsolete tests); `check`, root `lint`, full `test`, and `fallow dead-code` all green.
+
+### Observations
+
+- The refactor was purely subtractive and folded all src + test edits into one commit, as the plan predicted — the constructor-signature change breaks `index.ts`, `make-deps.ts`, and `agent-tool.test.ts` at typecheck simultaneously.
+- Renamed the unused `execute` `ctx` parameter to `_ctx` rather than removing it — the inner `defineTool` `execute` closure must keep the 5-arg signature, so the method keeps the positional slot but ignores it.
+- Corrected the architecture doc's Step 5 `Outcome` from "fixture drops 2 fields" to "drops 1 field" and noted the `agentActivity` half was already done in [#422] — the plan flagged this stale wording in advance.
+- Pre-completion reviewer: WARN (1 non-blocking finding).
+  The `package-pi-subagents` SKILL test count was stale (994/63 "as of Phase 17 Step 4"); refreshed to 1037/64 "as of Phase 18 Step 5" in a follow-up `docs:` commit.
+  All cross-step invariants verified — UICtx capture stays pinned by `handlers/tool-start.test.ts`, and no `setUICtx` calls remain in spawn tools or the tool.
+
+## Stage: Final Retrospective (2026-06-18T15:20:14Z)
+
+### Session summary
+
+Planned, implemented, and shipped Phase 18 Step 5 across three stages: a subtractive refactor dropping the `widget` constructor dependency from `AgentTool`, landed as one `refactor:` commit plus two `docs:` commits.
+CI passed, `#424` closed; all commits since `pi-subagents-v16.6.0` are non-releasing (`refactor:`/`docs:`/`style:`), so release-please batches until a `feat`/`fix` lands.
+Net test count 1039 → 1037 (−2 obsolete tests); the pre-completion reviewer returned WARN on a single stale-doc finding that was fixed inline.
+
+### Observations
+
+#### What went well
+
+- Planning caught that the issue body and roadmap Step 5 both named an `agentActivity`/activity-map dependency that was already removed in [#422]; a `grep` of `src/` for `agentActivity` confirmed only `widget` remained.
+  The `/plan-issue` "treat the proposed change as a hypothesis, verify against current code" discipline worked exactly as intended and prevented planning around a phantom dependency.
+- The plan correctly predicted the atomic-commit shape: removing the constructor parameter breaks `index.ts`, `make-deps.ts`, and `agent-tool.test.ts` at typecheck simultaneously, so the implementation folded all edits into one commit with zero rework.
+- Verification ran incrementally — `pnpm run check` plus the affected test files after the edits, then the full suite + root `lint` + `fallow dead-code` at the end of TDD — so no feedback-loop gap.
+- Clean handoff between stages: the planning retro entry flagged the stale `agentActivity` wording in advance, and the TDD stage acted on it without re-deriving the context.
+
+#### What caused friction (agent side)
+
+- `missing-context` (low impact, recurring) — the `package-pi-subagents` SKILL.md hardcoded test count (`994 tests across 63 files as of Phase 17 Step 4`) was stale by four issues.
+  The SKILL.md was edited by `docs:` commits in [#421], [#422], [#423], and [#424], yet none refreshed the count until the [#424] pre-completion reviewer flagged it.
+  Impact: one extra `docs:` commit (`18900d3f`) at ship time; no rework, but the precise count is structurally prone to per-step drift and the reviewer caught it only by chance at one of five Phase 18 steps.
+
+#### What caused friction (user side)
+
+- None.
+  The session was fully operator-authored and roadmap-driven; no user intervention or correction was needed at any stage.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the `pre-completion-reviewer` subagent ran on `anthropic/claude-sonnet-4-6` (per its agent frontmatter), appropriate for judgment-heavy review; it produced a thorough, correctly-structured PASS/WARN report.
+  The parent session switched models several times (`opus-4-8` → `sonnet-4-6` → `deepseek-v4-flash` → `opus-4-8`); execution stayed clean throughout, so no model-quality mismatch was observable.
+- **Escalation-delay tracking** — no `rabbit-hole` friction; no error sequence exceeded one tool call.
+- **Unused-tool detection** — nothing notable; the work was fully specified by the plan and needed no exploratory dispatch.
+- **Feedback-loop gap analysis** — verification was incremental (typecheck + affected tests per edit, full gates at end of TDD, root `lint` + `fallow` before push); no end-only verification gap.
+
+### Changes made
+
+1. Rewrote the opening sentence of the `## Testing` section in `.pi/skills/package-pi-subagents/SKILL.md` to drop both the hardcoded test count and the fork framing.
+   The operator judged the precise count (`1037 tests across 64 files as of Phase 18 Step 5`) to provide no real value and to be structurally prone to per-step drift — it had gone stale across four issues ([#421]–[#424]) before the [#424] reviewer caught it.
+   The fork is already introduced at the top of the skill, so the Testing section need not re-reference upstream; the sentence now reads "The package has an extensive `vitest` suite."
+
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424

package/docs/retro/0425-reconcile-subagent-events-contract.md

@@ -0,0 +1,46 @@
+---
+issue: 425
+issue_title: "pi-subagents: reconcile the public SUBAGENT_EVENTS contract with emitted channels"
+---
+
+# Retro: #425 — pi-subagents: reconcile the public SUBAGENT_EVENTS contract with emitted channels
+
+## Stage: Planning (2026-06-18T00:00:00Z)
+
+### Session summary
+
+Planned Phase 18 Step 6: reconcile the public `SUBAGENT_EVENTS` constant map in `src/service/service.ts` with the agent-lifecycle channels the core actually emits.
+The plan removes the vacant `ACTIVITY` constant (breaking) and adds `FAILED`, `COMPACTED`, `CREATED`, and `STEERED`, then updates the architecture doc's lifecycle-events table.
+Two TDD steps: a `feat!:` constant-map reconciliation pinned from both sides (declaration test + existing emission tests), and a `docs:` table update.
+
+### Observations
+
+- This is the operator's own issue (author `gotgenes` matches the gh CLI user), so the proposed change was treated as the working hypothesis.
+- Two genuine design choices were surfaced via `ask_user` and resolved: (1) remove `ACTIVITY` rather than emit a real broadcast — the activity tier was already deleted in Phase 18 Steps 1–3, so there is no streaming-progress source; (2) declare all four emitted agent-lifecycle channels including `subagents:steered` (from `steer-tool.ts`), not just the three named in the issue body, so declared == emitted is fully true for the lifecycle bus.
+- Classified as **breaking**: removing a key from the exported `SUBAGENT_EVENTS` `as const` map breaks any consumer referencing `SUBAGENT_EVENTS.ACTIVITY` at the type level.
+  Plan uses `feat!:` with a `BREAKING CHANGE:` footer; the footer notes there is no replacement for `ACTIVITY`.
+- Scope boundaries decided: config-domain events (`subagents:settings_loaded`/`settings_changed`) and the child-session seam events (`subagents:child:*`) stay out of `SUBAGENT_EVENTS` — separate domains with their own constant homes. `subagents:record` is an `appendEntry`, not a `pi.events.emit`, so it is not a channel constant.
+- Corrected a stale doc artifact found during planning: the architecture lifecycle-events table listed `subagents:completed` as `{ id, type, status, result?, error? }`, but `buildEventData` emits `{ id, type, description, result, error, status, toolUses, durationMs, tokens? }`.
+  The plan fixes this in the same doc step.
+- Public-surface gate: the plan requires running `verify:public-types` in the code step before committing, since `SUBAGENT_EVENTS` is rolled into `dist/public.d.ts`.
+- Value-only reconciliation — no new collaborator, no dependency-wiring change — so the `design-review` checklist surfaces nothing actionable; noted in the plan rather than run as a separate gate.
+- Next step: `/tdd-plan` (the change has a red→green test cycle).
+
+## Stage: Implementation — TDD (2026-06-18T00:00:00Z)
+
+### Session summary
+
+Executed both planned TDD steps in two commits: a `feat!:` reconciling the `SUBAGENT_EVENTS` constant map (removed `ACTIVITY`, added `FAILED`/`COMPACTED`/`CREATED`/`STEERED`) pinned by an expanded `service.test.ts` assertion plus an explicit "no vacant `ACTIVITY`" check, then a `docs:` update to the lifecycle-events table and the Phase 18 Step 6 roadmap entry.
+Full suite green at 1038 tests (+1 from the planning baseline of 1037); `check`, root `lint`, `verify:public-types`, and `fallow dead-code` all pass.
+
+### Observations
+
+- No deviations from the plan's design.
+  The only mid-stream addition was the extra `"ACTIVITY" in SUBAGENT_EVENTS` falsity assertion, which strengthens the breaking-removal coverage beyond what the plan sketched.
+- The breaking change went smoothly: `SUBAGENT_EVENTS.ACTIVITY` had no live consumers, so removal broke only the one service test that asserted it — folded into the same `feat!:` step as planned.
+- Ran `verify:public-types` before committing Step 1 (public-surface gate); the rolled `dist/public.d.ts` regenerated cleanly with the narrowed `as const` literal types.
+- `git diff` since the last tag (`pi-subagents-v16.6.0`) lists files from prior unreleased issues #422/#423/#424; scoped the pre-completion reviewer to #425's two commits to avoid noise.
+- Pre-completion reviewer: WARN (1 non-blocking finding).
+  The Phase 18 Mermaid node `S6` was missing the `✅` mark carried by completed nodes S1–S5; fixed by appending `✅` to the node label and amended into the unpushed `docs:` commit.
+  All other checklist items PASS or SKIP (no acceptance-criteria section; `service.ts` was not a target of any prior Phase 18 step, so no cross-step invariant at risk).
+- Next step: `/ship-issue`.

package/package.json

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

package/src/index.ts

@@ -28,6 +28,7 @@ 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 } from "#src/lifecycle/subagent-manager";
+import { CompositeSubagentObserver } from "#src/observation/composite-subagent-observer";
 import { type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
 import { SubagentEventsObserver } from "#src/observation/subagent-events-observer";
@@ -62,7 +63,6 @@ export default function (pi: ExtensionAPI) {
   // widget dependency — keeping the construction graph a cycle-free DAG.
   const notifications = new NotificationManager(
     (msg, opts) => pi.sendMessage(msg, opts),
-    runtime.agentActivity,
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -76,12 +76,18 @@ export default function (pi: ExtensionAPI) {
   settings.load();
 
   // Observer: receives agent lifecycle notifications and dispatches events/notifications.
-  const observer = new SubagentEventsObserver({
+  const eventsObserver = new SubagentEventsObserver({
     emit: (channel, data) => pi.events.emit(channel, data),
     appendEntry: (customType, data) => pi.appendEntry(customType, data),
     notifications,
   });
 
+  // Fan-out observer: lets the widget subscribe as a second lifecycle consumer
+  // while the manager keeps its single-observer contract. The widget is added
+  // after construction (it needs the manager); the manager consults the observer
+  // only at spawn time, so registering late is safe.
+  const observer = new CompositeSubagentObserver([eventsObserver]);
+
   const subagentSessionDeps: SubagentSessionDeps = {
     io: {
       detectEnv,
@@ -129,8 +135,9 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
 
   // 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);
+  // registered as a lifecycle observer so it self-drives its update timer.
+  const widget = new AgentWidget(manager, registry);
+  observer.add(widget);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
   const toolStart = new ToolStartHandler(widget);
@@ -142,7 +149,7 @@ export default function (pi: ExtensionAPI) {
 
   // ---- Agent tool ----
 
-  pi.registerTool(new AgentTool(manager, runtime, widget, settings, registry, getAgentDir()).toToolDefinition());
+  pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
 
   // ---- get_subagent_result tool ----
 
@@ -157,7 +164,6 @@ export default function (pi: ExtensionAPI) {
   const agentsMenu = new AgentsMenuHandler(
     manager,
     registry,
-    runtime.agentActivity,
     settings,
     new FsAgentFileOps(),
     join(getAgentDir(), "agents"),

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

@@ -0,0 +1,49 @@
+import { debugLog } from "#src/debug";
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/**
+ * Fans out SubagentManager lifecycle notifications to multiple observers.
+ *
+ * Lets the manager keep its single-observer contract while several independent
+ * consumers (event/notification dispatch, the reactive widget) subscribe.
+ * Each delegate is isolated: a throw in one does not suppress the others.
+ */
+export class CompositeSubagentObserver implements SubagentManagerObserver {
+  private readonly delegates: SubagentManagerObserver[];
+
+  constructor(delegates: SubagentManagerObserver[]) {
+    this.delegates = [...delegates];
+  }
+
+  /** Register an additional observer (breaks the widget↔manager construction cycle). */
+  add(observer: SubagentManagerObserver): void {
+    this.delegates.push(observer);
+  }
+
+  onSubagentStarted(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentStarted(record), "onSubagentStarted");
+  }
+
+  onSubagentCreated(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentCreated(record), "onSubagentCreated");
+  }
+
+  onSubagentCompleted(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentCompleted(record), "onSubagentCompleted");
+  }
+
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+    this.dispatch((o) => o.onSubagentCompacted(record, info), "onSubagentCompacted");
+  }
+
+  private dispatch(call: (o: SubagentManagerObserver) => void, label: string): void {
+    for (const o of this.delegates) {
+      try {
+        call(o);
+      } catch (err) {
+        debugLog(`CompositeSubagentObserver.${label}`, err);
+      }
+    }
+  }
+}

package/src/observation/notification.ts

@@ -1,7 +1,6 @@
 import { debugLog } from "#src/debug";
 import { getLifetimeTotal } from "#src/lifecycle/usage";
 import type { Subagent } from "#src/types";
-import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
 /** Details attached to custom notification messages for visual rendering. */
 export interface NotificationDetails {
@@ -77,7 +76,6 @@ export function formatTaskNotification(record: Subagent, resultMaxLen: number):
 export function buildNotificationDetails(
   record: Subagent,
   resultMaxLen: number,
-  activity?: AgentActivityTracker,
 ): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
@@ -86,8 +84,8 @@ export function buildNotificationDetails(
     description: record.description,
     status: record.status,
     toolUses: record.toolUses,
-    turnCount: activity?.turnCount ?? 0,
-    maxTurns: activity?.maxTurns,
+    turnCount: record.turnCount,
+    maxTurns: record.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
     outputFile: record.outputFile,
@@ -127,7 +125,6 @@ export function buildEventData(record: Subagent) {
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
   sendCompletion: (record: Subagent) => void;
-  cleanupCompleted: (id: string) => void;
   dispose: () => void;
 }
 
@@ -141,7 +138,6 @@ export class NotificationManager implements NotificationSystem {
       msg: { customType: string; content: string; display: boolean; details?: unknown },
       opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
     ) => void,
-    private agentActivity: Map<string, AgentActivityTracker>,
   ) {}
 
   cancelNudge(key: string): void {
@@ -153,14 +149,9 @@ export class NotificationManager implements NotificationSystem {
   }
 
   sendCompletion(record: Subagent): void {
-    this.agentActivity.delete(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
   }
 
-  cleanupCompleted(id: string): void {
-    this.agentActivity.delete(id);
-  }
-
   dispose(): void {
     for (const timer of this.pendingNudges.values()) clearTimeout(timer);
     this.pendingNudges.clear();
@@ -193,7 +184,7 @@ export class NotificationManager implements NotificationSystem {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, this.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );

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

@@ -65,10 +65,7 @@ export class SubagentEventsObserver implements SubagentManagerObserver {
 		});
 
 		// Skip notification if result was already consumed via get_subagent_result.
-		if (record.notification?.resultConsumed) {
-			this.notifications.cleanupCompleted(record.id);
-			return;
-		}
+		if (record.notification?.resultConsumed) return;
 
 		this.notifications.sendCompletion(record);
 	}

package/src/runtime.ts

@@ -9,7 +9,6 @@
 import { buildParentSnapshot, type ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { ModelInfo } from "#src/tools/spawn-config";
 import type { SessionContext } from "#src/types";
-import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 
 /**
  * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
@@ -30,11 +29,6 @@ export class SubagentRuntime {
   // ── Session state (was closure-scoped in index.ts) ───────────────────────
   /** Active Pi session context — set on session_start, cleared on session_shutdown. */
   currentCtx: SessionContext | undefined = undefined;
-  /**
-   * Per-agent live activity state shared across the notification system,
-   * widget, and tool handlers. The Map itself is never replaced.
-   */
-  readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
 
   // ── Session-context methods ──────────────────────────────────────────────
 

package/src/service/service.ts

@@ -97,7 +97,10 @@ export interface SubagentsService {
 export const SUBAGENT_EVENTS = {
   STARTED: "subagents:started",
   COMPLETED: "subagents:completed",
-  ACTIVITY: "subagents:activity",
+  FAILED: "subagents:failed",
+  COMPACTED: "subagents:compacted",
+  CREATED: "subagents:created",
+  STEERED: "subagents:steered",
 } as const;
 
 // ---- Accessor functions ----

package/src/tools/agent-tool.ts

@@ -12,22 +12,8 @@ import { buildDetails, buildTypeListText, textResult } from "#src/tools/helpers"
 import { renderAgentResult } from "#src/tools/result-renderer";
 import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
 import type { ParentSessionInfo, Subagent } from "#src/types";
-import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
-import { type UICtx } from "#src/ui/agent-widget";
 import { type AgentDetails, getDisplayName } from "#src/ui/display";
 
-// ---- Shared interfaces (also used by background-spawner and foreground-runner) ----
-
-/**
- * Narrow read/write interface for the agent-tool's agentActivity access.
- * The full Map satisfies this structurally — no wrapper needed.
- */
-export interface AgentActivityAccess {
-	get(id: string): AgentActivityTracker | undefined;
-	set(id: string, tracker: AgentActivityTracker): void;
-	delete(id: string): void;
-}
-
 // ---- Deps interfaces ----
 
 /** Narrow manager interface — only the methods the Agent tool calls. */
@@ -40,24 +26,11 @@ 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;
-}
-
 /** Narrow settings accessor — only the fields the Agent tool reads. */
 export type AgentToolSettings = {
 	readonly defaultMaxTurns: number | undefined;
@@ -73,7 +46,6 @@ 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,
@@ -87,11 +59,8 @@ export class AgentTool {
 		params: Record<string, unknown>,
 		signal: AbortSignal | undefined,
 		onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
-		ctx: any,
+		_ctx: any,
 	) {
-		// Ensure we have UI context for widget rendering
-		this.widget.setUICtx(ctx.ui as UICtx);
-
 		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
 		this.registry.reload();
 
@@ -140,8 +109,6 @@ export class AgentTool {
 		if (config.execution.runInBackground) {
 			return spawnBackground(
 				this.manager,
-				this.widget,
-				this.runtime.agentActivity,
 				{ config, snapshot, parentSession, settings: this.settings },
 			);
 		}
@@ -149,8 +116,6 @@ export class AgentTool {
 		// ---- Foreground execution — stream progress via onUpdate ----
 		return runForeground(
 			this.manager,
-			this.widget,
-			this.runtime.agentActivity,
 			{ config, snapshot, parentSession },
 			signal,
 			onUpdate,

package/src/tools/background-spawner.ts

@@ -1,11 +1,8 @@
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentSpawnConfig } from "#src/lifecycle/subagent-manager";
-import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import { textResult } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
 import type { ParentSessionInfo, Subagent } from "#src/types";
-import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
-import { subscribeUIObserver } from "#src/ui/ui-observer";
 
 /** Narrow manager interface for the background spawner. */
 export interface BackgroundManagerDeps {
@@ -13,12 +10,6 @@ export interface BackgroundManagerDeps {
   getRecord(id: string): Subagent | undefined;
 }
 
-/** Narrow widget interface for the background spawner. */
-export interface BackgroundWidgetDeps {
-  ensureTimer(): void;
-  update(): void;
-}
-
 /** All values the background spawner needs beyond the resolved config. */
 export interface BackgroundParams {
   config: ResolvedSpawnConfig;
@@ -29,17 +20,13 @@ export interface BackgroundParams {
 
 /**
  * Spawn a background agent and return the tool result immediately.
- * Owns: activity tracker creation, UI observer subscription, activity map
- * registration, widget update, and launch message formatting.
+ * Owns: launch message formatting.
  */
 export function spawnBackground(
   manager: BackgroundManagerDeps,
-  widget: BackgroundWidgetDeps,
-  agentActivity: AgentActivityAccess,
   params: BackgroundParams,
 ) {
   const { identity, execution, presentation } = params.config;
-  const bgState = new AgentActivityTracker(execution.effectiveMaxTurns);
 
   let id: string;
   try {
@@ -52,13 +39,6 @@ export function spawnBackground(
       thinkingLevel: execution.thinking,
       isBackground: true,
       invocation: execution.agentInvocation,
-      observer: {
-        onSessionCreated: (agent) => {
-          const sub = agent.subagentSession!;
-          bgState.setSession(sub);
-          subscribeUIObserver(sub, bgState);
-        },
-      },
     });
   } catch (err) {
     return textResult(err instanceof Error ? err.message : String(err));
@@ -66,10 +46,6 @@ export function spawnBackground(
 
   const record = manager.getRecord(id);
 
-  agentActivity.set(id, bgState);
-  widget.ensureTimer();
-  widget.update();
-
   const isQueued = record?.status === "queued";
   return textResult(
     `Agent ${isQueued ? "queued" : "started"} in background.\n` +