@gotgenes/pi-subagents 16.6.0 → 17.0.1

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

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

package/docs/retro/0426-consolidate-residual-test-clone-families.md

@@ -0,0 +1,100 @@
+---
+issue: 426
+issue_title: "pi-subagents: consolidate residual test clone families"
+---
+
+# Retro: #426 — pi-subagents: consolidate residual test clone families
+
+## Stage: Planning (2026-06-18T17:48:42Z)
+
+### Session summary
+
+Produced a numbered plan (`docs/plans/0426-consolidate-residual-test-clone-families.md`) for consolidating the residual test clone families in four named `pi-subagents` test files.
+Ran `fallow dupes` to enumerate the live clone groups: 24 test clone groups package-wide, of which the four target files (`test/settings.test.ts` + `test/layered-settings.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/ui/agent-config-editor.test.ts`) contribute exactly 10 — consolidating them lands at 14, below the issue's `<15` target.
+The plan is a test-only refactor verified by the existing suite staying green plus a falling fallow clone count; the follow-up is `/build-plan` (no red→green behavior cycles).
+
+### Observations
+
+- Release: ship independently — the Phase 18 roadmap step 7 carries no `Release: batch` tag and is explicitly "independent of the disentanglement spine."
+- The `testing` skill's rule "do not wrap the system-under-test call in a helper to eliminate a duplication-metric clone" drove the design: consolidate *arrange* only, keep every `loadSettings`/`createSubagentSession`/`showAgentDetail` act written out.
+  For `agent-config-editor` menu cases, `it.each` is the right tool — it keeps the act visible in the table body rather than hiding it in a helper.
+- Three independent consolidations: (1) a new shared `test/helpers/tmp-settings-dirs.ts` fixture for the cross-file settings tmp-dir scaffolding (with paired self-test, per the `test/helpers/*.test.ts` convention); (2) file-local `arrangeFactory`/`defaultDeps` for the `create-subagent-session` post-bind-guard block; (3) `it.each` table + hoisted `filePath` for `agent-config-editor`.
+- Scope deliberately excludes: the production clone in `src/ui/agent-config-editor.ts` (test-only issue), the cross-package `vitest.config.ts` clone, the `5d8dbd48` group spanning `subagent-manager.test.ts` ↔ `subagent.test.ts` (neither is a target file), and all other non-target test clone families.
+- Key risk flagged for build: removing inline `writeGlobal`/`writeProject` may orphan fs imports (`mkdtempSync`/`rmSync`/`mkdirSync`/`writeFileSync`/`tmpdir`/`join`); Biome `noUnusedImports` is warning-level, so step 4 runs `pnpm fallow dead-code` as the backstop.
+- Markdown lint gotcha hit during planning: bare `#N` inline mentions are fine, but reference-style `[#N]` link defs trip `MD053` unless a matching bracket reference exists in the body — kept only the `[#427]` cross-link def.
+
+## Stage: Implementation — Build (2026-06-18T18:14:01Z)
+
+### Session summary
+
+Executed all four refactor steps plus the architecture doc-flip across four commits.
+Extracted two shared test fixtures (`test/helpers/tmp-settings-dirs.ts`, `test/helpers/capture-warn.ts`, each with a paired self-test) and table-drove the `create-subagent-session` post-bind and `agent-config-editor` menu/confirm-remove cases into `it.each`.
+Dropped pi-subagents test clone groups from 24 to 14 (below the `<15` target); full suite green at 1047 tests (was 1038), type check and lint clean, `fallow dead-code` clean.
+
+### Observations
+
+- Pre-completion reviewer: PASS (deterministic checks, assertion-strength preservation, act-visibility, and no-coverage-drop all verified).
+- Deviation 1 — the settings fixture exposes a `dispose()` method instead of the plan's separate `disposeSettingsDirs()` function (Tell-Don't-Ask; the fixture disposes itself).
+- Deviation 2 — added `test/helpers/capture-warn.ts` (`captureWarn`) beyond the plan's tmp-dir-only fixture.
+  The plan's Step 1 verify listed clone group `4003c0e7` (the `console.warn` spy try/finally boilerplate) as expected-gone, but the tmp-dir fixture alone did not address it; the warn-capture helper does, and migrating the spy tests in both files cleared it.
+  Squarely within the issue's "extract shared fixtures for the clone families" intent.
+- Deviation 3 — Step 2's first pass (arrange helpers only) left a transient arrange+assert clone (`62899223`) between the two adjacent post-bind membership tests; folding the three membership cases into one `it.each` with a strong `toEqual` (replacing the prior `toContain` checks) cleared it.
+- Used destructure-to-locals in `settings.test.ts`/`layered-settings.test.ts` (e.g. `({ globalDir: agentDir, projectDir: cwd, ... } = dirs)`) rather than the plan's `dirs.X` member-access sketch — keeps the existing terse test bodies unchanged and lowers edit risk.
+- Dropped one brittle `captureWarn` self-test ("suppresses real stderr") that was actually exercising `vi.spyOn`'s restore-to-original semantics with nested spies, not the helper's behavior.
+- The risk flagged at planning (orphaned `node:fs`/`node:os` imports after removing inline `writeGlobal`/`writeProject`) materialized only in `layered-settings.test.ts` (`mkdtempSync`/`rmSync`/`tmpdir`/`vi` became unused); removed them, and `fallow dead-code` confirmed clean.
+
+## Stage: Final Retrospective (2026-06-18T18:31:04Z)
+
+### Session summary
+
+Planned, built, and shipped #426 in one continuous session: extracted two shared test fixtures (`tmp-settings-dirs.ts`, `capture-warn.ts`) and table-drove four clone families into `it.each`, dropping pi-subagents test clone groups from 24 to 14.
+CI green, issue closed, no release cut (all `test:`/`docs:` commits batch until the next `feat`/`fix`).
+Execution was clean overall; the one recurring friction was the plan over-predicting which clone fingerprints each change would clear.
+
+### Observations
+
+#### What went well
+
+- **Metric-driven feedback loop.**
+  Each build step re-ran `pnpm fallow dupes` and checked the targeted fingerprints (`21d1fb01`, `4003c0e7`, `48ff1484`, …) disappeared before committing.
+  This caught the two prediction gaps (below) immediately rather than at pre-completion, and turned a fuzzy "reduce duplication" goal into a precise per-step pass/fail.
+- **`it.each` strengthened assertions while consolidating.**
+  Folding the `create-subagent-session` post-bind cases into a table let the merged test assert `toEqual(expected)` on the full post-bind set, replacing the prior weaker `toContain` checks — consolidation improved coverage rather than just moving lines.
+- **Pre-completion reviewer verified the real risk.**
+  For a test-refactor the central risk is silent coverage loss; the reviewer explicitly confirmed former-`it`-count equals row-count for every `it.each` and that each act stayed explicit.
+  PASS with nothing to fix.
+
+#### What caused friction (agent side)
+
+- `missing-context` (planning) — the plan's Step 1 *verify* listed clone group `4003c0e7` (the `console.warn` spy try/finally boilerplate) as expected-gone, but the Step 1 *design* only described the tmp-dir fixture, which does not touch that clone.
+  The build discovered the gap and added `capture-warn.ts` + migrated ~7 spy tests mid-step.
+  Impact: one unplanned helper (with self-test) folded into the same commit; no follow-up commit, but the plan-vs-build mismatch was real.
+- `wrong-abstraction` (build, self-corrected) — Step 2's first pass applied arrange helpers (`arrangeFactory`/`defaultDeps`) alone, which left a *new* transient clone (`62899223`) between the two adjacent post-bind tests.
+  Folding the three membership cases into one `it.each` cleared it.
+  Impact: one extra edit+verify iteration within the step; caught by the same-step `fallow dupes` run.
+- `other` (build, trivial) — wrote a brittle `captureWarn` self-test ("suppresses real stderr") that asserted `vi.spyOn` nested-restore semantics rather than the helper's behavior; the test failed immediately and was dropped.
+  Impact: ~2 tool calls, no rework downstream.
+- `other` (ship, trivial) — `git log | grep -P` failed on macOS BSD grep; retried with `grep -o`.
+  Impact: one retry.
+
+#### What caused friction (user side)
+
+- None.
+  The session ran end-to-end (plan → build → ship → retro) without a mid-course correction; the prompts carried enough structure that no strategic intervention was needed.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the entire `/ship-issue` stage ran on `opencode-go/deepseek-v4-flash` (a reasoning-weak model), covering judgment-bearing steps: release-coordination decision, stacked-release detection, and close-comment synthesis.
+  It executed correctly because `/ship-issue` is heavily proceduralized (deterministic checks, explicit decision tree), so the weak model followed the rails without error.
+  Planning/build ran on stronger models (`opus-4-8`/`sonnet-4-6`); retro on `opus-4-8`.
+  No quality defect resulted, but ship-issue does carry real judgment — worth noting that its proceduralization is what absorbed the model mismatch.
+- **Escalation-delay tracking** — no `rabbit-hole`; the two prediction-gap fixes resolved in 1–2 tool calls each via the per-step `fallow dupes` check.
+  No sequence exceeded the 5-call flag.
+- **Unused-tool detection** — none needed; scope was small and fully understood from the planning-stage file reads. `fallow dupes` was the right and sufficient tool.
+- **Feedback-loop gap analysis** — verification ran *incrementally*: `pnpm run check` + `vitest run <file>` + `pnpm fallow dupes` after every step, full suite + `fallow dead-code` at the end.
+  No end-only verification gap.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added a cross-section consistency rule under **Module-Level Changes**: when a plan step's verify criterion names a static-analysis finding (clone fingerprint, dead-code symbol, complexity target) as resolved, the design or Module-Level Changes must map the change that clears it.
+   Motivated by the Step 1 `4003c0e7` prediction gap (the verify step listed it as expected-gone but the design did not address it, forcing the mid-build `capture-warn.ts` addition).

