@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/retro/0188-replace-any-casts-with-sdk-types.md

@@ -1,69 +0,0 @@
----
-issue: 188
-issue_title: "refactor(pi-subagents): replace any casts with SDK types in extractText and SubscribableSession"
----
-
-# Retro: #188 — Replace any casts with SDK types
-
-## Stage: Planning (2026-05-24T20:04:58Z)
-
-### Session summary
-
-Produced a two-step refactoring plan for replacing `any` casts in `extractText` (with a `TextContent` type predicate) and `SubscribableSession` (with `AgentSessionEvent`).
-Verified that both SDK types are already imported and used in adjacent files within the package.
-Confirmed mock session compatibility via function parameter contravariance — no test changes expected.
-
-### Observations
-
-- The `extractText` parameter type stays `unknown[]` to avoid rippling through callers in `message-formatters.ts` that declare `content: unknown[]`.
-  A future cleanup could tighten those caller signatures.
-- `SubscribableSession` moves to `src/types.ts` as the shared location, matching existing cross-domain types there (`SubagentType`, `ThinkingLevel`, `ShellExec`).
-- All three `eslint-disable` top-level comments (`context.ts`, `record-observer.ts`, `ui-observer.ts`) should be removable once the `any` casts are gone, since the SDK union's discriminated members cover the property access patterns.
-- Risk: if `AgentSessionEvent` doesn't cover `assistantMessageEvent` in `ui-observer.ts`, the type checker will surface it immediately — the mitigation is to check the union members during implementation.
-
-## Stage: Implementation — TDD (2026-05-24T20:17:38Z)
-
-### Session summary
-
-Completed both TDD steps from the plan.
-Step 1 replaced the `any` filter/map chain in `extractText` with an `isTextContent` type predicate; the `??""` removal was required because `TextContent.text` is non-optional per the SDK type.
-Step 2 moved `SubscribableSession` to `types.ts` typed with `AgentSessionEvent`, removed both duplicate local interfaces, and removed all three `eslint-disable` comments.
-Test count: 902 → 901 (one test removed).
-
-### Observations
-
-- The `??` operator on `c.text` in `extractText` triggered `@typescript-eslint/no-unnecessary-condition` at commit time because `TextContent.text` is `string` (non-nullable); removing it was necessary, not just cosmetic.
-- After typing the `record-observer` callback as `AgentSessionEvent`, five additional lint errors surfaced: `event.message?.role` (optional chain unnecessary since `MessageEndEvent.message` is required), `if (u)` guard (unnecessary since `AssistantMessage.usage` is required), and three `?? 0` guards on `input`/`output`/`cacheWrite` (all required `number` fields per `Usage` interface in the Pi source at `~/development/pi/pi/packages/ai/src/types.ts`).
-- The test `"ignores message_end without usage"` was removed — it emitted a non-conforming event that the SDK types guarantee cannot occur at runtime.
-- `ui-observer.ts` had one analogous fix: `event.assistantMessageEvent?.type` → `.type` (the field is required on `MessageUpdateEvent`).
-- No test file changes were needed for `ui-observer.ts` — its existing tests all emit conforming events.
-- The plan's contravariance reasoning about mock session compatibility was correct: `pnpm run check` passed without updating `MockSession.subscribe`.
-
-## Stage: Final Retrospective (2026-05-24T20:41:42Z)
-
-### Session summary
-
-Clean two-step refactoring shipped as `pi-subagents-v6.19.1`.
-Both TDD steps completed in a single session with two minor deviations from the plan, both caught by pre-commit hooks.
-Test count: 902 → 901 (one non-conforming test removed).
-
-### Observations
-
-#### What went well
-
-- The plan's contravariance analysis of `MockSession.subscribe` vs `SubscribableSession` was correct — zero test infrastructure changes needed.
-- Pre-commit hooks (ESLint) caught both deviations from the plan at commit time, before they could reach CI.
-- The user providing the Pi source path (`~/development/pi/pi`) unblocked verification of `AssistantMessage.usage` field requirements without guesswork.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's Risk 3 said "keep `?? ""` for safety" on `TextContent.text`, but `@typescript-eslint/no-unnecessary-condition` rejected it at commit time because `TextContent.text: string` is non-optional.
-  Impact: one failed commit attempt, immediate fix (changed `.map((c) => c.text ?? "")` to `.map((c) => c.text)`).
-- `missing-context` — The plan's step 2 didn't anticipate the five additional lint errors surfaced by properly typing the `record-observer` callback: unnecessary optional chain on `event.message?.role`, unnecessary `if (u)` guard, and three unnecessary `?? 0` guards on usage fields.
-  Impact: added ~5 minutes of investigation to verify the SDK types were truly non-optional before removing guards; required removing one test case (`"ignores message_end without usage"`).
-  Both instances stem from the same root cause: the plan checked that the SDK types *existed* but didn't trace the *field optionality* of types downstream of `AgentSessionEvent` (specifically `AgentMessage.usage` and `Usage.{input,output,cacheWrite}`).
-
-#### What caused friction (user side)
-
-- The Pi source path (`~/development/pi/pi`) was provided reactively after I'd already spent several tool calls trying to locate `AgentMessage` type definitions in `node_modules`.
-  Sharing this path earlier (or noting it in the package skill) would have saved ~4 `grep`/`find` calls.

