@gotgenes/pi-subagents 18.0.1 → 18.0.2

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

@@ -1,105 +0,0 @@
----
-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

@@ -1,97 +0,0 @@
----
-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.

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

@@ -1,112 +0,0 @@
----
-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

@@ -1,89 +0,0 @@
----
-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

@@ -1,101 +0,0 @@
----
-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`.
-
-## Stage: Final Retrospective (2026-06-18T12:00:00Z)
-
-### Session summary
-
-A single continuous session carried issue #425 from planning through ship in four stages: planned the `SUBAGENT_EVENTS` reconciliation, executed two TDD commits (a `feat!:` constant-map change and a `docs:` table update), passed a WARN-then-resolved pre-completion review, and shipped `pi-subagents-v17.0.0` (major bump from the breaking `ACTIVITY` removal).
-The one notable bump was at ship time: the batch-vs-release question led the user to choose batch, then immediately reverse course ("I have regrets.
-Release it.").
-
-### Observations
-
-#### What went well
-
-- The planning `ask_user` gate caught a real scope gap: the issue body named three missing channels (`failed`/`compacted`/`created`), but exploration of `steer-tool.ts` found a fourth emitted-but-undeclared channel (`subagents:steered`).
-  Surfacing it as a design choice let the operator opt into a fully reconciled `declared == emitted` set rather than shipping the issue's literal-but-incomplete list.
-- The invariant was pinned from both sides — `service.test.ts` for declaration, the existing observer/steer-tool tests for emission — so "declared channels equal emitted channels" is enforced by the suite, not just prose.
-- The pre-completion reviewer caught a genuine inconsistency the deterministic gates missed: the Phase 18 Mermaid node `S6` lacked the `✅` mark that completed nodes `S1`–`S5` carried.
-  A one-character fix, amended cleanly into the unpushed `docs:` commit.
-
-#### What caused friction (agent side)
-
-- `missing-context` (self-identified at retro) — at ship step 4b, the batch-vs-release question fired on the plan's "Phase 18 Step 6 / phased roadmap" framing, but both the issue body ("Independent of the disentanglement spine — can land at any time") and the planning retro recorded an explicit independent-releasability signal.
-  The `ask_user` call presented batch and release as neutral options without surfacing that counter-signal, so the user chose batch and then reversed ("I have regrets.
-  Release it.").
-  Impact: one wasted `ask_user` round-trip, a cancelled `ci_watch`, and a mid-flow correction before the normal release path resumed; no commits had to be redone.
-- `wrong-abstraction` (self-identified) — after the user cancelled the `ci_watch`, I read "cancelled by user" as the GitHub run being cancelled and tried `gh run rerun`, which failed ("already running").
-  Cancelling the watch tool aborts the poll, not the remote run, which was still in progress.
-  Impact: 1 wasted tool call; recovered immediately by re-listing and re-watching.
-
-#### What caused friction (user side)
-
-- The independent-releasability of this step was knowable from the issue body but only surfaced as a reversal after the batch choice.
-  Opportunity, not criticism: when an issue is explicitly carved out as independently shippable, stating "release immediately" up front (or the prompt biasing toward it) avoids the round-trip.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer` on `anthropic/claude-sonnet-4-6` (219s, 37 tool uses); a strong model on judgment-heavy review work — appropriate, no mismatch.
-- **Escalation-delay tracking** — no rabbit-hole exceeded 5 consecutive tool calls; the `gh run rerun` misstep was a single call, recovered next turn.
-- **Unused-tool detection** — none; planning exploration (`Read`/`grep`/`colgrep`) and TDD verification covered the needed context without a missed Explore/`colgrep` opportunity.
-- **Feedback-loop gap analysis** — verification ran incrementally, not just at the end: green-baseline `check`/`lint`/test before TDD, `verify:public-types` before committing the public-surface change in step 1, and the full suite + `check` + root `lint` + `fallow` after step 2.
-
-### Follow-up
-
-The ship-time batch friction prompted a larger design than a retro should land inline: make release batching plan-driven rather than an ad-hoc step-4b question.
-The architecture doc would annotate coherent **release batches** per phase (guidance for the `improvement-discovery` skill / `plan-improvements.md`), `/plan-issue` would read those annotations and write a prominent Release recommendation into the plan, and `/ship-issue` would read that recommendation and confirm with the user **early** (before pull/CI) instead of inferring from prose mid-flow.
-Filed as [#434] for a later `/plan-issue`.
-
-### Changes made
-
-1. Applied a one-sentence carve-out to `.pi/prompts/ship-issue.md` step 4b (skip the batch question when a step is explicitly independently releasable), then **reverted** it after discussion — the file is unchanged.
-   The structured plan-driven approach in [#434] supersedes it.
-2. Created [#434] (`enhancement`) capturing the plan-driven release-batching design across the architecture-doc authoring guidance, `/plan-issue`, and `/ship-issue`.
-3. Appended this Final Retrospective entry to the retro file.
-
-[#434]: https://github.com/gotgenes/pi-packages/issues/434