package/docs/retro/0427-reconsider-ui-direction.md

@@ -0,0 +1,102 @@
+---
+issue: 427
+issue_title: "pi-subagents: reconsider the UI direction from first principles (ADR)"
+---
+
+# Retro: #427 — pi-subagents: reconsider the UI direction from first principles (ADR)
+
+## Stage: Planning (2026-06-18T00:00:00Z)
+
+### Session summary
+
+Planned the Phase 18 Step 8 decision-only ADR for the pi-subagents UI direction.
+Two `ask_user` rounds with the operator (their own issue) settled a per-component decision and surfaced a key SDK finding — Pi's `switchSession(sessionPath)` — that reshapes the conversation-viewer direction.
+The plan writes `docs/decisions/0004-reconsider-ui-direction.md` plus an architecture-doc update; no `src/`/`test/` changes (implementation deferred to a separately-planned Phase 19).
+
+### Observations
+
+- **Decision-only ADR → `/build-plan`, not `/tdd-plan`.**
+  The operator chose to record decisions and defer all code to Phase 19, so the plan has a docs-only Build Order, no test cycles.
+- **Per-component decisions recorded:**
+  (A) foreground widget shrinks to background-agents-only;
+  (B) conversation viewer replaced by native session navigation (remove the bespoke `ConversationViewer`);
+  (C) `/agents` menu dissolved — **remove** both agent-management surfaces outright (creation wizard and agent-types config editor; managing definitions belongs in an editor/IDE or a Pi agent, not the menu), re-home running-agent visibility onto the widget + session navigation, extract settings to a focused `/subagents:settings` command;
+  (D) distribution = keep surviving UI in-core (substitutable, _not_ extracted to `@gotgenes/pi-subagents-ui`).
+- **Key SDK finding — `switchSession`.**
+  `@earendil-works/pi-coding-agent@0.79.1` exposes `ExtensionActions.switchSession(sessionPath, { withSession })`.
+  It is a _full active-session takeover_ (fires `session_before_switch`/`session_shutdown`, invalidates the current context), and the switched-to session is interactive (`ReplacedSessionContext.sendUserMessage`).
+  A read-only alternative exists: `loadEntriesFromFile`/`parseSessionEntries` render a transcript without switching.
+  These tensions are recorded as Phase 19 spike gates rather than pretend-resolved — the ADR commits to the _direction_ (native session machinery over a bespoke renderer), not the _mechanism_.
+- **Operator-raised open questions (now Phase 19 entry criteria):** root-continuity during a session switch, view-only vs interactive, parallel-agent navigation gesture, settings command namespace, and confirming the creation-wizard's value is covered by "generate via a Pi agent" before deleting it.
+- **Release:** ship independently — Phase 18 carries no `Release:` batch tag; this issue completes the phase.
+- **Numbering:** plan `0427`, ADR `0004` (next free in `docs/decisions/`).
+
+## Stage: Implementation — Build (2026-06-18T20:05:00Z)
+
+### Session summary
+
+Executed the decision-only ADR plan in two docs steps: wrote `docs/decisions/0004-reconsider-ui-direction.md` (per-component decisions A–D plus Phase 19 entry criteria) and updated `docs/architecture/architecture.md` (Step 8 + phase row marked `✅` complete, `S8` Mermaid node `✅`, ADR-0004 Landed line gateway-ing Phase 19).
+No `src/`/`test/`/`.ts` files were touched, so the type-check and suite were correctly skipped; `pnpm run lint` is green.
+
+### Observations
+
+- **Decision-only ADR held to scope:** four docs files total (ADR, arch doc, plan, retro); zero runtime change, matching the plan's Non-Goals.
+- **Pre-completion reviewer: PASS.**
+  One non-blocking WARN — architecture design-principle #5 still read "UI extraction is deferred … first candidate for extraction," which ADR-0004's Decision D now contradicts.
+- **Reviewer warning addressed in-session:** rewrote principle #5 to "UI is an in-core, substitutable consumer" pointing at ADR-0004 (commit `1c445ed4`), rather than deferring it to Phase 19 — it lived in the same doc and directly conflicted with the just-landed ADR.
+- **Lint gotcha:** the relative ADR link from `docs/architecture/` needs `../decisions/…` (the Step 8 Landed line already had it); an initial `decisions/…` tripped `MD057` and was fixed by amend.
+  Also note `pnpm … lint | tail -N` masks the pipeline exit status — check `PIPESTATUS`/run lint unpiped to gate `&&` chains.
+- **Commit count:** 4 build/doc commits for this stage (`17b0546a`, `7b1d9316`, `1c445ed4` for the ADR + arch doc; planning commits `12e7814a`/`e4895548`/`f1e65a14` predate this stage).
+
+## Stage: Final Retrospective (2026-06-18T21:00:00Z)
+
+### Session summary
+
+Shipped issue #427 — a decision-only ADR (`docs/decisions/0004-reconsider-ui-direction.md`) completing Phase 18 of the `pi-subagents` roadmap — across planning, build, and ship stages in one session.
+The whole arc held to docs-only scope: four docs files, zero runtime change, all `docs:` commits, so release-please correctly batched (no version cut).
+CI passed; #427 closed with a per-component decision summary; siblings #425/#426/#434 were already closed.
+
+### Observations
+
+#### What went well
+
+- **Verified the SDK surface before recording it (novel).**
+  Rather than build the ADR on an assumed `switchSession` API, I read `@earendil-works/pi-coding-agent@0.79.1` `.d.ts` files directly in `node_modules` and confirmed the real contract — full active-session takeover, interactive `ReplacedSessionContext`, plus the `loadEntriesFromFile` read-only alternative.
+  This generalizes the AGENTS.md "verify the remediation exists in the real surface" rule (written for breaking-change migration notes) to an ADR's SDK claims, and it directly shaped Decision B's "direction not mechanism" framing.
+- **Decision-only scope discipline.**
+  Held to four docs files matching the plan's Non-Goals; no `src/`/`test/` drift despite the ADR describing future code.
+- **Pre-completion reviewer earned its keep on a docs-only change.**
+  It caught a stale design-principle (#5) that directly contradicted the just-landed ADR — a real inconsistency, not a code defect — showing the reviewer adds value beyond test/lint gates.
+- **`ask_user` used well for a decision-heavy issue.**
+  Two structured rounds (per-component fates, then the `switchSession`-informed follow-up) let the operator drive the ADR's content; the second round was correctly gated on the first's SDK finding.
+
+#### What caused friction (agent side)
+
+- `other` (shell footgun) — gated a commit on a lint check piped through `tail`: `pnpm … lint 2>&1 | tail -3 && git add … && git commit`.
+  A pipeline's exit status is the last command (`tail`), so the lint failure was masked and a broken-link commit (`89ad57a3`, `MD057`) landed before I noticed.
+  Impact: one extra fix + `git commit --amend`; self-caught on the next unpiped lint run.
+  No bad push (the amend preceded `/ship-issue`).
+- `other` (doc-link slip) — wrote a relative ADR link as `decisions/0004-…` from `docs/architecture/`, when the same session's earlier Step 8 Landed line already used the correct `../decisions/…`.
+  Impact: the `MD057` failure above; had the correct pattern in hand and didn't reuse it.
+- `other` (malformed tool call) — one `Edit` call included a stray `newText_unused` property and was rejected; retried cleanly.
+  Impact: one wasted call, self-caught.
+
+#### What caused friction (user side)
+
+- None blocking.
+  The operator firmed the `/agents` decision (remove create+edit surfaces) one turn after the plan was first committed, costing a small follow-up commit (`f1e65a14`).
+  Opportunity, not criticism: the `ask_user` `/agents` option labeled "shrink — keep config management" may have under-signaled that outright removal was on the table; a crisper "remove agent-management surfaces" option could have surfaced the firm decision in the first round.
+
+### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`) for judgment-heavy review; appropriate (per AGENTS.md its `model:` frontmatter must be a `provider/id` alias to actually run).
+  The main session's `model_change` log shows frequent toggling (`glm-5.2`, `opus-4-8`, `sonnet-4-6`, `deepseek-v4-flash`) but turns can't be cleanly attributed and nothing looks mismatched — not actionable.
+- **Feedback-loop gap analysis** — `pnpm run lint` ran incrementally after each build step (good), not just at the end; baseline `check`+`lint` ran before any change.
+  The one gap was process, not timing: the `tail`-masked lint let a failure slip a commit (above).
+- **Escalation-delay / unused-tool** — no rabbit-holes; longest same-error streak was 1–2 calls (the `MD057` fix).
+  Direct `node_modules` `.d.ts` inspection substituted well for `web_search`/`code_search` on the SDK contract — no missing-context gap.
+
+### Changes made
+
+1. `AGENTS.md` § Commits — added a two-line rule: don't gate a commit (or any `&&` step) on a check piped through `tail`/`head`, since the pipeline's exit status is the filter's and a failed `pnpm run lint`/`check` is masked; run the check unpiped or test `${PIPESTATUS[0]}`.
+2. `packages/pi-subagents/docs/retro/0427-reconsider-ui-direction.md` — appended this Final Retrospective stage entry.

package/docs/retro/0446-spike-session-navigation-entry-criteria.md

@@ -0,0 +1,99 @@
+---
+issue: 446
+issue_title: "pi-subagents: spike — resolve ADR-0004 session-navigation entry criteria"
+---
+
+# Retro: #446 — pi-subagents: spike — resolve ADR-0004 session-navigation entry criteria
+
+## Stage: Planning (2026-06-20T00:00:00Z)
+
+### Session summary
+
+Planned the Phase 19 Step 1 spike that answers the four ADR-0004 session-navigation entry criteria and records them as an ADR-0004 addendum.
+Confirmed the release is independent and that the only committed artifact is the addendum.
+The plan lives at `packages/pi-subagents/docs/plans/0446-spike-session-navigation-entry-criteria.md`; next stage is `/build-plan` (docs/spike deliverable, no committed TDD cycles).
+
+### Observations
+
+- Operator owns the issue (`gotgenes` == gh user), so the "Proposed change" is the working hypothesis.
+  Used `ask_user` once to resolve two method ambiguities: spike method = **automated observed test (vitest)**, committed artifact = **ADR addendum only** (the vitest harness is throwaway, discarded).
+- Gathered the SDK evidence up front so the addendum's expected answers are grounded: `switchSession` is a full active-session takeover that tears down the current runtime via `session_shutdown` (so it threatens the root's in-flight turn); `ReplacedSessionContext` exposes `sendUserMessage` (switch makes the child interactive); `loadEntriesFromFile`/`parseSessionEntries` read entries without switching; `Subagent.outputFile` already exposes the child JSONL path; sibling commands use flat hyphenated names (`agents`, `colgrep-reindex`, `permission-system`).
+- Expected recommendations the spike will confirm: read-only `loadEntriesFromFile` transcript (resolves root-continuity by construction), command-first parallel-agent selection (widget gesture deferred), and `/subagents-settings` (reject the ADR's tentative `/subagents:settings`).
+- `setBeforeSessionInvalidate` is a **host** runtime seam (`agent-session-runtime`/`interactive-mode`), not on the extension command context — noted in Background so Step 4 does not assume the extension can call it.
+- No production code changes and no invariants at risk; the read-only path was chosen partly to keep transcript rendering out of core (preserving the Phase 18 spine invariants from issues #422–#425).
+
+## Stage: Implementation — Build (2026-06-20T10:00:00Z)
+
+### Session summary
+
+Executed the spike: ran a throwaway vitest harness against a real 43-entry child session JSONL, confirmed the read-only transcript path, then wrote the ADR-0004 addendum answering all four entry criteria.
+Discarded the harness (operator decision: addendum only) and folded the architecture.md doc-sync into this build rather than deferring it.
+Four `docs:` commits; pre-completion reviewer returned WARN, whose findings were then resolved.
+
+### Observations
+
+- **Key divergence from the plan (Finding 0):** the plan's Design Overview assumed `loadEntriesFromFile(path)` would be the read mechanism, but it is **not part of the package's public surface** — it lives in the deep `core/session-manager` module (marked `/** Exported for testing */`) and the public barrel (`src/index.ts` → `dist/index.{d.ts,js}`) re-exports only a curated subset that includes `parseSessionEntries` but not `loadEntriesFromFile`; the `exports` map exposes only `"."`, so the deep import is unsupported too.
+  This is **not** a types/runtime mismatch — both barrels agree, and `tsc` rejects the import with `TS2305`.
+  My first harness reached a runtime `is not a function` only because Vitest/esbuild strips types without type-checking; `pnpm run check` (`tsc`) would have caught it at compile time.
+  My earlier "types/runtime mismatch" framing in the addendum/architecture was wrong and was corrected in a follow-up `docs:` commit.
+  Viable path: `parseSessionEntries(readFileSync(outputFile, "utf8"))` (`parseSessionEntries` is public).
+- **Upgrade check (operator question):** verified the omission is **not** version-specific — the latest `0.79.8` barrel omits it identically to the pinned `0.79.1`, so an SDK bump does not surface `loadEntriesFromFile`.
+  No upgrade pursued (out of scope for a docs-only spike); noted the routine `0.79.1` → `0.79.8` freshness gap as a separate, unrelated item.
+- **Doc-sync landed now, not deferred:** the reviewer flagged architecture.md line 997 ("Mechanism (confirmed by Step 1): `switchSession` … or `loadEntriesFromFile`") as actively contradicting the spike.
+  Since the spike now exists, I marked Step 1 ✅ (heading + Mermaid node `S1`), corrected the Phase 18 summary line, and rewrote the Step 4 mechanism line to `parseSessionEntries(readFileSync(...))` — closing the WARN.
+- **Pre-completion reviewer: WARN** (no FAILs) — three architecture.md staleness findings, all addressed in the final `docs:` commit (`74e2374f`).
+  No `src/`/`test/` changes; `pnpm run check` + `pnpm run lint` + `pnpm fallow dead-code` all green at baseline and after.
+- Release recommendation unchanged: **ship independently** (`Release: independent`).
+
+## Stage: Final Retrospective (2026-06-20T18:00:00Z)
+
+### Session summary
+
+Planned, built, and shipped the Phase 19 Step 1 spike across three workflow stages, producing the ADR-0004 addendum that answers all four session-navigation entry criteria and unblocks #445.
+The spike did its job — it rejected ADR-0004's literally-named `loadEntriesFromFile` mechanism before Step 4 coded against it — but the build stage committed an incorrect "types/runtime mismatch" characterization that took two user questions and a correction commit to fix.
+Eight `docs:` commits landed; no release (all `docs:`, auto-batched).
+
+### Observations
+
+#### What went well
+
+- **The spike paid for itself, then over-delivered.**
+  It caught that ADR-0004's named candidate (`loadEntriesFromFile`) is not in the SDK's public surface — a finding about the *implementation*, not the harness — before Step 4 started.
+  The operator's three follow-up questions (upgrade?
+  describe-the-mismatch?
+  spike-vs-implementation impact?) then drove the addendum from a thin "use `parseSessionEntries`" note into a complete, link-backed render pipeline (Finding 1: `parseSessionEntries` → `buildSessionContext` → Pi's public entry components / `serializeConversation`).
+  Step 4 now starts from a verified, public-API-only design.
+- **Clean, non-defensive self-correction.**
+  When the operator asked me to substantiate the claim with links (turn 74), running the actual `tsc` probe surfaced my own error; I corrected all three artifacts (addendum, `architecture.md`, retro) in commit `112c4254` without hedging.
+  "Ask the agent to cite/substantiate a claim" proved a high-leverage verification gesture.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` (compounded by `missing-context`) — I diagnosed a question about the SDK's *export surface* from a *runtime* symptom.
+  The throwaway vitest harness threw `loadEntriesFromFile is not a function`, and I leapt to the dramatic reading ("declared in `.d.ts` but absent at runtime — a types/runtime mismatch") instead of running `tsc`, which disambiguates instantly (`TS2305: has no exported member`).
+  The symbol is simply not in the public barrel — types and runtime agree.
+  Impact: an incorrect technical claim shipped into three committed artifacts (addendum `7c505b78`, `architecture.md`, the build retro note) and required a 3-file correction commit (`112c4254`) plus two operator questions to surface and fix.
+- `instruction-violation` (user-caught) — the `testing` skill already states "Vitest uses esbuild and does not typecheck; run `pnpm run check`."
+  I never ran `tsc` against the harness or the export claim during the build.
+  Two reasons it slipped: (1) the skill was not loaded — `/build-plan` only loads `testing` "if the plan involves test changes or TDD steps," and a docs-only spike using a throwaway harness does not obviously match; (2) the existing rule is framed for "type-only changes," not for *claims/findings about what a module exports*, so it would not clearly have fired even if loaded.
+- `other` (tooling friction, minor) — getting the `tsc` probe to resolve the package took four attempts (turns 77–80: `npx` blocked → `pnpm exec` → files-on-cmdline tsconfig error → probe-inside-package).
+  Impact: added friction, no rework; not a conceptual rabbit-hole.
+
+#### What caused friction (user side)
+
+- None material — the operator's three interventions were strategic probes (dependency-freshness, claim substantiation, spike-vs-implementation scope) that each improved the artifact.
+  The only "earlier" opportunity is an agent-side gap: I should have self-applied the `tsc` check so the operator did not need to ask "describe the mismatch" to trigger verification.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning + Build + the correction work all ran on `anthropic/claude-opus-4-8` (turns 2–104); the mischaracterization therefore occurred on the *strong* model, so the fix is process (run `tsc` on export claims), not model selection.
+  The Ship stage (turns 106–122) ran on `opencode-go/deepseek-v4-flash` — appropriate cost-matching for a mechanical git/CI/close procedure, which it executed cleanly.
+  A transient `anthropic/claude-sonnet-4-6` `model_change` carried no assistant turn (never ran).
+- **Escalation-delay tracking** — no rabbit-hole exceeded five consecutive tool calls on one error; the runtime `is not a function` was resolved in ~2 calls (the issue was the *interpretation*, not a stuck loop).
+- **Unused-tool detection** — for the mischaracterization, `tsc` / `pnpm run check` was available and routine but applied only at baseline (turn 29) and not again until the operator forced it (turns 77–80); it was never run against the harness or the claim.
+- **Feedback-loop gap analysis** — `pnpm run lint` ran after every doc edit (good incremental hygiene), but the *type-check* loop was skipped for precisely the finding that needed it — the harness ran under vitest (no typecheck) and `tsc` was not run on the export claim before committing it.
+
+### Changes made
+
+1. Extended the `testing` skill's `## Type checking` section to cover verifying claims about module exports with `tsc`, not runtime symptoms — `Refs #446`.
+   File: `.pi/skills/testing/SKILL.md`.

package/docs/retro/0448-block-disabled-agent-spawn.md

@@ -0,0 +1,42 @@
+---
+issue: 448
+issue_title: "`enabled: false` does not prevent explicitly spawning disabled agents"
+---
+
+# Retro: #448 — `enabled: false` does not prevent explicitly spawning disabled agents
+
+## Stage: Planning (2026-06-20T00:00:00Z)
+
+### Session summary
+
+Planned the fix for a third-party bug report: `enabled: false` agent overrides are hidden from the available-types list but still spawnable when named explicitly via `subagent_type`.
+The plan adds a disabled-type gate in `resolveSpawnConfig` (returning an explicit error) and a `enabled` filter in `buildTypeListText`, both localized changes with no new collaborators or interface changes.
+
+### Observations
+
+- Issue author (`nickadminroot`) is not the operator (`gotgenes`), so I ran the `ask-user` direction gate.
+  Operator confirmed: fix it, **return an explicit error** (`Agent type "<Name>" is disabled`) rather than the lenient fall-back-to-`general-purpose` alternative, and **include both fixes** (spawn path + tool-description list).
+- Root cause is `resolveType` → `resolveKey` ignoring `enabled`; the registry already has `isValidType` (checks `enabled`) but it was unused on the spawn path.
+  The gate reuses `isValidType`, leaving `resolveType` / `resolveAgentConfig` untouched so UI consumers that intentionally resolve disabled configs keep working.
+- Rejected changing `resolveType` or `resolveAgentConfig` directly — `agent-config-editor.ts` and `agent-menu.ts` rely on resolving disabled agents to display/edit/re-enable them.
+- For the tool-description fix, chose to filter inside `buildTypeListText` rather than re-define `getDefaultAgentNames` / `getUserAgentNames` semantics; those two methods have `buildTypeListText` as their sole consumer (verified by grep), but keeping their meaning intact is cleaner.
+- Classified as non-breaking `fix:` — the change aligns code with the documented README/registry contract; explicit spawning of a disabled agent was undocumented buggy behavior.
+- Not in any architecture roadmap step (no `#448` reference in `docs/`), so **ship independently**.
+
+## Stage: Implementation — TDD (2026-06-20T12:40:00Z)
+
+### Session summary
+
+Completed 2 TDD cycles and all post-step verification gates.
+Step 1 added a 3-line enabled-type gate in `resolveSpawnConfig` (reusing `isValidType`) and 2 new test cases in `test/tools/spawn-config.test.ts`.
+Step 2 added an `isEnabled` predicate filter in `buildTypeListText` and 2 new test cases in `test/tools/helpers.test.ts`.
+Test count delta: 1047 → 1051 (+4).
+
+### Observations
+
+- No deviations from the plan.
+  Both changes were as small as designed: 3 lines in `spawn-config.ts`, 2 lines in `helpers.ts`.
+- Extended the `makeRegistry` stub's `resolve` type in `test/tools/helpers.test.ts` to include an optional `enabled` field, so the `isEnabled` predicate could be exercised without touching production code.
+- The `makeAgentConfig` helper was added to `test/tools/spawn-config.test.ts` (mirroring the pattern in `test/config/agent-types.test.ts`) rather than importing from a shared fixture, since the existing spawn-config test fixture infrastructure didn't need modification.
+- All three plan-enumerated cross-step invariants held green throughout: `resolveAgentConfig` disabled-config behavior, unknown-type fallback, and `getAllTypes` disabled-agent listing.
+- Pre-completion reviewer: **PASS** — all deterministic checks, code design, test artifacts, and cross-step invariants clean.

package/package.json

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

package/src/index.ts

@@ -28,6 +28,7 @@ import { ConcurrencyLimiter } from "#src/lifecycle/concurrency-limiter";
 import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { SubagentManager } from "#src/lifecycle/subagent-manager";
+import { CompositeSubagentObserver } from "#src/observation/composite-subagent-observer";
 import { type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
 import { SubagentEventsObserver } from "#src/observation/subagent-events-observer";
@@ -75,12 +76,18 @@ export default function (pi: ExtensionAPI) {
   settings.load();
 
   // Observer: receives agent lifecycle notifications and dispatches events/notifications.
-  const observer = new SubagentEventsObserver({
+  const eventsObserver = new SubagentEventsObserver({
     emit: (channel, data) => pi.events.emit(channel, data),
     appendEntry: (customType, data) => pi.appendEntry(customType, data),
     notifications,
   });
 
+  // Fan-out observer: lets the widget subscribe as a second lifecycle consumer
+  // while the manager keeps its single-observer contract. The widget is added
+  // after construction (it needs the manager); the manager consults the observer
+  // only at spawn time, so registering late is safe.
+  const observer = new CompositeSubagentObserver([eventsObserver]);
+
   const subagentSessionDeps: SubagentSessionDeps = {
     io: {
       detectEnv,
@@ -128,8 +135,9 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
 
   // Live widget: constructed after the manager (it polls listAgents()) and
-  // injected directly into its consumers — no post-construction field write.
+  // registered as a lifecycle observer so it self-drives its update timer.
   const widget = new AgentWidget(manager, registry);
+  observer.add(widget);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
   const toolStart = new ToolStartHandler(widget);
@@ -141,7 +149,7 @@ export default function (pi: ExtensionAPI) {
 
   // ---- Agent tool ----
 
-  pi.registerTool(new AgentTool(manager, runtime, widget, settings, registry, getAgentDir()).toToolDefinition());
+  pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
 
   // ---- get_subagent_result tool ----
 

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

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

package/src/runtime.ts

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

package/src/service/service.ts

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