@gotgenes/pi-subagents 16.6.0 → 17.0.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [17.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.6.0...pi-subagents-v17.0.0) (2026-06-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* SUBAGENT_EVENTS.ACTIVITY ("subagents:activity") is removed. It was never emitted, so no consumer could act on it, and there is no replacement — the activity tier was removed in Phase 18. Consumers should subscribe to the now-declared FAILED, COMPACTED, CREATED, and STEERED channels instead.
+
+### Features
+
+* reconcile SUBAGENT_EVENTS with emitted channels ([#425](https://github.com/gotgenes/pi-packages/issues/425)) ([ba0c48b](https://github.com/gotgenes/pi-packages/commit/ba0c48b294123c1498db2040b1037adcd7ad4e4e))
+
 ## [16.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.5.0...pi-subagents-v16.6.0) (2026-06-17)
 
 

package/dist/public.d.ts

@@ -154,7 +154,10 @@ interface SubagentsService {
 declare const SUBAGENT_EVENTS: {
     readonly STARTED: "subagents:started";
     readonly COMPLETED: "subagents:completed";
-    readonly ACTIVITY: "subagents:activity";
+    readonly FAILED: "subagents:failed";
+    readonly COMPACTED: "subagents:compacted";
+    readonly CREATED: "subagents:created";
+    readonly STEERED: "subagents:steered";
 };
 /** Publish the SubagentsService on globalThis for cross-extension access. */
 declare function publishSubagentsService(service: SubagentsService): void;

package/docs/architecture/architecture.md

@@ -63,9 +63,8 @@ flowchart TB
 
     subgraph observation["Observation domain"]
         direction TB
-        RecordObserver["record-observer<br/>(stats via events)"]
+        RecordObserver["record-observer<br/>(stats + live activity via events)"]
         Notification["notification<br/>(completion nudges)"]
-        UIObserver["ui-observer<br/>(streaming state)"]
     end
 
     subgraph tools["Tools domain"]
@@ -95,8 +94,8 @@ flowchart TB
     SessionConfig --> Prompts & Env
     AgentTypeRegistry --> DefaultAgents & CustomAgents
     RecordObserver -.->|subscribes| SubagentSession
-    UIObserver -.->|subscribes| SubagentSession
     Widget -.->|polls| SubagentManager
+    SubagentManager -.->|notifies| Widget
 ```
 
 ### Key domain types
@@ -258,7 +257,7 @@ sequenceDiagram
     Asm-->>Factory: SessionConfig
     Factory->>Child: create session + bind extensions
     Factory-->>Ag: SubagentSession (born complete)
-    Note over Ag: agent-observer + ui-observer subscribe to session events
+    Note over Ag: record-observer subscribes to session events
     Ag->>Sub: runTurnLoop(prompt, opts)
     Sub->>Child: prompt + drive turn loop
     Child-->>Sub: result text
@@ -322,6 +321,7 @@ src/
 │   ├── notification.ts             completion nudges
 │   ├── notification-state.ts       per-agent notification tracking
 │   ├── renderer.ts                 notification TUI component
+│   ├── composite-subagent-observer.ts fans manager notifications out to multiple observers
 │   └── subagent-events-observer.ts manager lifecycle observer (event emission + persistence + notification)
 │
 ├── service/                        cross-extension API boundary
@@ -346,10 +346,8 @@ src/
 │   ├── agent-creation-wizard.ts    agent creation (AgentCreationWizard class)
 │   ├── conversation-viewer.ts      scrollable session overlay
 │   ├── message-formatters.ts       pure per-message-type formatters (extracted from conversation-viewer)
-│   ├── agent-activity-tracker.ts   live activity state tracker
 │   ├── agent-file-ops.ts           filesystem abstraction
 │   ├── agent-file-writer.ts        overwrite-guard + write + reload + notify helper
-│   ├── ui-observer.ts              session-event observer for streaming
 │   └── display.ts                  pure formatters and shared types
 │
 └── handlers/                       event handlers
@@ -361,11 +359,11 @@ src/
 
 ### Observation model
 
-Record statistics (tool uses, token usage, compaction counts) are updated by `record-observer.ts`, which subscribes directly to session events.
-UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
-Neither observer wraps or forwards the other — both subscribe directly to the session.
+Record statistics (tool uses, token usage, compaction counts) and live activity (active tools, response text, turn counts) are updated by `record-observer.ts`, which subscribes directly to session events.
+This is the single per-child session subscription — all run state lives on the `Subagent` record.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Subagent.subscribeToUpdates()` and reads messages via `Subagent.messages` — no direct `AgentSession` reference (#277).
+The widget reads agent state by polling the records exposed via `SubagentManager.listAgents()` every 80 ms; that poll loop is now started by the manager's lifecycle notifications (the widget subscribes as a `SubagentManagerObserver` fanned out through `CompositeSubagentObserver`), not by inbound calls from the spawn tools.
+The conversation viewer subscribes to session events via `Subagent.subscribeToUpdates()` and reads messages via `Subagent.messages` — no direct `AgentSession` reference (#277).
 
 ## Cross-extension architecture
 
@@ -483,11 +481,14 @@ If Pi gains a native service registry ([earendil-works/pi#4207]), these accessor
 
 The core emits events on `pi.events` that any extension can observe:
 
-| Channel               | Payload                                     | When                 |
-| --------------------- | ------------------------------------------- | -------------------- |
-| `subagents:started`   | `{ id, type, description }`                 | Agent begins running |
-| `subagents:completed` | `{ id, type, status, result?, error? }`     | Agent finishes       |
-| `subagents:activity`  | `{ id, toolName?, textDelta?, turnCount? }` | Streaming progress   |
+| Channel               | Payload                                                                             | When                                          |
+| --------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- |
+| `subagents:started`   | `{ id, type, description }`                                                         | Agent begins running                          |
+| `subagents:completed` | `{ id, type, description, status, result?, error?, toolUses, durationMs, tokens? }` | Agent finishes successfully                   |
+| `subagents:failed`    | same as `completed` (`buildEventData` shape)                                        | Agent ends in `error`/`stopped`/`aborted`     |
+| `subagents:compacted` | `{ id, type, description, reason, tokensBefore, compactionCount }`                  | Child session compacts                        |
+| `subagents:created`   | `{ id, type, description, isBackground }`                                           | Background agent created (pre-admission)      |
+| `subagents:steered`   | `{ id, message }`                                                                   | Steering message delivered to a running agent |
 
 These are fire-and-forget broadcast events — no request IDs, no reply channels.
 
@@ -965,25 +966,30 @@ Folding the live activity onto the record (the single owner of run state, consis
    Smell: Category C (Law of Demeter).
    Outcome: no consumer references `AgentActivityTracker`.
    Landed: `WidgetAgent` folds the live-activity fields and a `contextPercent` projection; `AgentWidget` projects records; `ConversationViewer`, `AgentsMenuHandler`, `buildDetails`, and `buildNotificationDetails` read off the record; `NotificationSystem.cleanupCompleted` removed; `SubagentEventsObserver` returns early on consumed results; +8 tests (1058 → 1066).
-3. **Delete `AgentActivityTracker` and `ui-observer`; drop the activity map from the runtime and spawn tools.**
+3. **✅ Delete `AgentActivityTracker` and `ui-observer`; drop the activity map from the runtime and spawn tools — complete.**
    ([#422]) Target: `ui/agent-activity-tracker.ts` (delete), `ui/ui-observer.ts` (delete), `runtime.ts`, `tools/foreground-runner.ts`, `tools/background-spawner.ts`.
    The spawn tools stop constructing trackers, subscribing, and populating maps; `SubagentRuntime.agentActivity` is removed.
    Smell: Category A + C. Outcome: −145 LOC, one session subscription per child, runtime holds zero UI state.
-4. **Make the widget self-drive from lifecycle events.**
-   ([#423]) Target: `ui/agent-widget.ts`, `lifecycle/subagent-manager.ts` (observer), `index.ts`.
+   Landed: deleted `agent-activity-tracker.ts` (84) + `ui-observer.ts` (61) and their unit suites; dropped the `agentActivity` parameter from `runForeground`/`spawnBackground`, the `AgentActivityAccess` interface, and the `AgentToolRuntime`/`SubagentRuntime` activity-map fields; the foreground `observer.onSessionCreated` keeps `recordRef`/`fgId` binding and `widget.ensureTimer`; −34 tests (1066 → 1032).
+4. **✅ Make the widget self-drive from lifecycle events — complete.**
+   ([#423]) Target: `ui/agent-widget.ts`, `observation/composite-subagent-observer.ts` (new), `index.ts`.
    The widget starts/stops its timer in response to started/created/completed notifications instead of tool calls; spawn tools no longer call `ensureTimer`/`update`/`markFinished`.
    Smell: Category C (coupling direction).
    Outcome: the widget is a reactive consumer; no inbound calls from core spawn tools.
-5. **Drop the widget and activity-map dependencies from the `subagent` tool.**
+   Landed: `AgentWidget implements SubagentManagerObserver` (starts the 80 ms loop on `onSubagentStarted`/`onSubagentCreated`, re-renders on `onSubagentCompleted`/`onSubagentCompacted`); a new `CompositeSubagentObserver` fans the manager's single observer slot out to `[eventsObserver, widget]` (wired in `index.ts`, keeping `SubagentManager` unchanged); dropped the `widget` parameter and `ForegroundWidgetDeps`/`BackgroundWidgetDeps` interfaces from both spawners, deleted `AgentWidget.markFinished` (redundant with `seedFinishedAgents`), made `ensureTimer` private, and narrowed `AgentToolWidget` to `setUICtx`; +11 tests (1032 → 1043, then −4 with the dropped spawner widget-driving tests → 1039).
+5. **✅ Drop the widget dependency from the `subagent` tool — complete.**
    ([#424]) Target: `tools/agent-tool.ts`, `test/helpers/make-deps.ts`.
-   `AgentTool` loses its `widget` and `agentActivity` constructor params (UICtx capture stays in `ToolStartHandler`); `createToolDeps` sheds the widget and map stubs.
+   `AgentTool` loses its `widget` constructor param (UICtx capture stays in `ToolStartHandler`); `createToolDeps` sheds the widget stub.
+   The activity-map (`agentActivity`) dependency this step originally named was already removed from the tool and runtime in Step 3 ([#422]), so only `widget` remained to drop.
    Smell: Category C/D.
-   Outcome: the LLM tool depends only on manager/runtime/settings/registry; fixture drops 2 fields.
-6. **Reconcile the public event contract.**
+   Outcome: the LLM tool depends only on manager/runtime/settings/registry; fixture drops 1 field.
+   Landed: removed the `widget` constructor param and the redundant `this.widget.setUICtx(ctx.ui)` call from `AgentTool.execute`, deleted the `AgentToolWidget` interface and its `UICtx` import, updated the sole `index.ts` call site, and dropped the `widget` field/stub plus two now-obsolete tests (`agent-tool` UICtx capture, `make-deps` widget defaults) — UICtx capture is pinned by `handlers/tool-start.test.ts`; −2 tests (1039 → 1037).
+6. **✅ Reconcile the public event contract — complete.**
    ([#425]) Target: `service/service.ts`, this document's lifecycle-events table.
    Remove the vacant `ACTIVITY` channel (or emit a real broadcast for it) and add the emitted `failed`/`compacted`/`created` channels so declared constants match emitted events.
    Smell: Category A/E.
    Outcome: declared channels equal emitted channels; no vacant hook.
+   Landed: removed `SUBAGENT_EVENTS.ACTIVITY` (breaking) and added `FAILED`/`COMPACTED`/`CREATED`/`STEERED` — `subagents:steered` (from `steer-tool.ts`) was also emitted-but-undeclared, so all four emitted agent-lifecycle channels are now declared; corrected the stale `subagents:completed` payload in the lifecycle-events table to the real `buildEventData` shape; +1 test (1037 → 1038).
 7. **Consolidate residual test clone families.**
    ([#426]) Target: `test/settings.test.ts` + `test/layered-settings.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/ui/agent-config-editor.test.ts`.
    Extract shared fixtures for the clone families fallow reports that the spine does not already rewrite.
@@ -1010,10 +1016,10 @@ Folding the live activity onto the record (the single owner of run state, consis
 flowchart TB
     S1["1 — Fold metrics + activity onto record (#420) ✅"]
     S2["2 — Migrate readers to record getters (#421) ✅"]
-    S3["3 — Delete tracker + ui-observer, drop activity map (#422)"]
-    S4["4 — Widget self-drives on events (#423)"]
-    S5["5 — Drop widget dep from subagent tool (#424)"]
-    S6["6 — Reconcile public event contract (#425)"]
+    S3["3 — Delete tracker + ui-observer, drop activity map (#422) ✅"]
+    S4["4 — Widget self-drives on events (#423) ✅"]
+    S5["5 — Drop widget dep from subagent tool (#424) ✅"]
+    S6["6 — Reconcile public event contract (#425) ✅"]
     S7["7 — Consolidate test clone families (#426)"]
     S8["8 — Reconsider UI direction, ADR (#427)"]
 

package/docs/plans/0422-delete-activity-tracker-ui-observer.md

@@ -0,0 +1,204 @@
+---
+issue: 422
+issue_title: "pi-subagents: delete AgentActivityTracker and ui-observer, drop the activity map from the core"
+---
+
+# Delete AgentActivityTracker and ui-observer, drop the activity map from the core
+
+## Problem Statement
+
+The activity tier is the UI's live-streaming bookkeeping, but today it lives inside the core.
+A `Map<string, AgentActivityTracker>` sits on the core composition root (`SubagentRuntime`), and the two spawn tools construct trackers, open a second session subscription (`subscribeUIObserver`), and populate or delete the map.
+After Phase 18 Step 2 ([#421]) migrated every reader to the record getters, nothing reads the trackers or the map any longer — they are dead bookkeeping the core still maintains.
+This is the third step of the Phase 18 spine (activity-tier disentanglement): delete `AgentActivityTracker` and `ui-observer`, and remove the activity map from `SubagentRuntime` and the spawn tools.
+
+## Goals
+
+- Delete `src/ui/agent-activity-tracker.ts` and `src/ui/ui-observer.ts` (~145 LOC).
+- Remove `agentActivity` from `SubagentRuntime` (`src/runtime.ts`) and from the `AgentToolRuntime` slice (`src/tools/agent-tool.ts`).
+- Stop constructing trackers, calling `subscribeUIObserver` / `setSession`, and populating or deleting the map in `src/tools/foreground-runner.ts` and `src/tools/background-spawner.ts`.
+- Remove the now-unused `AgentActivityAccess` interface and the `agentActivity` parameter from both spawner functions.
+- Leave each child session with exactly one session subscription (the core's own `record-observer`) and zero UI state on the runtime.
+- Keep the existing test suite green at every commit.
+
+This is **not** a breaking change.
+`AgentActivityTracker`, `ui-observer`, and `SubagentRuntime.agentActivity` are internal symbols — none appear in the public service surface (`src/service/service.ts`) or the settings entry (`src/layered-settings.ts`).
+Observable behavior is unchanged; commits use `refactor:` / `docs:`.
+
+## Non-Goals
+
+- Changing how the widget starts/stops its timer — the spawn tools still call `widget.ensureTimer` / `update` / `markFinished` after this step; that decoupling is Phase 18 Step 4 ([#423]).
+- Dropping the `widget` or activity-map constructor params from the `subagent` tool — that is Phase 18 Step 5 ([#424]).
+- Touching `record-observer.ts`, `SubagentState`, or the record getters added in Steps 1–2.
+- Reconciling the public event contract (Step 6) or any UI-distribution decision (Step 8).
+
+## Background
+
+Relevant modules and their current relationships:
+
+- `src/ui/agent-activity-tracker.ts` — `AgentActivityTracker` class (active tools, response text, turn count, session ref).
+  Constructed per-spawn in both spawner tools; written via transition methods; no longer read after [#421].
+- `src/ui/ui-observer.ts` — `subscribeUIObserver(session, tracker, onUpdate?)` opens a second session subscription parallel to `record-observer` and streams events into the tracker.
+- `src/runtime.ts` — `SubagentRuntime.agentActivity: Map<string, AgentActivityTracker>`, the UI streaming-state map on the core composition root.
+- `src/tools/agent-tool.ts` — declares the `AgentActivityAccess` interface and the `AgentToolRuntime.agentActivity` field; passes `this.runtime.agentActivity` into both spawners.
+- `src/tools/foreground-runner.ts` — constructs `fgState`, calls `setSession` + `subscribeUIObserver`, populates and deletes the map; its `streamUpdate` already reads activity off the record (`recordRef`), not the tracker.
+- `src/tools/background-spawner.ts` — constructs `bgState`, calls `setSession` + `subscribeUIObserver` inside an `observer.onSessionCreated`, populates the map.
+
+The architecture doc records this as Phase 18 Step 3 (`docs/architecture/architecture.md`, roadmap and step-dependency diagram), with the explicit outcome "−145 LOC, one session subscription per child, runtime holds zero UI state."
+
+AGENTS.md constraints that apply:
+
+- Run `pnpm fallow dead-code` locally before pushing — deleting modules can orphan sibling exports.
+- pi-subagents is a narrow core with no UI policy; removing UI bookkeeping from the core moves it in the documented direction (dependency arrows point inward).
+
+## Design Overview
+
+This step is a deletion enabled by Step 2, not a new abstraction.
+The two structural wins are removing an output-argument pattern (`agentActivity.set(...)` / `.delete(...)` writes into a received map) and narrowing two function signatures by dropping the `agentActivity` parameter.
+
+### Foreground runner
+
+The `observer.onSessionCreated` callback stays — it is still the only place `recordRef` and `fgId` are bound mid-flight (while `spawnAndWait` is in progress) and where `widget.ensureTimer()` fires.
+Only the tracker lines are removed.
+The post-change callback:
+
+```typescript
+observer: {
+  onSessionCreated: (agent) => {
+    recordRef = agent;
+    fgId = agent.id;
+    widget.ensureTimer();
+  },
+},
+```
+
+The `fgState` construction, the `unsubUI` variable and its two `unsubUI?.()` cleanup calls, and `agentActivity.set` / `agentActivity.delete` all go.
+`streamUpdate` is unchanged — it already reads `recordRef?.turnCount`, `recordRef?.activeTools`, `recordRef?.responseText`.
+Re-renders are driven by the existing 80 ms spinner interval, which reads fresh record state populated by the core's `record-observer`.
+
+### Background spawner
+
+`onSessionCreated` in the background spawner did **only** tracker work (`bgState.setSession`, `subscribeUIObserver`), so the entire `observer` block is removed from the spawn opts.
+The post-spawn `widget.ensureTimer()` and `widget.update()` calls (outside the observer) stay.
+The `bgState` construction and `agentActivity.set(id, bgState)` go.
+
+### Agent tool
+
+`AgentTool` stops passing `this.runtime.agentActivity` to both spawners (Step "remove param").
+The `AgentActivityAccess` interface, the `AgentToolRuntime.agentActivity` field, and the `import { AgentActivityTracker }` are removed once no caller references them.
+
+### Runtime
+
+`SubagentRuntime.agentActivity` and its `import type { AgentActivityTracker }` are removed, along with the field's doc comment.
+The session-context methods and `createSubagentRuntime` are untouched.
+
+## Module-Level Changes
+
+Source:
+
+- `src/tools/foreground-runner.ts` — remove `AgentActivityTracker` import, `subscribeUIObserver` import, `AgentActivityAccess` import, the `agentActivity` parameter, `fgState`, `unsubUI` (+ both `unsubUI?.()` calls), `agentActivity.set`, `agentActivity.delete`; trim the doc comment that lists "AgentActivityTracker creation, UI observer subscription".
+- `src/tools/background-spawner.ts` — remove `AgentActivityTracker` import, `subscribeUIObserver` import, `AgentActivityAccess` import, the `agentActivity` parameter, `bgState`, the entire `observer` block, `agentActivity.set`; trim the doc comment.
+- `src/tools/agent-tool.ts` — remove `AgentActivityAccess` interface, `AgentToolRuntime.agentActivity` field, `import { AgentActivityTracker }`, and the two `this.runtime.agentActivity` arguments to `spawnBackground` / `runForeground`.
+- `src/runtime.ts` — remove `agentActivity` field (+ doc comment) and `import type { AgentActivityTracker }`.
+- `src/types.ts` — reword the `SubscribableSession` doc comment from "Used by record-observer and ui-observer" to reference `record-observer` only.
+- `src/ui/agent-activity-tracker.ts` — **delete**.
+- `src/ui/ui-observer.ts` — **delete**.
+
+Tests:
+
+- `test/ui/agent-activity-tracker.test.ts` — **delete**.
+- `test/ui/ui-observer.test.ts` — **delete**.
+- `test/tools/foreground-runner.test.ts` — drop the `runtime.agentActivity` argument from every `runForeground(...)` call; remove the "registers activity tracker in agentActivity on session creation" test (redundant with the ensureTimer/markFinished test).
+- `test/tools/background-spawner.test.ts` — drop the `runtime.agentActivity` argument from every `spawnBackground(...)` call; remove the "registers an AgentActivityTracker in agentActivity map" test and the `AgentActivityTracker` import.
+- `test/tools/agent-tool.test.ts` — remove the "registers activity in agentActivity map" test.
+- `test/runtime.test.ts` — remove the "agentActivity map is independently mutable" and "multiple instances are isolated" tests, the two `agentActivity` assertions in "returns correct defaults", and the `AgentActivityTracker` import.
+- `test/helpers/make-deps.ts` — remove the `agentActivity` map construction, the `agentActivity` field on the runtime stub, and the `AgentActivityTracker` import; update the runtime doc comment.
+- `test/helpers/make-deps.test.ts` — remove the "agentActivity is an empty Map on the runtime" test, the "runtime.agentActivity satisfies AgentActivityAccess" test, and the `AgentActivityTracker` import.
+
+Docs:
+
+- `docs/architecture/architecture.md`:
+  - File tree (around line 350) — remove the `agent-activity-tracker.ts` and `ui-observer.ts` entries.
+  - "Observation model" prose (around lines 365–368) — drop the "UI streaming … is handled by `ui/ui-observer.ts`" sentence and the stale "widget reads agent state by polling a shared `Map<string, AgentActivityTracker>`" sentence (the widget reads off records since [#421]).
+  - System diagram (around line 68) — remove the `ui-observer` node.
+  - Sequence-diagram note (around line 261) — drop "+ ui-observer" so it reads "agent-observer subscribes to session events".
+  - Phase 18 roadmap Step 3 entry — mark complete (✅) with a `Landed:` bullet, matching the Steps 1–2 format.
+  - Phase 18 health-metrics table — the "Activity-tier modules slated for removal" row becomes historical; leave the snapshot but ensure the Step 3 `Landed:` bullet records the realized LOC delta.
+- `.pi/skills/package-pi-subagents/SKILL.md`:
+  - Module-dependency-flow block — remove `←─subscribes─ ui-observer` from the `record-observer ─subscribes─→ AgentSession` line.
+  - Domain table — UI directory count `12 → 10`; domain header "seven domains (59 files)" → "(57 files)".
+
+Historical docs under `docs/plans/`, `docs/retro/`, and `docs/architecture/history/` reference these symbols as records of past work and are **not** edited.
+
+## Test Impact Analysis
+
+This is a deletion, not an extraction, so it enables no new lower-level tests.
+
+1. New tests enabled: none — the deleted modules' behavior is gone, not relocated.
+2. Tests that become redundant: the tracker/observer unit suites (`agent-activity-tracker.test.ts`, `ui-observer.test.ts`) test deleted code and are removed wholesale; the "registers in agentActivity map" tests across `foreground-runner`, `background-spawner`, `agent-tool`, `runtime`, and `make-deps` test removed state and are deleted.
+3. Tests that must stay: the spawner result-text tests, the `ensureTimer` / `markFinished` / `update` widget-driving tests, the foreground streaming-`onUpdate` test, and the runtime session-context tests — they exercise behavior that survives this step.
+
+## Invariants at risk
+
+This step touches surfaces refactored by Phase 18 Steps 1–2.
+The relevant prior `Landed:` invariants and the tests that pin them:
+
+- "no consumer references `AgentActivityTracker`" (Step 2 outcome) — pinned by the type checker: after this step the symbol is deleted, so any surviving reference fails `pnpm run check`.
+  The foreground `streamUpdate` reading off `recordRef` (Step 2) must remain — covered by `test/tools/foreground-runner.test.ts` "calls onUpdate with streaming details while running".
+- "`Subagent` is the single home for all run state; getters available" (Step 1 outcome) — unchanged here; the getters keep their existing coverage in `test/lifecycle/` and `test/observation/`.
+- Foreground re-render after dropping the second subscription — pinned by the streaming-`onUpdate` test (spinner-driven tick), confirming re-renders survive without `subscribeUIObserver`.
+
+No new test is required; the type checker plus the surviving streaming test cover the at-risk invariants.
+
+## TDD Order
+
+This is primarily code deletion; each step is a `refactor:`/`docs:` commit that keeps `pnpm run check` and the full suite green.
+Steps are ordered so no commit leaves a dangling type reference.
+
+1. **Remove tracker wiring + the `agentActivity` parameter from the spawners.**
+   Edit `foreground-runner.ts` and `background-spawner.ts` to drop tracker construction, `subscribeUIObserver`/`setSession`, map writes, and the `agentActivity` parameter; update the two `AgentTool` call sites; update `foreground-runner.test.ts` and `background-spawner.test.ts` (drop the arg, remove the "registers tracker" tests and the `AgentActivityTracker` import in the background test).
+   The parameter removal cascades to call sites and tests at the type level, so they land together.
+   Run `pnpm run check` immediately after — shared-signature change.
+   Commit: `refactor: stop wiring activity trackers in the spawn tools (#422)`.
+
+2. **Remove the activity map from the runtime and the agent-tool slice.**
+   Delete `SubagentRuntime.agentActivity` (`runtime.ts`), the `AgentActivityAccess` interface, the `AgentToolRuntime.agentActivity` field, and the `AgentActivityTracker` import in `agent-tool.ts`; update `make-deps.ts` (drop the map + field), and all tests reading the field (`runtime.test.ts`, `make-deps.test.ts`, `agent-tool.test.ts`).
+   Removing the field and `AgentActivityAccess` export breaks every reader at the type level, so all consumer + test updates land in this commit.
+   Run `pnpm run check` immediately after.
+   Commit: `refactor: drop the activity map from the runtime and agent tool (#422)`.
+
+3. **Delete the dead modules and their tests.**
+   Delete `src/ui/agent-activity-tracker.ts`, `src/ui/ui-observer.ts`, `test/ui/agent-activity-tracker.test.ts`, `test/ui/ui-observer.test.ts`; reword the `SubscribableSession` comment in `types.ts`.
+   Run `pnpm fallow dead-code` to confirm no sibling export (e.g. `SessionLike`, `SubscribableSession`) was orphaned.
+   Commit: `refactor: delete AgentActivityTracker and ui-observer (#422)`.
+
+4. **Update the architecture doc and package skill.**
+   Apply the doc edits listed in Module-Level Changes (file tree, observation-model prose, system + sequence diagrams, Phase 18 Step 3 ✅ + `Landed:` bullet, SKILL.md flow diagram and domain counts).
+   Verify any touched Mermaid renders (load the `mermaid` skill).
+   Commit: `docs: mark Phase 18 Step 3 complete and remove activity-tier references (#422)`.
+
+## Risks and Mitigations
+
+- **Foreground re-render cadence.**
+  Dropping `subscribeUIObserver` removes event-driven re-renders; updates now rely solely on the 80 ms spinner poll.
+  The displayed content is identical within ≤80 ms latency (the poll reads the same record the core observer populates), and the spinner already ran at this cadence — no perceptible regression.
+  Pinned by the streaming-`onUpdate` test.
+- **Stale doc references.**
+  The architecture doc and SKILL.md describe the activity map as current state.
+  Mitigation: Step 4 grep-driven sweep; the file tree, prose, and two diagrams are all listed explicitly.
+- **Orphaned sibling exports.**
+  Deleting the modules could orphan `SessionLike` or `SubscribableSession`.
+  Verified during planning: both remain used (`SessionLike` by `subagent-session.ts`; `SubscribableSession` by `record-observer.ts`, `subagent-session.ts`, `types.ts`).
+  Mitigation: `pnpm fallow dead-code` in Step 3.
+- **Commit ordering.**
+  Removing the field before the spawners stop passing it would break the build.
+  Mitigation: Step 1 (stop passing) strictly precedes Step 2 (remove field).
+
+## Open Questions
+
+None blocking.
+Whether the widget should self-drive from lifecycle events (so the spawners no longer call `ensureTimer`/`update`/`markFinished`) is deferred to Phase 18 Step 4 ([#423]).
+
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424