package/docs/retro/0192-define-session-context-interface.md

@@ -1,59 +0,0 @@
----
-issue: 192
-issue_title: "Define SessionContext narrow interface"
----
-
-# Retro: #192 — Define SessionContext narrow interface
-
-## Stage: Planning (2026-05-24T16:00:00Z)
-
-### Session summary
-
-Planned the pure-additive `SessionContext` interface for `src/types.ts`.
-Traced all 5 consumed fields against the SDK's `ExtensionContext` type declarations to confirm shape alignment.
-Single TDD step: add the interface and verify with `pnpm run check`.
-
-### Observations
-
-- The interface is trivial in scope — one new export with no consumers changing.
-  This is intentionally the smallest possible first step to unblock Layer 1 (#193).
-- `ModelRegistry` already exists as a local narrow interface in `src/session/model-resolver.ts`; `SessionContext` imports it rather than redeclaring.
-- `sessionManager` uses an inline structural type (3 methods) rather than importing the SDK's `ReadonlySessionManager` (13 methods) — ISP applies here.
-- No design ambiguity required `ask_user`; the issue's proposed change section was fully specified.
-
-## Stage: Implementation — TDD (2026-05-24T19:55:00Z)
-
-### Session summary
-
-Added the `SessionContext` interface to `src/types.ts` with an `import type { ModelRegistry }` from `#src/session/model-resolver`.
-Single compile-time step — no runtime tests needed for a pure type definition.
-Baseline: 53 test files, 848 tests; final: unchanged.
-
-### Observations
-
-- Pre-existing lint failure in `docs/architecture/architecture.md` (5 unused MD053 link references for issues #164, #165, #170, #171, #172) was fixed as part of the baseline verification and included in the feat commit.
-- The interface landed exactly as planned — no deviations from the plan's Design Overview.
-
-## Stage: Final Retrospective (2026-05-24T20:00:00Z)
-
-### Session summary
-
-All three stages (plan, TDD, ship) completed in a single session.
-Released as `pi-subagents-v7.1.0`.
-No rework, no deviations from plan.
-
-### Observations
-
-#### What went well
-
-- The issue was fully specified — no ambiguity, no `ask_user` needed at any stage.
-- Trivial scope (one interface, no consumers) made the plan-to-ship pipeline fast and mechanical.
-- Pre-existing lint failures in `architecture.md` were caught during baseline verification and fixed without disrupting the flow.
-
-#### What caused friction (agent side)
-
-- None — clean execution with no rework or corrections.
-
-#### What caused friction (user side)
-
-- None — no intervention needed beyond invoking the three workflow commands.

package/docs/retro/0193-runtime-owns-context-queries.md

@@ -1,75 +0,0 @@
----
-issue: 193
-issue_title: "SubagentRuntime owns context queries"
----
-
-# Retro: #193 — SubagentRuntime owns context queries
-
-## Stage: Planning (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Planned the Layer 1 change that types `SubagentRuntime.currentCtx` as `SessionContext`, adds three query methods (`buildSnapshot`, `getModelInfo`, `getSessionInfo`), and eliminates 4 `as any` casts from `index.ts`.
-The plan covers 7 TDD steps touching `runtime.ts`, `handlers/lifecycle.ts`, `parent-snapshot.ts`, `context.ts`, `service-adapter.ts`, and `index.ts`.
-
-### Observations
-
-- The `pi` field in `currentCtx` is never read back — only stored.
-  Dropping it is safe; `SessionLifecycleHandler` already holds `pi` as a constructor param.
-- `ExtensionContext` structurally satisfies `SessionContext`, so changing `buildParentSnapshot`'s param type is source-compatible with the `/agents` command handler that passes raw SDK `ctx`.
-- `service-adapter.ts` gets the biggest structural change: its two closure params (`getCtx`, `getModelRegistry`) collapse into a single `ServiceRuntimeLike` interface.
-- No design ambiguity — the architecture doc's Layer 1 spec and the issue body are fully aligned.
-- Test fixtures in `make-deps.ts` are unaffected because the `AgentToolDeps` interface shape doesn't change — only the wiring in `index.ts` that supplies the implementations changes.
-
-## Stage: Implementation — TDD (2026-05-24T20:30:00Z)
-
-### Session summary
-
-Completed all 6 implementation TDD steps plus an architecture doc update in one session.
-The `getSessionInfo` implementation needed `?.sessionManager.getSessionFile()` (not `?.sessionManager?.getSessionFile()`) since `sessionManager` is a required field of `SessionContext` — ESLint's `no-unnecessary-condition` caught this at the pre-commit hook.
-Final test count: 854 (up from 848 baseline, +6 new tests for `buildSnapshot`, `getModelInfo`, `getSessionInfo`).
-
-### Observations
-
-- The plan's Non-Goals section incorrectly said `buildParentContext` would NOT change.
-In practice it had to accept `SessionContext` instead of `ExtensionContext` — they are not substitutable in that direction.
-The Module-Level Changes list was correct; only the Non-Goals prose was wrong.
-- `context.ts` needed a local `BranchEntry` union type to handle `getBranch(): unknown[]`.
-TypeScript's discriminated union narrowing doesn't work when the union includes a catch-all `{ type: string }` arm — explicit casts within each `if` branch were required.
-- `service-adapter.ts` ended up using `runtime.currentCtx.modelRegistry` directly (no `getModelInfo()` call needed in the service adapter) — `ServiceRuntimeLike` only needs `currentCtx` and `buildSnapshot`.
-This is cleaner than the plan's `getModelInfo(): { modelRegistry: unknown }` approach.
-- Biome's `noUnusedPrivateClassMembers` warning caught the leftover `private readonly pi: unknown` in `SessionLifecycleHandler`.
-Removed `pi` from the constructor entirely (rather than adding `_` prefix), which also cleaned up `index.ts`.
-- The `eslint-disable` directive at the top of `index.ts` had two now-unused entries (`no-unsafe-member-access`, `no-unsafe-call`) removed by `eslint --fix`.
-
-## Stage: Final Retrospective (2026-05-24T20:45:00Z)
-
-### Session summary
-
-All three stages (plan, TDD, ship) completed in a single session.
-Released as `pi-subagents-v7.2.0`.
-One plan contradiction required a judgment call during implementation; otherwise clean mechanical execution.
-
-### Observations
-
-#### What went well
-
-- The architecture doc's Phase 11 Layer 1 spec was precise enough that no `ask_user` was needed at any stage — the issue body, architecture doc, and #192 retro were fully aligned.
-- `ServiceRuntimeLike` ended up simpler than planned (only `currentCtx` + `buildSnapshot` instead of also requiring `getModelInfo()`) — the implementation found a cleaner design than the plan specified.
-- Test count increase (+6) validates the design: methods that were previously untestable as anonymous closures now have dedicated unit tests.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's Non-Goals section claimed `buildParentContext` would not change, contradicting Module-Level Changes item #4 which explicitly listed the file.
-  The planning stage didn't cross-check these sections before committing.
-  Impact: brief confusion during step 3 about which section to trust (resolved by following Module-Level Changes); no rework, added ~30s of deliberation.
-- `missing-context` — TypeScript's discriminated union narrowing limitation with a `{ type: string }` catch-all arm was not anticipated.
-  Impact: required adding a local `BranchEntry` union type and explicit casts in `context.ts`; no rework but ~2 min of debugging the type error.
-
-#### What caused friction (user side)
-
-- None — no user intervention was needed at any point across all three stages.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added a Non-Goals vs Module-Level Changes cross-check instruction under the Module-Level Changes bullet.

package/docs/retro/0194-align-tool-interfaces-for-structural-typing.md

@@ -1,62 +0,0 @@
----
-issue: 194
-issue_title: "Align tool interfaces for structural typing"
----
-
-# Retro: #194 — Align tool interfaces for structural typing
-
-## Stage: Planning (2026-05-24T12:00:00Z)
-
-### Session summary
-
-Produced an implementation plan for three targeted alignment changes: moving `getMaxConcurrent` off manager interfaces to the settings accessor, renaming `SubagentRuntime.updateWidget()` → `update()`, and removing the dead `getToolCallName` re-export.
-The plan includes a 4-step TDD order with type-check gates after each refactoring step.
-
-### Observations
-
-- Issue #193 (Layer 1) is already closed/implemented, confirming this layer can proceed immediately.
-
-## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Completed all 4 TDD steps: renamed `SubagentRuntime.updateWidget()` → `update()`, moved `getMaxConcurrent` from manager interfaces to the `settings` narrow type, removed the dead `getToolCallName` re-export, and updated the architecture doc.
-Test count stayed flat at 854 (53 files) — all green.
-The `pnpm run check` type-gate caught a previously-unnoticed `test/helpers/make-deps.test.ts` that also validated `getMaxConcurrent` and the old `settings` shape; this file was updated as part of step 2.
-
-### Observations
-
-- An unexpected file `test/helpers/make-deps.test.ts` had three type errors after removing `getMaxConcurrent` (one test asserting `manager.getMaxConcurrent()`, one structural compatibility check referencing it, and one settings override that only passed `defaultMaxTurns`).
-  All three were fixed in the same commit as step 2 — no deviation from the plan.
-- Adding `settings` to `BackgroundParams` (instead of as a 5th function parameter) was the right call: it keeps `spawnBackground` at 4 arguments and groups all spawn-context values together.
-- The health metric update: dead exports 1 → 0, adapter closures 41 → 40 (only `getMaxConcurrent` was removed in this layer; the remaining 8 widget/manager adapter closures need #195 class conversion to collapse).
-- The `background-spawner.ts` module is the only consumer of `getMaxConcurrent` — grep confirms no other call sites beyond `agent-tool.ts`'s interface definition.
-- The `NotificationManager` constructor takes `updateWidget` as a positional callback parameter name — this does NOT need renaming (it's not a structural interface member).
-- The rename from `updateWidget` → `update` is safe because the `WidgetLike` interface in `runtime.ts` already uses `update()` — no naming conflict within the class.
-- All three changes are independent of each other and could be committed in any order, but the plan sequences them for clean `pnpm run check` passes at each step.
-
-## Stage: Final Retrospective (2026-05-24T21:15:00Z)
-
-### Session summary
-
-Planning, TDD implementation, and shipping completed in one continuous session.
-Released as `pi-subagents-v7.2.1` with zero rework or deviations from the plan.
-
-### Observations
-
-#### What went well
-
-- Clean execution end-to-end: 3 refactor commits + 1 docs commit, all planned in advance.
-- The `pnpm run check` gate after step 2 caught `test/helpers/make-deps.test.ts` — a file the plan didn't list — preventing a broken intermediate state.
-  This validates the "run type-check after each step" pattern for interface-alignment work.
-- Phased architecture approach paid off: Layers 0 and 1 being done made Layer 2 entirely mechanical.
-
-#### What caused friction (agent side)
-
-- None identified.
-  The issue scope was tight, the plan was unambiguous, and no rabbit-holes arose.
-
-#### What caused friction (user side)
-
-- None identified.
-  The issue body and architecture doc provided complete context with no ambiguity.

package/docs/retro/0195-convert-tool-factories-to-classes.md

@@ -1,84 +0,0 @@
----
-issue: 195
-issue_title: "Convert tool factories to classes"
----
-
-# Retro: #195 — Convert tool factories to classes
-
-## Stage: Planning (2026-05-24T12:00:00Z)
-
-### Session summary
-
-Produced a 5-step TDD plan converting `createAgentTool`, `createGetResultTool`, and `createSteerTool` to classes with constructor-injected dependencies.
-Verified both prerequisites (#193, #194) are closed and their effects visible in the current source.
-Designed narrow interfaces (`AgentToolRuntime`, `GetResultToolManager`, `SteerToolManager`, `SteerToolEvents`, etc.) that `SubagentRuntime`, `AgentManager`, and `NotificationManager` satisfy structurally.
-
-### Observations
-
-- The conversion is mechanical — no behavioral changes, just structural.
-  Existing tests cover all paths; only test helpers need updating.
-- `steerAgent` and `getAgentConversation` are pure functions that can be imported directly by the classes rather than injected — simplifies the constructor signature.
-- `agentDir` doesn't fit neatly on any existing collaborator, so it remains a constructor param for `AgentTool`.
-- The `AgentToolWidget` interface may become redundant once `AgentToolRuntime` replaces it as the type passed to `spawnBackground`/`runForeground`, but this is deferred to implementation.
-- Ordered TDD steps from smallest (SteerTool) to largest (AgentTool) to build confidence incrementally.
-
-## Stage: Implementation — TDD (2026-05-24T21:26:00Z)
-
-### Session summary
-
-Completed all 5 planned TDD cycles (SteerTool → GetResultTool → AgentTool → `index.ts` wiring → architecture doc).
-All 854 tests pass; type check and lint clean.
-Total: 5 commits across source + test files, plus 1 cleanup fix commit.
-
-### Observations
-
-- `steerAgent` was inlined as `session.steer(message)` directly in `SteerTool.execute()` rather than imported as a module function.
-  This eliminated the dep entirely — the mock session's `steer` vi.fn() handles it in tests without `vi.mock`.
-- The `verbose` test in `get-result-tool.test.ts` was upgraded to drive the real `getAgentConversation` function via `createMockSession({ messages: [...] })` overrides, making it a stronger integration test.
-- `AgentToolWidget` was eliminated: `AgentToolRuntime` (a superset) replaced it, and `background-spawner` and `foreground-runner` already define their own narrow `BackgroundWidgetDeps`/`ForegroundWidgetDeps` interfaces.
-- `createToolDeps()` changed shape from `AgentToolDeps` bag to `AgentToolFixture` (`{ manager, runtime, settings, registry, agentDir }`).
-  This required updating `background-spawner.test.ts` and `foreground-runner.test.ts` (not listed in the plan) to destructure `{ manager, runtime }` instead of `{ manager, widget, agentActivity }`.
-- Biome flagged an unused `import type { AgentSession }` in `get-result-tool.ts` (left by ESLint's cast removal in step 2) — caught by `pnpm run lint` and fixed in a separate commit.
-- The `ReturnType<typeof vi.fn>` annotation on `makeNotifications()` in the get-result-tool test triggered a TypeScript error; fixed by removing the return type annotation entirely (per testing skill guidance).
-
-## Stage: Final Retrospective (2026-05-25T14:06:00Z)
-
-### Session summary
-
-Shipped #195 (three tool factory-to-class conversions), then discovered and fixed a process gap: the fallow dead-code gate was advisory (`continue-on-error: true`) and the `/tdd-plan` and `/ship-issue` prompts didn't run `pnpm fallow dead-code` at all.
-Resulting follow-up work promoted all dead-code rule categories to `error` severity, split the CI fallow step into a hard gate plus advisory full report, and removed the genuinely dead `steerAgent` export and unused `@eslint/js` devDependency.
-
-### Observations
-
-#### What went well
-
-- The user reading CI output carefully and asking "why did fallow check fail yet we proceeded to release?"
-  surfaced a real process gap that would have silently accumulated dead code over time.
-- Incremental severity promotion was effective: checking each category's violation count before promoting let us ratchet from 3 error-level rules to 9 in three commits with zero cleanup work (all categories were already clean except the `steerAgent` export we'd just created).
-
-#### What caused friction (agent side)
-
-- `missing-context` — During the TDD session, I didn't run `pnpm fallow dead-code` after removing all callers of `steerAgent`, so the dead export shipped.
-  The existing `/tdd-plan` prompt's "after last step" checks didn't include fallow.
-  Impact: dead code shipped to a release, required a follow-up fix commit and re-release (`v7.2.2` → `v7.2.3`).
-- `missing-context` — Used `// fallow-ignore-next-line unused-class-member -- reason text` but fallow parses every space-separated token after the rule name as additional rule names.
-  The existing codebase uses bare comments with no trailing text.
-  Impact: 12 stale-suppression warnings until the comment was fixed; no rework but added noise.
-- `missing-context` — During planning, the Module-Level Changes section didn't list `background-spawner.test.ts` or `foreground-runner.test.ts`, even though both destructure `{ widget, agentActivity }` from `createToolDeps()`.
-  The testing skill already has guidance ("grep for ALL test files that construct a compatible mock") but I didn't apply it during planning.
-  Impact: caught immediately by running the full test suite; added friction but no rework.
-
-#### What caused friction (user side)
-
-- The fallow dead-code gap could have been caught earlier if the CI workflow had been configured to block on fallow findings from the start.
-  The `continue-on-error: true` was a reasonable initial setting during adoption but had outlived its usefulness.
-
-### Follow-up ideas
-
-- **Pre-completion reviewer subagent** — a `.pi/agents/pre-completion-reviewer.md` dispatched before `/ship-issue` that runs deterministic checks (`pnpm fallow dead-code`, `pnpm run check`, `pnpm run lint`, `pnpm vitest run`) and judgment checks (conventional commits, architecture doc staleness) in a fresh read-only context.
-  Modeled after RepOne's `pre-completion-reviewer` but scoped to this monorepo's needs.
-  This would be a separate issue.
-
-### Changes made
-
-1. `.pi/prompts/tdd-plan.md` — added `pnpm fallow dead-code` as step 4 in "After the last TDD step" (renumbered steps 4–7 → 5–8).

package/docs/retro/0196-convert-runner-menu-to-classes.md

@@ -1,73 +0,0 @@
----
-issue: 196
-issue_title: "Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts"
----
-
-# Retro: #196 — Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts
-
-## Stage: Planning (2026-05-25T14:35:46Z)
-
-### Session summary
-
-Produced a 6-step TDD plan covering the final two closure-factory-to-class conversions (`createAgentRunner` → `ConcreteAgentRunner`, `createAgentsMenuHandler` → `AgentsMenuHandler`) and the subsequent `index.ts` simplification.
-Confirmed that `AgentManager` structurally satisfies `AgentMenuManager`, enabling direct pass-through without adapter closures.
-
-### Observations
-
-- The issue's proposed `AgentsMenuHandler` constructor omits `agentActivity`, but the class needs it for `viewAgentConversation`.
-  Plan includes it as a constructor param — minimal deviation from the issue.
-- `getModelLabel` can be internalized into `AgentsMenuHandler` since it only uses two pure imported functions (`resolveModel`, `getModelLabelFromConfig`) plus the registry (already a constructor param).
-  This eliminates a 7-line closure from `index.ts`.
-- Tests for `agent-runner` call `runAgent`/`resumeAgent` directly — no test uses `createAgentRunner`, so the runner conversion has zero test impact.
-- The `agent-menu.test.ts` file is 215 lines and needs call-site updates (factory → class constructor + `.handle()`), but no logic changes.
-- After both conversions, `index.ts` loses ~5 imports and ~4 adapter closures.
-  The remaining ~15 closures are structural (event registrations, SDK factory callbacks) and cannot be eliminated.
-
-## Stage: Implementation — TDD (2026-05-25T14:56:11Z)
-
-### Session summary
-
-Completed all 6 plan steps (collapsed into 5 commits: steps 3 and 5 merged).
-Baseline was 854 tests across 53 files; final suite is 856 tests across 54 files (+2 tests, +1 file for `concrete-agent-runner.test.ts`).
-All type-check, lint, and dead-code gates pass clean.
-
-### Observations
-
-- Plan steps 3 and 5 had to be merged into a single commit: removing `createAgentsMenuHandler` immediately broke `index.ts` imports, so the `index.ts` update could not wait for a separate commit.
-  This is a known coupling when a factory's only call site is in `index.ts`.
-- The `AgentsMenuHandler` class constructor includes `agentActivity` as planned (the issue's proposed signature omitted it; the plan's deviation was correct).
-- `getModelLabel` internalization was clean: `resolveModel` and `getModelLabelFromConfig` are pure functions the class imports directly.
-- `AgentManager` structurally satisfies `AgentMenuManager` with no adapter closures — confirmed by `pnpm run check` passing immediately.
-- The `agent-menu.test.ts` refactor replaced `Partial<AgentMenuDeps>` overrides with a `makeHandler(opts)` helper that returns both the handler and collaborator stubs, which is cleaner for assertion.
-- `rumdl` emitted 3 warnings in `pnpm run lint` — these are pre-existing and unrelated to this change (lint passes for markdown linting, the warnings are from biome/eslint steps that auto-fixed nothing).
-
-## Stage: Final Retrospective (2026-05-25T15:04:47Z)
-
-### Session summary
-
-Completed all three stages (planning, TDD, shipping) in one sitting.
-Issue #196 shipped as `pi-subagents-v7.2.5`.
-All closure factories in pi-subagents are now classes; Phase 11 (Layers 3 + 4) is complete.
-
-### Observations
-
-#### What went well
-
-- The three-session lifecycle (plan → TDD → ship) completed cleanly in a single sitting with no user corrections.
-- Structural typing confirmation during planning paid off — `AgentManager` satisfied `AgentMenuManager` without adapter closures, and `pnpm run check` passed immediately after the wiring change.
-- The `makeHandler(opts)` test helper pattern (returning handler + collaborator stubs) was cleaner than the `Partial<AgentMenuDeps>` spread approach it replaced.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan separated factory removal (step 3) from call-site update (step 5), even though the testing skill already has a rule: "When a TDD step changes an interface that has a single call site, the step must include updating that call site."
-  The planner treated this as a testing concern and didn't apply it during plan authoring.
-  Impact: steps 3 and 5 had to be merged at implementation time, producing a commit message explaining the deviation.
-  Added a cross-reference to `plan-issue.md`.
-
-#### What caused friction (user side)
-
-Nothing notable — the user's issue was well-specified and the three `/` commands ran without intervention.
-
-### Changes made
-
-1. Added single-call-site rule to `.pi/prompts/plan-issue.md` TDD Order section: when a step removes a factory/export with one call site, include the call-site update in the same step.

package/docs/retro/0205-decompose-render-widget-lines.md

@@ -1,64 +0,0 @@
----
-issue: 205
-issue_title: "Decompose renderWidgetLines (cognitive 44)"
----
-
-# Retro: #205 — Decompose renderWidgetLines
-
-## Stage: Planning (2026-05-25T15:27:45Z)
-
-### Session summary
-
-Planned the decomposition of `renderWidgetLines` (cognitive complexity 44) into four private helper functions: `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow`.
-Also updated `architecture.md` Phase 12 steps with issue links (#205–#208) and added a Phase 12 row to the structural refactoring issues table.
-
-### Observations
-
-- The function's complexity comes from five interwoven concerns (categorization, section building, heading, non-overflow assembly with connector fixup, overflow-budget assembly) — but the extraction is mechanical since all logic is already pure and stateless.
-- No new tests are needed — the existing 8 tests in `widget-renderer.test.ts` cover all branches end-to-end and remain the correct test level for assembly logic.
-- The tree-connector fixup (swapping `├─` → `└─` via string replacement on Unicode chars) is the most fragile part; it stays as-is inside `assembleWithinBudget` rather than being further decomposed.
-- A `sections` return object from `buildSections` bundles `finishedLines`, `runningLines`, and `queuedLine` to avoid long parameter lists on the assembly helpers.
-
-## Stage: Implementation — TDD (2026-05-25T15:35:10Z)
-
-### Session summary
-
-Completed all four TDD steps: extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`.
-All 23 `widget-renderer.test.ts` tests pass throughout; no new tests were added.
-Full suite (856 tests, 54 files) is green; type check and lint are clean.
-
-### Observations
-
-- **Stray backtick during `assembleOverflow` extraction:** The Edit tool introduced a double-backtick (`\`\``) at the end of the nested template literal on the overflow indicator line — the inner template literal's closing backtick concatenated with the outer template's closing backtick, creating a parse error.
-  Required Python-based line-level surgery to fix since the Edit tool cannot reliably match nested template literals through JSON escaping.
-- The `renderWidgetLines` `else` block removal also required Python because the Edit tool's `oldText` matching is unreliable when the target contains nested template literals with backticks.
-- Aside from the template-literal matching friction, all extractions were purely mechanical; no logic changes were needed.
-- The final `renderWidgetLines` is a clean 12-line orchestrator; each helper is well under complexity 10.
-
-## Stage: Final Retrospective (2026-05-25T15:41:48Z)
-
-### Session summary
-
-All three stages (planning, TDD implementation, shipping) completed in a single session.
-Four refactor commits extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`, reducing cognitive complexity from 44 to <10 per function.
-Released as `pi-subagents-v7.2.6`.
-
-### Observations
-
-#### What went well
-
-- The planning-through-shipping pipeline was efficient: plan → 4 TDD steps → ship → release in one session with no rework.
-- The plan correctly identified all four extraction targets and ordered TDD steps to avoid intermediate breakage.
-- All 23 existing `widget-renderer.test.ts` tests passed throughout with zero modifications — the existing test coverage was at the right abstraction level for this refactoring.
-- The `architecture.md` Phase 12 update (issue links, refactoring table row) was a clean opportunistic addition.
-
-#### What caused friction (agent side)
-
-- `other` (Edit tool limitation) — The Edit tool introduced a stray double-backtick when inserting `assembleOverflow`'s body, caused by JSON escaping colliding with nested template literal backticks.
-  The same limitation then prevented matching `oldText` containing nested template literals in the `renderWidgetLines` overflow block.
-  Required two Python-based line-level fixes via bash.
-  Impact: ~3 extra tool calls; self-identified and self-corrected.
-
-#### What caused friction (user side)
-
-- No friction observed.

package/docs/retro/0206-decompose-show-agent-detail.md

@@ -1,67 +0,0 @@
----
-issue: 206
-issue_title: "Decompose showAgentDetail (cognitive 33)"
----
-
-# Retro: #206 — Decompose showAgentDetail (cognitive 33)
-
-## Stage: Planning (2026-05-25T12:00:00Z)
-
-### Session summary
-
-Produced a 4-step plan to decompose `showAgentDetail` (cognitive 33) and `ejectAgent` (cognitive 20) in `ui/agent-config-editor.ts`.
-The plan extracts two exported pure functions (`buildMenuOptions`, `buildEjectContent`) with dedicated unit tests, plus three closure-internal handlers (`handleEdit`, `handleDelete`, `handleReset`).
-
-### Observations
-
-- Three of the six action handlers (`ejectAgent`, `disableAgent`, `enableAgent`) were already extracted as closure functions — only Edit, Delete, and Reset were inlined in the dispatch chain.
-- `buildMenuOptions` and `buildEjectContent` are ideal pure-function extractions: complex branching logic with no IO dependencies, previously untestable in isolation.
-- The existing 18 integration tests through `showAgentDetail` provide a strong safety net — no risk of behavior regression during extraction.
-- Chose to scope `ejectAgent` decomposition into this issue since the issue's outcome says "< 10 per function" and `ejectAgent` is at cognitive 20 in the same file.
-- `disableAgent` and `enableAgent` were explicitly deferred — their cognitive complexity is manageable and decomposing them would add scope without meaningful benefit.
-
-## Stage: Implementation — TDD (2026-05-25T11:55:00Z)
-
-### Session summary
-
-Completed all 4 TDD steps. 3 `refactor:` commits extract `buildMenuOptions`, the three inline handlers, and `buildEjectContent`; 1 `docs:` commit updates the architecture table.
-Test count grew from 21 to 33 (+12 new unit tests for the two exported pure functions).
-
-### Observations
-
-- A `newText: null` bug in the Edit tool corrupted `agent-config-editor.ts` during step 1; recovered immediately by rewriting the file with `Write`.
-- The test used `thinking: "auto"` which is not a valid `ThinkingLevel` — fixed by changing to `"low"` before the final commit; the type error was caught by `pnpm run check` after the TDD step.
-- `buildMenuOptions` extracted cleanly with early-return style (no `let menuOptions` intermediate); the refactored function passes all 5 new unit tests and all 21 existing integration tests.
-- `handleEdit`, `handleDelete`, and `handleReset` are closure-internal; they drop the outer `if (file)` guard since the menu only shows those options when `file` is defined.
-- `buildEjectContent` extracted from `ejectAgent` reduces `ejectAgent` to a thin IO function (~10 lines); no behavior change verified by the existing eject integration tests.
-
-## Stage: Final Retrospective (2026-05-25T12:10:00Z)
-
-### Session summary
-
-Completed full lifecycle — Planning, TDD (3 `refactor:` + 1 `docs:` commits, +12 tests), Ship, and Release (`pi-subagents-v7.2.7`) — in a single session with no user corrections.
-
-### Observations
-
-#### What went well
-
-- The three-stage workflow (plan → TDD → ship) executed without any user intervention between stages.
-  Each stage's retro notes provided clean context for the next.
-- Pure-function extraction pattern worked cleanly: `buildMenuOptions` and `buildEjectContent` exported for unit testing; `handleEdit`, `handleDelete`, `handleReset` kept as closure-internal, tested via existing integration tests.
-- The existing 21 integration tests caught no regressions across all 3 refactor commits — strong safety net for mechanical extraction.
-
-#### What caused friction (agent side)
-
-- `other` — Passed `newText: null` to the `Edit` tool during TDD step 1, injecting a literal `null` into `agent-config-editor.ts` and corrupting the file.
-  Self-identified immediately via Biome autoformat failure.
-  Impact: one wasted tool round-trip; recovered by rewriting the file with `Write`.
-- `missing-context` — Used `thinking: "auto"` in a `buildEjectContent` test fixture without checking `ThinkingLevel` is `"minimal" | "low" | "medium" | "high" | "xhigh"`.
-  Self-identified by `pnpm run check` post-TDD gate.
-  Impact: one `--amend` fix, no extra commit.
-- `missing-context` — Plan stated "18 tests" as the baseline count; actual baseline was 21.
-  Impact: none — just an inaccurate number in the plan text.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The user triggered each stage sequentially without needing to redirect or correct.