@gotgenes/pi-subagents 16.5.0 → 17.0.0

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

@@ -0,0 +1,166 @@
+---
+issue: 424
+issue_title: "pi-subagents: drop the widget and activity-map dependencies from the subagent tool"
+---
+
+# Drop the widget dependency from the subagent tool
+
+## Problem Statement
+
+The LLM-facing `subagent` tool's real concern is dispatch, yet `AgentTool` still takes a `widget` constructor dependency and calls `this.widget.setUICtx(ctx.ui)` at the start of `execute`.
+Every `AgentTool` unit test has to stub the widget through `createToolDeps` — testability friction that marks the domain seam.
+Now that the widget self-drives its timer from lifecycle notifications (Phase 18 Step 4, [#423]) and `ToolStartHandler` already captures the UI context on every `tool_execution_start`, the tool no longer needs the widget at all.
+
+Note: the issue title and the roadmap entry for this step also mention an `agentActivity` / activity-map dependency, but that was already removed from `AgentTool` and the runtime in Phase 18 Step 3 ([#422]).
+The only remaining dependency to drop is `widget`.
+This plan corrects that stale wording where it appears in the roadmap.
+
+## Goals
+
+- Remove the `widget` constructor parameter from `AgentTool`; the tool depends only on manager / runtime / settings / registry / agentDir.
+- Remove the now-redundant `this.widget.setUICtx(ctx.ui)` call from `AgentTool.execute` — UICtx capture stays in `ToolStartHandler`.
+- Delete the `AgentToolWidget` interface and the `UICtx` import that only that interface used.
+- Drop the `widget` field, its stub, and the `AgentToolWidget` import from the `createToolDeps` fixture.
+- Update the `index.ts` call site and all affected tests in the same commit (the constructor-signature change breaks them at typecheck time).
+- This change is **not breaking** — `AgentTool` is internal (the package's only public exports are the service and settings entries), and observable behavior is preserved because `ToolStartHandler` already captures UICtx before the tool executes.
+
+## Non-Goals
+
+- No change to `ToolStartHandler`, `AgentWidget`, or the `UICtx` type itself (it stays in `src/ui/agent-widget.ts`, consumed by the widget and `ToolStartHandler`).
+- No change to `foreground-runner.ts` / `background-spawner.ts` (their widget driving was already removed in [#423]).
+- No work on Phase 18 Steps 6–8 ([#425], [#426], [#427]) — the public-event-contract reconciliation, test-clone consolidation, and UI-direction ADR are separate steps.
+
+## Background
+
+Relevant modules and their current state:
+
+- `src/tools/agent-tool.ts` — `AgentTool` constructor signature is `(manager, runtime, widget, settings, registry, agentDir)`.
+  `execute` opens with `this.widget.setUICtx(ctx.ui as UICtx)`.
+  The file defines the narrow `AgentToolWidget` interface (`setUICtx` only, already narrowed in [#423]) and imports `UICtx` from `#src/ui/agent-widget` solely for that interface and the cast.
+- `src/handlers/tool-start.ts` — `ToolStartHandler.handleToolExecutionStart` already calls `this.widget.setUICtx(ctx.ui)` then `this.widget.onTurnStart()`.
+  `tool_execution_start` fires before any tool's `execute`, so the widget already has the current UICtx by the time `AgentTool.execute` runs.
+  This handler is wired in `index.ts` and is the canonical UICtx-capture site.
+- `src/index.ts:152` — the sole `new AgentTool(...)` call site, passing `widget` as the third argument.
+  `widget` is still constructed and registered as a lifecycle observer (`observer.add(widget)`) and passed to `ToolStartHandler` — those usages stay.
+- `test/helpers/make-deps.ts` — `createToolDeps` builds an `AgentToolFixture` with a `widget` field stub (`{ setUICtx: vi.fn() }`) and imports `AgentToolWidget`.
+- `test/helpers/make-deps.test.ts` — has a `describe("widget defaults")` block asserting the stub.
+- `test/tools/agent-tool.test.ts` — `makeTool` passes `deps.widget`; the test `"sets UI context on runtime at start of execute"` asserts `deps.widget.setUICtx` was called.
+
+AGENTS.md constraint: pi-subagents is a minimal core whose dependency arrows point inward.
+Removing an outbound widget dependency from the LLM tool moves the package further toward "UI is a pure consumer of broadcast events," which is the stated precondition for the Phase 18 UI-direction decision.
+
+## Design Overview
+
+This is a purely subtractive refactor — no new collaborator, no new interface, no moved behavior.
+The widget already receives its UICtx from `ToolStartHandler` on every turn's first tool execution, so the tool's own `setUICtx` call is redundant.
+
+`AgentTool.execute` after the change opens directly with the registry reload:
+
+```typescript
+async execute(toolCallId, params, signal, onUpdate, ctx) {
+	// Reload custom agents so new .pi/agents/*.md files are picked up without restart
+	this.registry.reload();
+	const config = resolveSpawnConfig(params, this.registry, this.runtime.getModelInfo(), this.settings);
+	// ... unchanged
+}
+```
+
+The `ctx` parameter is still required by the `defineTool` `execute` signature; the tool simply no longer reads `ctx.ui`.
+
+New constructor signature:
+
+```typescript
+constructor(
+	private readonly manager: AgentToolManager,
+	private readonly runtime: AgentToolRuntime,
+	private readonly settings: AgentToolSettings,
+	private readonly registry: AgentTypeRegistry,
+	private readonly agentDir: string,
+) { /* unchanged body */ }
+```
+
+Edge cases:
+
+- UICtx availability — `tool_execution_start` always precedes `execute`, so removing the tool's capture loses no coverage; the widget is registered as an observer and already has the UICtx when it renders.
+- No behavior depends on the tool calling `setUICtx` twice per turn; the second call (in the tool) was idempotent for the same `ctx.ui` and a no-op when unchanged.
+
+## Module-Level Changes
+
+- `src/tools/agent-tool.ts`
+  - Remove the `import { type UICtx } from "#src/ui/agent-widget";` line.
+  - Remove the `AgentToolWidget` interface (and its doc comment).
+  - Remove the `private readonly widget: AgentToolWidget` constructor parameter.
+  - Remove the `this.widget.setUICtx(ctx.ui as UICtx);` statement and its comment from `execute`.
+- `src/index.ts`
+  - Update line 152: `new AgentTool(manager, runtime, settings, registry, getAgentDir())` (drop `widget`).
+  - Leave the `widget` construction, `observer.add(widget)`, and `new ToolStartHandler(widget)` wiring unchanged.
+- `test/helpers/make-deps.ts`
+  - Drop `AgentToolWidget` from the imports from `#src/tools/agent-tool`.
+  - Remove the `widget: AgentToolWidget` field from `AgentToolFixture` (and its doc comment).
+  - Remove the `const widget: AgentToolWidget = { setUICtx: vi.fn() };` stub and the `widget,` entry in the returned object.
+- `test/helpers/make-deps.test.ts`
+  - Remove the `describe("widget defaults", ...)` block.
+- `test/tools/agent-tool.test.ts`
+  - Update `makeTool` to drop `deps.widget` from the `new AgentTool(...)` call.
+  - Remove the `"sets UI context on runtime at start of execute"` test (UICtx capture is covered by `test/handlers/tool-start.test.ts`).
+- `docs/architecture/architecture.md`
+  - Mark Phase 18 Step 5 complete (✅) with a `Landed:` bullet, mirroring the Step 4 entry.
+  - Correct the stale `agentActivity` mention in the Step 5 description (line ~979) — only the `widget` param remains to drop.
+  - Update the step dependency diagram node `S5` to the completed (✅) marker.
+
+Grep confirmation performed during planning: `AgentToolWidget` appears only in `src/tools/agent-tool.ts` and `test/helpers/make-deps.ts`; the `UICtx` type stays in use by `src/ui/agent-widget.ts`, `src/handlers/tool-start.ts` (via `unknown`), and `test/ui/agent-widget.test.ts`.
+No `package-*/SKILL.md` references `AgentToolWidget` or the tool's widget dependency.
+
+## Test Impact Analysis
+
+1. New tests enabled: none required — this is a subtractive refactor, not a new seam.
+   The remaining `AgentTool` tests get simpler (no widget stub to thread).
+2. Tests that become redundant:
+   - `test/tools/agent-tool.test.ts` → `"sets UI context on runtime at start of execute"` — the tool no longer captures UICtx; `test/handlers/tool-start.test.ts` (`"calls setUICtx with the context's ui"`) already pins that behavior on its true owner.
+     Remove it.
+   - `test/helpers/make-deps.test.ts` → `describe("widget defaults")` — the fixture no longer has a widget field.
+     Remove it.
+3. Tests that must stay as-is:
+   - `test/handlers/tool-start.test.ts` — genuinely exercises UICtx capture, now the sole owner of that responsibility.
+   - `test/ui/agent-widget.test.ts` — exercises the widget's own `setUICtx`, unaffected.
+   - All other `AgentTool` dispatch/resume/background/foreground tests — exercise the tool's real concern and only shed the unused widget argument.
+
+## Invariants at risk
+
+Phase 18 Step 4 ([#423]) documented Outcome: "the widget is a reactive consumer; no inbound calls from core spawn tools."
+This step extends that to the LLM tool.
+The invariant that UICtx is captured exactly once per turn by `ToolStartHandler` is pinned by `test/handlers/tool-start.test.ts` (`"calls setUICtx with the context's ui"` and `"calls setUICtx before onTurnStart"`) — both stay green and require no new test.
+No earlier step's `Outcome:` is regressed: the widget's self-driving timer (Step 4) is independent of the tool's removed `setUICtx` call.
+
+## TDD Order
+
+This is a behavior-preserving refactor; the green suite stays green.
+Because removing the constructor parameter breaks the `index.ts` call site, the `make-deps` fixture, and the `agent-tool` tests at typecheck time, all source and test edits land in one commit.
+
+1. **Refactor: drop the widget dependency from `AgentTool`.**
+   Edit `src/tools/agent-tool.ts` (remove the `UICtx` import, `AgentToolWidget` interface, `widget` param, and `setUICtx` call), `src/index.ts` (drop `widget` from the constructor call), `test/helpers/make-deps.ts` (drop the field, stub, and import), `test/helpers/make-deps.test.ts` (remove the widget-defaults block), and `test/tools/agent-tool.test.ts` (drop `deps.widget` from `makeTool`, remove the UICtx test).
+   Run `pnpm run check` and the full package suite.
+   Commit: `refactor: drop the widget dependency from the subagent tool (#424)`.
+2. **Docs: mark Phase 18 Step 5 complete.**
+   Update `docs/architecture/architecture.md` — Step 5 ✅ + `Landed:` bullet, correct the stale `agentActivity` wording, update the `S5` diagram node.
+   Commit: `docs: mark Phase 18 Step 5 complete and drop the tool widget dep (#424)`.
+
+## Risks and Mitigations
+
+- Risk: removing the tool's `setUICtx` loses UICtx for the widget in some path.
+  Mitigation: `tool_execution_start` fires before every `execute`, and `ToolStartHandler` captures UICtx there; the existing handler tests pin this.
+  Run the full suite, not just `agent-tool.test.ts`, since the change touches a shared fixture (`make-deps.ts`).
+- Risk: an orphaned import left behind after deletions (Biome `noUnusedImports` is warning-level, exit 0).
+  Mitigation: re-read `agent-tool.ts` and `make-deps.ts` after editing; confirm `UICtx` and `AgentToolWidget` have no remaining references via grep.
+- Risk: the stale `agentActivity` wording is mistaken for live work to do.
+  Mitigation: this plan explicitly records that `agentActivity` was already removed in [#422]; only `widget` remains.
+
+## Open Questions
+
+None — the scope is fully determined by the established roadmap and the verified current code state.
+
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#425]: https://github.com/gotgenes/pi-packages/issues/425
+[#426]: https://github.com/gotgenes/pi-packages/issues/426
+[#427]: https://github.com/gotgenes/pi-packages/issues/427

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

@@ -0,0 +1,144 @@
+---
+issue: 425
+issue_title: "pi-subagents: reconcile the public SUBAGENT_EVENTS contract with emitted channels"
+---
+
+# Reconcile the public `SUBAGENT_EVENTS` contract with emitted channels
+
+## Problem Statement
+
+The public lifecycle-event contract has drifted out of sync with what the core actually broadcasts on `pi.events`.
+`SUBAGENT_EVENTS.ACTIVITY = "subagents:activity"` is declared in the service surface (`src/service/service.ts`) and the architecture doc's lifecycle-events table, but no module ever emits it — a vacant hook that the architecture's own "no vacant hooks" rule forbids.
+The vacancy hardened in Phase 18 Steps 1–5, which deleted the entire activity tier (`AgentActivityTracker`, `ui-observer`), so there is no streaming-progress source left to broadcast.
+In the other direction, four channels the core does emit — `subagents:failed`, `subagents:compacted`, `subagents:created` (all in `SubagentEventsObserver`), and `subagents:steered` (in `steer-tool.ts`) — are absent from the constant map.
+A consumer reading `SUBAGENT_EVENTS` therefore gets one channel that never fires and misses four that do.
+
+## Goals
+
+- Remove the vacant `SUBAGENT_EVENTS.ACTIVITY` constant.
+  This is a **breaking change** to the public surface: it deletes a key from the exported `SUBAGENT_EVENTS` map, so a consumer referencing `SUBAGENT_EVENTS.ACTIVITY` breaks at the type level on upgrade.
+  Use `feat!:` with a `BREAKING CHANGE:` footer.
+- Add the four emitted agent-lifecycle channels to the constant map: `FAILED`, `COMPACTED`, `CREATED`, `STEERED`.
+- After the change, declared channels equal emitted agent-lifecycle channels — no vacant hook, no undeclared emission.
+- Update the lifecycle-events table in `docs/architecture/architecture.md` to match, and correct the stale `subagents:completed` payload shape while there.
+- Mark Phase 18 Step 6 complete in the architecture roadmap.
+
+## Non-Goals
+
+- Re-introducing a streaming-progress (`activity`) event.
+  The activity tier was deliberately deleted in Steps 1–3; resurrecting it is out of scope and was rejected during planning.
+- Adding the config-domain events (`subagents:settings_loaded`, `subagents:settings_changed`) or the child-session seam events (`subagents:child:*`) to `SUBAGENT_EVENTS`.
+  Those belong to separate domains and already have their own constant homes (settings emitter, `child-lifecycle.ts`); `SUBAGENT_EVENTS` is the agent-lifecycle bus only.
+- The `subagents:record` session entry — it is an `appendEntry` (session persistence), not a `pi.events.emit`, so it is not a channel constant.
+- Changing any event payload shape or emission site.
+  This issue reconciles the *constant map* with what is *already emitted*; emission logic is untouched.
+- Phase 18 Steps 7–8 (test-clone consolidation, UI reconsideration) — separate issues ([#426], [#427]).
+
+## Background
+
+- `src/service/service.ts` declares `SUBAGENT_EVENTS` as an `as const` object — the public, cross-extension channel constants, re-exported through the `.` subpath entry and rolled into `dist/public.d.ts`.
+- `src/observation/subagent-events-observer.ts` emits `subagents:started`, `subagents:completed`, `subagents:failed`, `subagents:compacted`, and `subagents:created`.
+- `src/tools/steer-tool.ts` emits `subagents:steered` with payload `{ id, message }`.
+- The completed/failed payload is produced by `buildEventData(record)` in `src/observation/notification.ts`: `{ id, type, description, result, error, status, toolUses, durationMs, tokens? }`.
+  The architecture doc's current table lists `subagents:completed` as `{ id, type, status, result?, error? }`, which is stale.
+- AGENTS.md / `package-pi-subagents` skill constraint: any change to the public surface must run `pnpm --filter @gotgenes/pi-subagents run verify:public-types` (a CI gate), and sibling packages consume this one from the published registry release, not a workspace symlink.
+- The "no vacant hooks" rule (ADR-0002, architecture doc §519) governs both directions here: admit a surface only when a real consumer/emitter exists.
+
+This is a value-only reconciliation of a shared constant: no new collaborator, no dependency-wiring change, no new parameter on any interface — so the `design-review` dependency-width / Law-of-Demeter checklist surfaces nothing actionable.
+
+## Design Overview
+
+The reconciled constant map:
+
+```typescript
+/** Event channel constants for pi.events subscriptions. */
+export const SUBAGENT_EVENTS = {
+  STARTED: "subagents:started",
+  COMPLETED: "subagents:completed",
+  FAILED: "subagents:failed",
+  COMPACTED: "subagents:compacted",
+  CREATED: "subagents:created",
+  STEERED: "subagents:steered",
+} as const;
+```
+
+The declared set is now exactly the set of agent-lifecycle channels emitted by `SubagentEventsObserver` and `steer-tool.ts`.
+
+Updated lifecycle-events table (`architecture.md`):
+
+| 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 |
+
+The `subagents:activity` row is removed.
+
+### Edge cases
+
+- `as const` preservation: the literal-string value types must stay narrow, so the new keys keep the `as const` assertion.
+  `verify:public-types` confirms the rolled `dist/public.d.ts` exposes the narrowed literal types.
+- No runtime emission changes: the four added constants name channels that are *already* fired, so subscribers wired to the string literals see no behavioral change — only the typed constant is now available.
+
+## Module-Level Changes
+
+- `packages/pi-subagents/src/service/service.ts` — remove the `ACTIVITY` key; add `FAILED`, `COMPACTED`, `CREATED`, `STEERED` to `SUBAGENT_EVENTS`.
+- `packages/pi-subagents/test/service/service.test.ts` — update the `SUBAGENT_EVENTS` assertion: drop the `ACTIVITY` expectation, add expectations for the four new constants.
+- `packages/pi-subagents/docs/architecture/architecture.md` — replace the lifecycle-events table (remove the `activity` row, add `failed`/`compacted`/`created`/`steered`, correct the `completed` payload); mark Phase 18 Step 6 complete with a `✅ … — complete.` prefix and a `Landed:` bullet.
+
+Grep confirmation that no other live reference to the removed symbol exists:
+
+- `grep -rn "SUBAGENT_EVENTS.ACTIVITY\|subagents:activity"` across `src/`, `test/`, and `.pi/skills/package-*/SKILL.md`: the only live hits are `service.ts:100`, the `service.test.ts` assertion, and the `architecture.md` table — all three are updated here.
+  Remaining `subagents:activity` matches live in historical/plan docs (`docs/plans/0048-*`, `docs/architecture/history/`, the structural-analysis finding #6 snapshot) and are intentionally left as historical record.
+- `docs/comparison-with-upstream.md` already lists the lifecycle bus as `created, started, completed, failed, steered, compacted` (no `activity`) — it matches the reconciled set and needs no edit.
+- The architecture structural-analysis finding #6 (the phase-start smell snapshot) is left as-is, consistent with how findings #1–5 remain present-tense snapshots while their steps are marked `✅`.
+
+## Test Impact Analysis
+
+This is a constant-map reconciliation, not an extraction, so no new lower-level test surface opens up.
+
+1. New tests enabled: none beyond the expanded `SUBAGENT_EVENTS` assertion — the change adds no new function or collaborator.
+2. Tests becoming redundant: none.
+   The emission-site tests in `test/observation/subagent-events-observer.test.ts` (which assert `subagents:failed`/`compacted`/`created` are emitted) and the steer-tool test stay — they pin the *emission*, while the service test pins the *declaration*.
+3. Tests that must stay as-is: the observer and steer-tool emission tests — they genuinely exercise the channels the constants now name, and are the other half of the "declared == emitted" invariant.
+
+## Invariants at risk
+
+This step touches the public-contract surface that Step 6 is itself responsible for; no earlier Phase 18 step (1–5) refactored `SUBAGENT_EVENTS`, so there is no prior `Outcome:`/`Landed:` invariant to regress.
+The invariant this step establishes — declared channels equal emitted agent-lifecycle channels — is pinned from both sides:
+
+- Declaration: the updated `test/service/service.test.ts` `SUBAGENT_EVENTS` assertion.
+- Emission: existing `test/observation/subagent-events-observer.test.ts` (`failed`/`compacted`/`created`) and the steer-tool test (`steered`).
+
+## TDD Order
+
+1. **Reconcile the constant map (red → green → commit).**
+   Test surface: `test/service/service.test.ts` — rewrite the `SUBAGENT_EVENTS` assertion to expect `STARTED`, `COMPLETED`, `FAILED`, `COMPACTED`, `CREATED`, `STEERED` and to assert `ACTIVITY` is absent (`expect("ACTIVITY" in SUBAGENT_EVENTS).toBe(false)` or drop the import-time reference).
+   This fails to compile/assert against the current map (red).
+   Then edit `src/service/service.ts`: remove `ACTIVITY`, add the four new keys (green).
+   Run `pnpm --filter @gotgenes/pi-subagents run check`, `pnpm --filter @gotgenes/pi-subagents run test`, and `pnpm --filter @gotgenes/pi-subagents run verify:public-types` (public-surface gate).
+   Commit: `feat!: reconcile SUBAGENT_EVENTS with emitted channels (#425)` with a `BREAKING CHANGE:` footer noting the removal of `SUBAGENT_EVENTS.ACTIVITY` and the migration (subscribe to the emitted channel constants `FAILED`/`COMPACTED`/`CREATED`/`STEERED`; there is no replacement for `ACTIVITY` — the activity tier was removed in Phase 18).
+2. **Update the architecture doc (commit, no test).**
+   Replace the lifecycle-events table and correct the `completed` payload; mark Phase 18 Step 6 `✅ … — complete.` with a `Landed:` bullet.
+   Run `pnpm --filter @gotgenes/pi-subagents run lint` (rumdl).
+   Commit: `docs: reconcile lifecycle-events table with SUBAGENT_EVENTS (#425)`.
+
+## Risks and Mitigations
+
+- **Risk:** the breaking removal of `ACTIVITY` surprises a consumer.
+  **Mitigation:** the constant was never emitted, so no consumer could meaningfully act on it; the `BREAKING CHANGE:` footer documents the removal and the absence of a replacement, and release-please carries it to the CHANGELOG and the issue close comment.
+- **Risk:** the rolled `dist/public.d.ts` drifts from the source `as const` shape.
+  **Mitigation:** `verify:public-types` packs the tarball and type-checks a throwaway consumer against both entries — run it in Step 1 before committing.
+- **Risk:** stale `subagents:activity` references linger in docs.
+  **Mitigation:** the Module-Level Changes grep enumerates every live vs. historical hit; only the three live references are edited, historical snapshots are intentionally preserved.
+
+## Open Questions
+
+None.
+The two design choices (remove vs. emit `ACTIVITY`; three vs. four added channels) were resolved during planning: remove `ACTIVITY`, and declare all four emitted agent-lifecycle channels (`failed`/`compacted`/`created`/`steered`).
+
+[#426]: https://github.com/gotgenes/pi-packages/issues/426
+[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/retro/0420-fold-run-metrics-live-activity-onto-record.md

@@ -43,3 +43,48 @@ Full suite green; type check and lint clean; zero dead code.
 - WARN finding: `package-pi-subagents` SKILL.md `Observation` domain row description ("Session-event stats") is now slightly incomplete for `record-observer` (it also accumulates live-activity fields).
   Intentionally deferred per the planning-stage decision — no symbol removed, and the description will be updated in Step 2 ([#421]) when the observer's role is fully defined after the reader migration.
 - Pre-completion reviewer verdict: **WARN** (one non-blocking finding, deferred per retro).
+
+## Stage: Final Retrospective (2026-06-17T17:40:39Z)
+
+### Session summary
+
+Shipped Phase 18 Step 1 across planning, TDD (3 red→green→commit cycles, +27 tests), and release (`pi-subagents` v16.5.0).
+The code work was clean and rework-free; all friction was in markdown-lint surfacing late — two separate doc-lint failures (one pre-existing, one introduced) escaped the baseline and post-TDD gates and were caught only by the pre-completion reviewer and the ship-stage lint, each requiring a fix commit.
+
+### Observations
+
+#### What went well
+
+- The `pre-completion-reviewer` safety net earned its keep: it caught the pre-existing `MD051` broken-fragment links in `phase-17-core-consolidation.md` (introduced earlier by `e4d92535`, unrelated to this issue) before the push, returning FAIL on the first run.
+  Without it the broken links would have shipped.
+- TDD execution was textbook: each of the 3 steps followed red→green→commit with no rework to production code, the `maxTurns`-via-`execution` delegation decision from planning held, and the "vacuously-passing" observer tests (verified in the retro) correctly converted to real assertions once the observer was implemented.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (gate-caught, at ship) — wrote a second `[#421]:` link-reference definition into the retro file when appending the TDD stage entry via `Write` full-content, tripping `MD053` (duplicate definition).
+  The `markdown-conventions` skill states this rule verbatim ("Link reference definitions are file-scoped … a duplicate trips MD053").
+  Impact: one fix commit at ship time (`80d4d050`), caught by the root `pnpm run lint` pre-push gate rather than during TDD (no lint runs after stage-notes writing).
+- `missing-context` (self-identified during ship investigation) — the TDD green-baseline lint was run package-scoped (`pnpm --filter @gotgenes/pi-subagents run lint`), which **silently passes** on `MD051` cross-file fragment failures.
+  Verified empirically: package `lint:md` (`rumdl check *.md docs/**/*.md`) returns "No issues" on the broken fragment, while root `rumdl check .` exits 1 on it — the cross-file fragment target (`../architecture.md`) is only resolved on a repo-root tree walk.
+  Impact: the pre-existing `MD051` failure slipped past the baseline gate (whose job is to catch exactly that) and surfaced mid-TDD via the reviewer, costing a fix commit (`86ed0c81`) and a reviewer FAIL/re-dispatch cycle.
+
+#### What caused friction (user side)
+
+- None.
+  The session ran end-to-end without user correction; the operator-authored, roadmap-aligned issue meant no clarification was needed.
+
+### Diagnostic details
+
+- **Model-performance correlation** — two `pre-completion-reviewer` subagent dispatches ran on the agent's configured reviewer model and performed judgment-heavy review work (acceptance criteria, design review, cross-step invariants); appropriate match.
+  No high-cost model was spent on mechanical work and no reasoning-weak model on judgment work.
+- **Feedback-loop gap analysis** — the lint feedback loop fired at the wrong scope and the wrong time: package-scoped at baseline (missed `MD051`), and absent after retro stage-notes writing (missed `MD053` until ship).
+  `pnpm run check` and `pnpm run test` were run incrementally per step and caught everything they should; only the markdown-lint loop was misconfigured.
+- **Escalation-delay / unused-tool** — no `rabbit-hole` friction; no lens-2 or lens-3 findings.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — "Verify green baseline" step 2 and "After the last TDD step" step 3 now specify `pnpm run lint` runs **from the repo root**, with a one-clause rationale that package-scoped lint silently passes on `MD051` cross-file fragments and cross-package issues (Proposal 1).
+2. Proposal 2 (an `MD053` duplicate-link-definition reminder in the retro-writing prompts) was declined — the rule already exists verbatim in the `markdown-conventions` skill, so a prompt clause would duplicate it.
+3. Follow-up (post-retro): `#420` completed Phase 18 Step 1 but the roadmap Steps section was not marked done until the operator noticed.
+   Added a roadmap-step-status check so this is caught going forward: a WARN bullet in `pre-completion-reviewer.md` §2c (backstop), and a proactive step in `.pi/prompts/tdd-plan.md` step 7 and `.pi/prompts/build-plan.md` "After the last step" — mark the completed roadmap step done (`✅`/`Landed:`) and update the phase status row.
+   Also marked Step 1 complete in `architecture.md` (Steps list, dependency diagram node, phase table row → "In progress").

package/docs/retro/0421-migrate-activity-readers-to-record-getters.md

@@ -0,0 +1,105 @@
+---
+issue: 421
+issue_title: "pi-subagents: migrate activity-tracker readers to the record getters"
+---
+
+# Retro: #421 — Migrate activity-tracker readers to the record getters
+
+## Stage: Planning (2026-06-17T00:00:00Z)
+
+### Session summary
+
+Produced a 5-step TDD plan for Phase 18 Step 2 — migrating the five activity readers (`widget-renderer`, `conversation-viewer`, `agent-menu`, `foreground-runner`, `notification`) off `AgentActivityTracker` and onto the `Subagent` getters added in Step 1 ([#420]).
+The plan files at `packages/pi-subagents/docs/plans/0421-migrate-activity-readers-to-record-getters.md`.
+
+### Observations
+
+- **Two design forks surfaced and were resolved with the operator** via `ask_user`. (1) Finished agents currently show **no** turn count because the tracker is deleted on completion; reading off the record (which persists `turnCount`) makes finished lines show `⟳N`.
+  Operator accepted this as the more-correct behavior — so the widget step is `feat:`, not `refactor:`. (2) How `WidgetAgent` exposes context percent: chose a precomputed `contextPercent` **field** + a `Subagent` → `WidgetAgent` projection in `AgentWidget` (over a `getContextPercent()` method on the snapshot), honoring the renderer's pure-data contract and dropping its `getSessionContextPercent(session)` reach-through.
+  Operator's steer: "no sacred cows, especially in the UI — make the change that makes the change easy, then make the easy change."
+- **Scope boundary with Step 3 ([#422]).**
+  The producer plumbing (`foreground-runner` / `background-spawner` constructing trackers, `subscribeUIObserver`, the `runtime.agentActivity` map) stays — it is removed in Step 3.
+  But the reader-held map deps in `notification`, `agent-widget`, and `agent-menu` are removed **here**, because Step 3's target list does not include those files.
+  This means `cleanupCompleted` (which only deleted a map entry) becomes vestigial and is removed from `NotificationSystem`, rippling to `SubagentEventsObserver`.
+- **Transient map leak between Steps 2 and 3** is noted as an accepted risk: after this step the runtime map is write-only and read by nobody, so it is inert until Step 3 deletes it.
+- **Prep step (tidy-first):** Step 1 adds `turnCount` / `activeTools` / `responseText` / `maxTurns` shorthands to `createTestSubagent` so the reader-migration tests can seed activity on records.
+- **Living-doc updates identified:** `.pi/skills/package-pi-subagents/SKILL.md` line 56 (`widget ─polls─→ AgentActivityTracker map`) and the architecture roadmap's Phase 18 Step 2 `Landed:` line.
+  Completed historical plans under `docs/plans/` are point-in-time records and are not edited.
+- **Shared-signature commits** flagged for `pnpm run check`: the widget step (`renderWidgetLines`) and the notification step (`NotificationSystem` + `index.ts` construction).
+  Both `buildDetails` call sites and both viewer/menu constructor call sites must land in the same commit as their signature changes.
+
+[#420]: https://github.com/gotgenes/pi-packages/issues/420
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+
+## Stage: Implementation — TDD (2026-06-17T17:00:00Z)
+
+### Session summary
+
+All 5 TDD cycles completed in one session.
+The five activity readers (`widget-renderer`, `conversation-viewer`, `agent-menu`, `foreground-runner`, `notification`) were migrated off `AgentActivityTracker` and onto the `Subagent` record getters added in Phase 18 Step 1.
+Test count went from 1058 to 1066 (+8).
+
+### Observations
+
+- **Step 2 (widget)** introduced the `WidgetAgent` → activity-field fold and the `AgentWidget.toWidgetAgent` projection.
+  The accepted behavior change (finished agents now show `⟳N` from the persisted record) landed as `feat:` as planned.
+  `renderWidgetLines` drops `activityMap`; renderer is now a pure function of plain data with no SDK-type reach.
+- **Step 3 (viewer + menu)** was straightforward once `ConversationViewer` dropped `activity?: AgentActivityTracker`; the streaming indicator now reads `this.record.activeTools` / `this.record.responseText` directly.
+  `AgentActivityReader` interface removed; `AgentsMenuHandler` constructor lost one parameter.
+- **Step 4 (buildDetails + foreground runner)** required care around the pre-`onSessionCreated` phase: `streamUpdate` falls back to `recordRef?.turnCount ?? 1`, `execution.effectiveMaxTurns`, empty `Map()`, and `""` before the record reference is assigned.
+  The `AgentTool` resume call site (`buildDetails(base, record)`) was already correct and needed no change.
+- **Step 5 (notifications)** removed `NotificationSystem.cleanupCompleted` entirely (it only deleted a map entry).
+  `SubagentEventsObserver.onSubagentCompleted` now returns early on `resultConsumed` rather than calling the removed method.
+  The `NotificationManager` constructor drops the `agentActivity: Map` argument; `index.ts` needed one arg removed.
+- **Post-commit SKILL.md fix**: the pre-completion reviewer (WARN) flagged that `subagent-events-observer.ts` was missing from the Observation domain table; fixed in a follow-up `docs:` commit.
+- **Pre-completion reviewer**: WARN (non-blocking).
+  Reviewer warning: SKILL.md Observation domain table listed 4 modules and omitted `subagent-events-observer.ts`; corrected before writing these notes.
+
+## Stage: Final Retrospective (2026-06-17T18:30:00Z)
+
+### Session summary
+
+Shipped Phase 18 Step 2 across one continuous session (planning, TDD, ship, retro): five activity readers migrated off `AgentActivityTracker` onto `Subagent` record getters, released as `pi-subagents` v16.6.0.
+Execution was clean overall (+8 tests, all deterministic checks green, one-pass CI), but the architecture roadmap's per-step completion marker was missed during TDD and only fixed after the user caught it at ship time.
+
+### Observations
+
+#### What went well
+
+- **`ask_user` design-fork gate during planning paid off downstream.**
+  Resolving the two forks (finished-agent turn-count behavior change; `contextPercent` field-vs-method) up front meant TDD had zero design backtracking — every step landed as planned, including the `feat:`-vs-`refactor:` commit-type split the fork decided.
+- **Lift-and-shift sequencing held.**
+  The prep step (`createTestSubagent` activity shorthands, commit `bcdb81c9`) made the four reader-migration steps mechanical; each shared-signature change (`renderWidgetLines`, `buildDetails`, `NotificationSystem`) landed with all its call sites in one commit, so `pnpm run check` stayed green at every step boundary.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (user-caught) — the architecture roadmap's **per-step** completion marker was not applied during TDD.
+  Step 7 of `/tdd-plan` says "mark that step done (`✅`/`Landed:`) and update the phase status row."
+  I added the `Landed:` line (commit `999e5ecb`) and confirmed the phase status row correctly stayed `In progress`, but did **not** add the `✅` prefix to the step heading or the Mermaid diagram node.
+  The established convention (Step 1 carries `✅` on both its heading and its `S1[...]` diagram node) treats the `✅` markers as the completion signal, with `Landed:` an optional detail line.
+  Impact: the user caught it at ship time ("we didn't check off the step in architecture.md in the phase Steps section"); fixed in commit `47644ff1`, after which ship resumed.
+  Root cause: the prompt phrasing `(✅/Landed:)` reads as either/or, so satisfying `Landed:` felt sufficient.
+- `missing-context` (reviewer gap) — the pre-completion reviewer's roadmap-status check (added in `b8a938d8` for exactly this class of miss) passed the unchecked step.
+  Its report said "Architecture doc has a `Landed:` entry for Step 2; Phase 18 status row correctly remains 'In progress'" — it verified the `Landed:` line and the phase row but never checked the per-step `✅` on the heading and diagram node.
+  Impact: the guard built to catch this exact omission did not, leaving the user as the only backstop.
+- `other` (tool friction) — a multi-edit `Edit` batch on `test/ui/agent-widget.test.ts` (Step 2) was rejected for overlapping `oldText` regions; re-issued as a single non-overlapping edit.
+  Impact: one retry, no rework.
+
+#### What caused friction (user side)
+
+- None substantive.
+  The single user intervention (the architecture step-checkbox catch) was the correct backstop for a gap the automated reviewer should have caught; surfacing it as a redirect rather than a silent fix kept the convention enforced.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the ship stage (CI watch, release-PR merge, issue close) ran on `opencode-go/deepseek-v4-flash`; appropriate for mechanical orchestration, and it executed the `UNSTABLE`-merge `GITHUB_TOKEN` branch correctly.
+  Planning/TDD ran on `anthropic/claude-opus-4-8` / `claude-sonnet-4-6` (judgment-heavy); retro on `claude-opus-4-8`.
+  No quality mismatch — the per-step-checkbox miss occurred during TDD on a high-reasoning model, so it is an instruction-clarity gap, not a model-capability gap.
+- **Feedback-loop gap analysis** — `pnpm run check` ran after each shared-signature step as the plan flagged, and the full suite plus `fallow dead-code` ran before push; verification was incremental, not end-loaded.
+- **Escalation-delay / unused-tool** — no `rabbit-hole` friction; no lens finding.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` (step 7) — disambiguated roadmap-step completion: `✅` on both the step heading and its Mermaid diagram node; `Landed:` is not a substitute; phase status row flips only when every step is done.
+2. `.pi/prompts/build-plan.md` (step 4) — same disambiguation as tdd-plan.
+3. `.pi/agents/pre-completion-reviewer.md` (roadmap-status check) — reviewer now verifies `✅` on both the step heading and diagram node (not just a `Landed:` line) and checks the phase row against the actual step count.

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

@@ -0,0 +1,97 @@
+---
+issue: 422
+issue_title: "pi-subagents: delete AgentActivityTracker and ui-observer, drop the activity map from the core"
+---
+
+# Retro: #422 — Delete AgentActivityTracker and ui-observer, drop the activity map from the core
+
+## Stage: Planning (2026-06-17T00:00:00Z)
+
+### Session summary
+
+Planned Phase 18 Step 3 of the activity-tier disentanglement spine: deleting `AgentActivityTracker` and `ui-observer`, and removing `SubagentRuntime.agentActivity` plus the tracker wiring in the two spawn tools.
+Verified the prerequisites (#420, #421) are both closed and that the trackers/map are now write-only dead state after the reader migration.
+Wrote a four-step plan (two `refactor:` deletion commits, a module-delete commit, a `docs:` sweep) at `packages/pi-subagents/docs/plans/0422-delete-activity-tracker-ui-observer.md`.
+
+### Observations
+
+- The change is **non-breaking** and internal-only: `AgentActivityTracker`, `ui-observer`, and `agentActivity` are absent from the public service surface (`service.ts`) and settings entry, so no `BREAKING CHANGE` footer.
+  Issue author is the operator (`gotgenes`) and the proposed change is unambiguous and roadmap-driven, so the `ask-user` gate was skipped.
+- The foreground `observer.onSessionCreated` callback **stays** — it is still the only place `recordRef`/`fgId` bind mid-flight and where `widget.ensureTimer()` fires; only the tracker lines are stripped.
+  The background `observer` block, by contrast, did only tracker work and is removed entirely.
+- Commit ordering matters: Step 1 (spawners stop passing `agentActivity`) must precede Step 2 (remove the runtime field), or the build breaks.
+  Both the param removal and the field/`AgentActivityAccess` removal cascade to call sites and tests at the type level, so each is folded into a single commit.
+- Re-render cadence: dropping `subscribeUIObserver` removes event-driven foreground re-renders, leaving the existing 80 ms spinner poll.
+  Content is identical within ≤80 ms (the poll reads the same record the core observer populates) — pinned by the streaming-`onUpdate` test, noted as a risk not a regression.
+- Found a **pre-existing stale doc** from #421: `architecture.md` still says "the widget reads agent state by polling a shared `Map<string, AgentActivityTracker>`", though #421 already moved the widget onto records.
+  Folded that correction into this plan's Step 4 doc sweep alongside the file tree, two Mermaid diagrams, and the SKILL.md domain counts (UI `12 → 10`, header `59 → 57` files).
+- Confirmed no orphaned sibling exports: `SessionLike` (used by `subagent-session.ts`) and `SubscribableSession` (used by `record-observer.ts`, `subagent-session.ts`, `types.ts`) both survive the module deletion; `pnpm fallow dead-code` is the Step 3 backstop.
+
+## Stage: Implementation — TDD (2026-06-17T20:40:00Z)
+
+### Session summary
+
+Executed all four planned steps as a deletion refactor: stripped tracker wiring + the `agentActivity` parameter from the spawners, removed the activity map from `SubagentRuntime`/`AgentToolRuntime`, deleted `agent-activity-tracker.ts` and `ui-observer.ts` (−145 LOC) plus their suites, and swept the architecture doc + SKILL.md.
+Landed in six commits (four planned + one folded test removal + one `style:` lint fixup).
+Test count dropped −34 (1066 → 1032) across 63 files (was 65); `check`, root `lint`, full `test`, and `fallow dead-code` all green.
+
+### Observations
+
+- **Deviation (test removal moved earlier):** the agent-tool "registers activity in agentActivity map" test was planned for Step 2 but had to be removed in Step 1 — once the spawner stops populating the map, the test fails at runtime in that commit.
+  Folded into Step 1 per the testing skill's "account for tests that break" rule.
+- **Deviation (atomic-batch trap):** the Step 2 multi-edit `Edit` on `runtime.ts` was rejected because edit[1] miscounted a decorative `─` rule, which silently dropped edit[0] (the `AgentActivityTracker` import removal).
+  `tsc` passed at Step 2 because the leftover was an elided `import type`; it only surfaced as a tsc/fallow error once Step 3 deleted the module.
+  Removed it in Step 3 and re-read the region after editing.
+  This is exactly the AGENTS.md warning about anchoring on decorative rules.
+- **Lint fixup:** an unused `runtime` destructure remained in one `background-spawner.test.ts` case.
+  It belongs to Step 1's file but HEAD was the `docs:` commit (a fixup must not land in a `docs:` commit, and amending a non-HEAD `refactor:` commit needs a rebase), so it landed as a standalone `style:` commit.
+- **No behavior regression:** foreground re-renders now rely solely on the 80 ms spinner poll (the second `subscribeUIObserver` subscription is gone); pinned by the surviving "calls onUpdate with streaming details while running" test.
+- **Doc correction:** fixed the pre-existing stale `architecture.md` prose that still claimed the widget polls a `Map<string, AgentActivityTracker>` (the widget moved onto records in #421); now reads "polls the records exposed via `SubagentManager.listAgents()`".
+- **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; no warnings.
+
+## Stage: Final Retrospective (2026-06-18T01:19:58Z)
+
+### Session summary
+
+Shipped Phase 18 Step 3 across plan → TDD → ship in three sessions: deleted `AgentActivityTracker` and `ui-observer`, removed the `agentActivity` map from `SubagentRuntime` and both spawn tools (−145 LOC, −34 tests), and swept the architecture doc + SKILL.md.
+Six implementation commits, pre-completion reviewer PASS, CI green, issue closed; no release (all `refactor:`/`style:`/`docs:`).
+Clean hands-off execution — the only user input was one `ask_user` answer ("Release now") and no corrections.
+
+### Observations
+
+#### What went well
+
+- Incremental verification cadence was exemplary: `pnpm run check` ran after every shared-type change (after Step 1, Step 2, and twice in Step 3), not just at end-of-cycle — exactly the feedback-loop discipline the TDD prompt asks for.
+  This caught the Step 2/3 type fallout immediately rather than as a late surprise.
+- The atomic-batch trap (below) was self-identified and the recovery was clean and well-documented — the Step 3 commit body explains why the `runtime.ts` import removal landed there instead of Step 2.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified) — the Step 2 multi-edit `Edit` on `runtime.ts` anchored `edits[1]` on a decorative `─` rule and miscounted it, rejecting the whole atomic batch and silently dropping `edits[0]` (the `AgentActivityTracker` import removal).
+  This is the exact anti-pattern AGENTS.md § "Edit tool batches" warns against ("anchor on adjacent unique code lines rather than the rule itself").
+  The follow-up rule ("after a rejection, re-apply every intended edit and run `pnpm run check`") was also only half-followed: the field edit was re-applied but the import edit was not, and the `check` at Step 2 passed anyway because `tsc` elides an unused `import type`.
+  Impact: the dropped import surfaced only at Step 3 (once the module was deleted) as a tsc/fallow error, costing one investigation cycle and smearing the import removal into the Step 3 commit instead of Step 2.
+- `other` (self-identified) — dropping the `runtime.agentActivity` argument from the `background-spawner.test.ts` calls left one test still destructuring an unused `runtime`.
+  Biome's `noUnusedVariables` is warning-level (exit 0), so it did not fail `lint`; it was caught by comparing the warning count to the green baseline at end-of-cycle.
+  Impact: one extra `style:` commit (could not amend — HEAD was a `docs:` commit).
+
+#### What caused friction (user side)
+
+- None blocking — execution was hands-off.
+  Opportunity, not criticism: the ship stage ran on `opencode-go/deepseek-v4-flash`, a weak model, and that stage carries a real judgment call (is a missing release-please PR expected, or a problem?).
+  It was answered correctly here, but the release-decision judgment on a weak model is a latent risk worth an operator's awareness.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning and TDD ran on `anthropic/claude-opus-4-8` (appropriate: design + commit-sequencing judgment, deviation recovery).
+  The pre-completion reviewer subagent ran to completion (245 s, 26 tool uses) and returned a thorough PASS.
+  Ship ran on `opencode-go/deepseek-v4-flash` — fine for the mechanical push/CI/close flow, but it also made the "no release expected" inference; correct here, latent risk in general (see user-side note).
+- **Escalation-delay tracking** — No `rabbit-hole`s.
+  Both deviations resolved within 1–2 tool calls; no sequence exceeded 5 calls on one error.
+- **Unused-tool detection** — No `missing-context` gaps. `grep` (not `colgrep`) was used throughout planning, correctly — every search was an exact symbol match (`agentActivity`, `AgentActivityTracker`, `subscribeUIObserver`), which is grep's lane per the colgrep decision table.
+- **Feedback-loop gap analysis** — No gap; verification was incremental, not end-only (see "What went well").
+  The one escape (`import type` removal) is a tsc-tolerance gap, not a cadence gap — `check` ran on schedule but cannot flag an unused type import.
+
+### Changes made
+
+1. `AGENTS.md` § "Edit tool batches" — augmented the post-rejection rule with a caveat: `tsc` passes on a dropped `import type` removal (an unused type import is not an error), so re-read the affected region rather than trusting `pnpm run check` alone.