@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/retro/0123-remove-vi-fn-cast-smell.md

@@ -1,49 +0,0 @@
----
-issue: 123
-issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
----
-
-# Retro: #123 — remove vi.fn() cast smell from test helpers
-
-## Final Retrospective (2026-05-22T00:00:00Z)
-
-### Session summary
-
-Planned and implemented removal of all 9 `as ReturnType<typeof vi.fn>` casts and 5 `vi.mocked()` calls across 3 test files, replacing them with named typed mock variables.
-Released as `pi-subagents-v6.8.1`.
-Pure test hygiene — no production code changes, no behavioral changes, 652 tests unchanged.
-
-### Observations
-
-#### What went well
-
-- **Three-file scope executed cleanly once the plan was right.**
-  Each file was an independent commit with no cross-file dependencies.
-  The named-variable pattern (`const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>()`) worked identically across all three test files despite different mock construction styles (factory function vs `beforeEach` assignment).
-
-#### What caused friction (agent side)
-
-- `scope-drift` — The initial plan scoped the fix to `service-adapter.test.ts` only, listing `lifecycle.test.ts` and `tool-start.test.ts` as explicit Non-Goals — despite the planning-phase grep showing all 9 cast sites across 3 files.
-  The user redirected with "let's eliminate this pattern of behavior."
-  Updated the GitHub issue body, rewrote the plan, and amended the commit.
-  Impact: plan rewrite (~2 minutes), no implementation rework.
-  User-caught.
-- `missing-context` — Imported `MockInstance` from `vitest` during step 1 (`service-adapter.test.ts`) but actually used `ReturnType<typeof vi.fn<...>>` — matching the pattern used in the other two files.
-  The unused import was caught by `pnpm run lint` at the post-implementation check, not proactively.
-  Impact: one extra edit + amend cycle.
-  Self-identified (via lint).
-- `other` — Ran `git commit --amend` to fix the unused import but HEAD was step 3's commit (`tool-start`), not step 1's (`service-adapter`).
-  The amend landed the `service-adapter.test.ts` change into the wrong commit with the wrong message.
-  Required `git reset --soft` back to the plan commit and recommitting all 3 files.
-  Impact: ~1 minute of git surgery, clean result.
-  Self-identified.
-
-#### What caused friction (user side)
-
-- The issue body scoped the fix to `service-adapter.test.ts` only, which the agent followed literally.
-  The broader intent ("eliminate this pattern") was implicit.
-  Flagging the desired scope as "all files with this pattern" in the issue body would have avoided the plan rewrite.
-
-### Changes made
-
-1. Wrote retro file at `packages/pi-subagents/docs/retro/0123-remove-vi-fn-cast-smell.md`.

package/docs/retro/0131-consolidate-shared-test-fixtures.md

@@ -1,46 +0,0 @@
----
-issue: 131
-issue_title: Consolidate shared test fixtures
----
-
-# Retro: #131 — Consolidate shared test fixtures
-
-## Final Retrospective (2026-05-22T11:30:00Z)
-
-### Session summary
-
-Planned and implemented the consolidation of six duplicated test factories into two shared helpers (`createMockSession` in `test/helpers/mock-session.ts`, `createToolDeps` in `test/helpers/make-deps.ts`).
-All 715 tests pass, released as `pi-subagents-v6.9.4`.
-The implementation was a pure test refactor with no production code changes.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift approach worked cleanly: create factory → migrate one consumer at a time → verify green after each step.
-  Each migration commit was small and isolated, making failures easy to diagnose.
-- Structural typing as a strategy proved out — `createToolDeps()` returns `AgentToolDeps` (the superset), and `spawnBackground(deps, ...)` and `runForeground(deps, ...)` accept their narrow `BackgroundDeps`/`ForegroundDeps` interfaces without any casting.
-
-#### What caused friction (agent side)
-
-- `missing-context` — Plan used `registry.resolve("general-purpose", "/dir")` in the `make-deps.test.ts` test, but `AgentTypeRegistry` has no `resolve` method — the correct method is `resolveAgentConfig()`.
-  Impact: one test failure during step 5 red→green, fixed immediately with no rework.
-
-- `missing-context` — Default values differed between the old narrow factories and the new shared factory: `"bg-1"` vs `"agent-1"` for spawn IDs (`background-spawner.test.ts`), `"Task done."` vs `"All done."` for result text (`foreground-runner.test.ts`).
-  Impact: two test failures in step 7, one in step 8, each requiring assertion updates before the migration step could pass.
-
-- `missing-context` — `MockSession` interface used `ReturnType<typeof vi.fn>` which expands to `Mock<Procedure | Constructable>` in Vitest v4 — a union type TypeScript cannot call.
-  Impact: `pnpm run check` failed after all TDD steps were done, requiring a separate `style:` commit to switch to explicitly parameterized `Mock<() => void>` etc.
-
-- `missing-context` — Removed the `AgentToolDeps` import from `agent-tool.test.ts` without checking that the `execute()` helper still referenced it.
-  Impact: caught in the same `pnpm run check` pass, fixed in the same `style:` commit.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The plan was unambiguous, and the session ran autonomously through all 8 TDD steps plus post-checks without intervention.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added TDD planning rule for diffing default values when consolidating duplicate test factories.
-2. `.pi/skills/testing/SKILL.md` — added Vitest mock pattern rule for typing mock fields with `Mock<specific-signature>` instead of `ReturnType<typeof vi.fn>`.

package/docs/retro/0132-inject-io-into-session-config.md

@@ -1,33 +0,0 @@
----
-issue: 132
-issue_title: "Inject IO collaborators into `assembleSessionConfig`"
----
-
-# Retro: #132 — Inject IO collaborators into `assembleSessionConfig`
-
-## Final Retrospective (2026-05-22T12:25:00Z)
-
-### Session summary
-
-Defined an `AssemblerIO` interface bundling four IO/prompt collaborators, injected it into `assembleSessionConfig`, and updated `agent-runner.ts` to pass real implementations.
-Eliminated all 4 `vi.mock()` calls in `session-config.test.ts`, flattened the `vi.hoisted()` block into plain `vi.fn()` declarations, and shifted assertions from mock-call verification to output-property checks.
-Released as `pi-subagents-v6.10.0`.
-
-### Observations
-
-#### What went well
-
-- Perl two-pass replacement (multi-line then single-line) handled 40+ `assembleSessionConfig` call-site updates in one command with zero manual errors.
-- Flattening `vi.hoisted()` into regular `vi.fn()` declarations in step 3 was a clean simplification — hoisting was only needed when the mocks were referenced inside `vi.mock()` factories.
-- Real `getMemoryToolNames` / `getReadOnlyMemoryToolNames` worked as drop-in replacements with no test rework needed — the pure functions' behavior matched what the mocks were configured to return for all existing test scenarios.
-
-#### What caused friction (agent side)
-
-- `missing-context` — `mockBuildAgentPrompt` was declared as `vi.fn(() => "assembled system prompt")` which inferred `Mock<() => string>`.
-  When step 4 used `mockImplementationOnce` with a parameterized function, TypeScript rejected it.
-  The testing skill already documents `Mock<specific-signature>` for this exact case.
-  Impact: one type-check failure, fixed by adding `Mock<AssemblerIO["buildAgentPrompt"]>` annotation; added friction but no rework.
-
-#### What caused friction (user side)
-
-- Nothing notable — standard prompt-template workflow with no corrections needed.

package/docs/retro/0133-inject-sdk-boundary-into-agent-runner.md

@@ -1,45 +0,0 @@
----
-issue: 133
-issue_title: "Inject SDK boundary into `agent-runner`"
----
-
-# Retro: #133 — Inject SDK boundary into agent-runner
-
-## Final Retrospective (2026-05-22T13:15:00Z)
-
-### Session summary
-
-Injected all SDK and IO dependencies into `runAgent()` via a `RunnerIO` interface and `createAgentRunner(io)` factory.
-Eliminated all 14 `vi.mock()` calls across `agent-runner.test.ts` (7) and `agent-runner-extension-tools.test.ts` (7).
-Released as `pi-subagents-v6.11.0`.
-
-### Observations
-
-#### What went well
-
-- The `createAgentRunner(io)` factory pattern was a clean design choice that kept the `AgentRunner` interface and `AgentManager` completely unchanged — zero downstream impact.
-- Folding plan steps 1 and 2 into a single commit was the right call given `tsconfig.json` includes `test/` — recognized the constraint before attempting a broken intermediate commit.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — Annotated `createRunnerIO(): RunnerIO` in the test helper, which erased the `Mock<...>` type information from `vi.fn()` stubs.
-   TypeScript then rejected `.mockResolvedValue()` on `io.createSession` across 18 call sites.
-   Required removing the annotation plus a follow-up edit to remove the now-unused `type RunnerIO` import flagged by Biome.
-   Impact: two extra edit rounds and a type-check cycle before the fix landed.
-
-2. `missing-context` — Added `SettingsManager` to the SDK import block in `index.ts` without checking that the name was already imported from `./settings.js`.
-   Biome caught the redeclaration and the `noRedeclare` lint error required an alias fix (`SettingsManager as SdkSettingsManager`).
-   Impact: one extra edit round triggered by the autoformat failure.
-
-3. `premature-convergence` — Spent excessive reasoning time deliberating commit-boundary strategy (whether to combine steps 1+2, how to handle broken intermediate states, whether step 4 would have remaining work).
-   The answer was straightforward once the `tsconfig` `include` was checked, but the check came late in the deliberation.
-   Impact: added friction but no rework — the final decision was correct.
-
-#### What caused friction (user side)
-
-- None identified.
-  The plan and issue were well-specified, and the user's only intervention was "Please, continue" after a message boundary, which was appropriate.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added rule: do not annotate test factory return types with production interface types (erases `Mock<...>` methods).

package/docs/retro/0134-reduce-as-any-casts.md

@@ -1,56 +0,0 @@
----
-issue: 134
-issue_title: "Reduce `as any` casts in test suite"
----
-
-# Retro: #134 — Reduce as-any casts in test suite
-
-## Final Retrospective (2026-05-22T17:00:00Z)
-
-### Session summary
-
-Reduced `as any` casts from 93 to 15 across the pi-subagents package.
-Production changes added type guards (`getToolCallName`, `isBashExecution`), narrowed `SubagentRuntime.widget` to `WidgetLike`, typed `CreateSessionOptions.settingsManager` as `SettingsManager`, and fixed `ResourceLoaderOptions.appendSystemPromptOverride` to match the SDK.
-Test improvements introduced `toAgentSession()`, `STUB_CTX`, and `makeRegistry()` helpers to centralise unavoidable bridge casts.
-Also fixed 3 pre-existing lint issues.
-
-This session also included #133 (plan + implement + ship) which preceded the #134 work.
-
-### Observations
-
-#### What went well
-
-- The user's Kent Beck prompt ("make the change that makes the change easy") redirected the plan from test-only fixes to targeted production changes, yielding cleaner results — `WidgetLike`, type guards, and SDK-typed options eliminated casts that would have been impossible to remove from tests alone.
-- The user's TDA observation on the `MenuCtx` step caught a deep architectural issue (context threaded 4 layers just to relay to `buildParentSnapshot`).
-  Skipping step 4 was the right call — attempting it would have added a production cast or cascaded changes through 6+ files.
-
-#### What caused friction (agent side)
-
-1. `rabbit-hole` — Step 1 planning involved extensive analysis of whether `CreateSessionOptions` could use full SDK types.
-   Spent significant reasoning tracing `ModelRegistry` / `SessionManager` private fields, structural compatibility, `ParentSnapshot` constructibility, and `ResourceLoader` interface width before concluding that only `settingsManager` and the callback signature could be fixed.
-   The plan's claim "widen to SDK types" was optimistic about class-with-private-fields constraints.
-   Impact: added friction but no rework — the conclusion was correct, just slow to reach.
-
-2. `wrong-abstraction` — Step 4 (`MenuCtx`) attempted to mechanically narrow the handler parameter without questioning why `ctx` was threaded 4 layers deep.
-   Partially implemented the `MenuCtx` interface before the user's "What am I misunderstanding?"
-   prompt exposed the real issue: a TDA violation where intermediate functions carry `ExtensionContext` only to relay it.
-   Impact: partial implementation reverted via `git checkout src/ui/agent-menu.ts`; ~10 minutes of wasted edits.
-
-3. `instruction-violation` (user-caught) — Used `pnpm exec biome check --write --unsafe` instead of `pnpm run lint:fix` to fix pre-existing lint issues.
-   The `/tdd-plan` prompt explicitly says "run `pnpm run lint:fix`."
-   Impact: no functional difference (same result), but violated the established convention and used an unnecessary `--unsafe` flag.
-
-4. `instruction-violation` (user-caught) — Dismissed pre-existing lint issues as "not from our changes" without fixing them.
-   The user asked "Why do we have pre-existing lint issues?"
-   — the correct action was to fix them immediately rather than noting and ignoring them.
-   Impact: required an extra commit (`style: fix pre-existing lint issues`) that should have been folded into an earlier step.
-
-#### What caused friction (user side)
-
-- The user's interventions on the `MenuCtx` step and lint issues were both valuable redirections that improved the outcome.
-  No mechanical overhead identified — each intervention was strategic judgment that the agent couldn't have reached alone.
-
-### Changes made
-
-1. `.pi/prompts/tdd-plan.md` — added "Verify green baseline" section (check + lint + test before starting TDD); added "Fix all failures — including pre-existing ones" to the end-of-cycle lint step.
-2. `.pi/prompts/build-plan.md` — same baseline check and fix-all rule for non-TDD plans.

package/docs/retro/0135-extract-display-helpers.md

@@ -1,38 +0,0 @@
----
-issue: 135
-issue_title: "Extract display helpers from `agent-widget.ts`"
----
-
-# Retro: #135 — Extract display helpers from agent-widget.ts
-
-## Final Retrospective (2026-05-22T19:00:00Z)
-
-### Session summary
-
-Extracted 11 helper functions, 3 constants, and 2 types from `agent-widget.ts` into a new `ui/display.ts` module.
-Updated 10 source consumers and 2 test consumers.
-Pure code-motion refactoring — no behavior change, no test-count delta (714 tests throughout).
-
-### Observations
-
-#### What went well
-
-- Plan accurately identified all 10 source and 2 test import sites with no misses — the consumer import table in the plan mapped 1:1 to actual changes.
-- TDD execution was mechanical and smooth: create module → update source imports → rename test file → verify.
-  Zero surprises or deviations from the plan.
-
-#### What caused friction (agent side)
-
-- `rabbit-hole` — During `/ship-issue`, wasted ~6 tool calls investigating whether `pi-subagents-v6.12.0` was at HEAD.
-  Ran `git log --oneline HEAD --not --remotes=origin/main` which dumped the entire repo history (50KB truncation), then misread `git describe --tags --abbrev=0` (nearest ancestor tag) as confirming the tag was at HEAD.
-  `git tag --points-at HEAD` returned empty, disproving the assumption, but I still spent cycles reasoning about CI release-please behavior.
-  Impact: added friction but no rework — the close comment and release-please merge were correct.
-
-#### What caused friction (user side)
-
-- None observed.
-  The issue was unambiguous, the architecture doc prescribed the exact extraction set, and no user intervention was needed during implementation.
-
-### Changes made
-
-1. Created `packages/pi-subagents/docs/retro/0135-extract-display-helpers.md` (this file).

package/docs/retro/0136-decompose-agent-menu.md

@@ -1,43 +0,0 @@
----
-issue: 136
-issue_title: "Decompose `agent-menu.ts`"
----
-
-# Retro: #136 — Decompose `agent-menu.ts`
-
-## Final Retrospective (2026-05-22T20:10:00-04:00)
-
-### Session summary
-
-Decomposed `agent-menu.ts` (668 lines) into four focused modules: `agent-file-ops.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts`, and a slimmed-down `agent-menu.ts` (296 lines).
-Three TDD cycles shipped cleanly, adding 47 tests (714 → 761) and eliminating `vi.mock("node:fs")` from the menu test file.
-Released as `pi-subagents-v6.13.0`.
-
-### Observations
-
-#### What went well
-
-- The three-cycle TDD plan (file-ops → config-editor → creation-wizard) produced clean incremental commits with no rework.
-  Each cycle left the repo green for both tests and type-check.
-- The creation wizard naturally produced narrower interfaces (`WizardManager`, `WizardRegistry`) than the plan specified — a positive deviation from the plan's `AgentTypeRegistry` concrete type, following ISP more strictly.
-- The large edit removing ~170 lines of extracted functions from `agent-menu.ts` in Cycle 2 landed correctly on the first attempt, thanks to using exact `oldText` matching with the full function bodies.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The config-editor test factory used `Partial<AgentConfigEditorDeps>` for the overrides parameter.
-  The `...overrides` spread created a union type that erased `Mock<...>` methods from `fileOps`, producing 28 `TS2339` errors on `pnpm run check`.
-  The testing skill warns about return-type annotations but not about `Partial<Interface>` in overrides — the same erasure mechanism applies through a different path.
-  Impact: one extra edit-check cycle to remove the `Partial<>` annotation and overrides parameter.
-  Self-identified (caught on `pnpm run check` before commit).
-
-- `missing-context` — The config-editor test had an unused `ctx` variable from an earlier draft of the "disable-only file" test, caught only by the linter after the Cycle 3 commit.
-  Impact: required amending the Cycle 3 commit; added friction but no rework.
-  Self-identified (caught by `pnpm run lint`).
-
-#### What caused friction (user side)
-
-- None observed — the user's plan was unambiguous and the prerequisite (#135) was already implemented.
-
-### Changes made
-
-1. Added a `Partial<Interface>` type-erasure bullet to `.pi/skills/testing/SKILL.md`.

package/docs/retro/0144-consolidate-observation-model.md

@@ -1,39 +0,0 @@
----
-issue: 144
-issue_title: "Consolidate observation model (Phase 9, Step L)"
----
-
-# Retro: #144 — Consolidate observation model
-
-## Final Retrospective (2026-05-23)
-
-### Session summary
-
-Planned and implemented the Phase 9 Step L observation model consolidation.
-Removed dual `_toolUses`/`_lifetimeUsage` counting from `AgentActivityTracker`, added `session`/`outputFile` convenience getters to `AgentRecord`, migrated 14 callsites, and dissolved `NotificationDeps` into plain constructor parameters.
-Released as `pi-subagents-v6.16.0`.
-
-### Observations
-
-#### What went well
-
-- The plan correctly anticipated that TDD steps 4 (remove tracker stats) and 5 (migrate UI consumers) would be type-coupled and need merging.
-  This played out exactly as predicted — no surprise rework.
-- Step 2's grep sweep during `execution?.` migration found two callsites (`agent-tool.ts:315`, `agent-manager.ts:353`) that the plan's file list missed.
-  Systematic grep at migration time caught them before commit.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` — Did not load the `colgrep` skill during the planning phase despite two explicit instructions: AGENTS.md ("Use `colgrep` for intent-based codebase exploration") and the `/plan-issue` prompt ("load the `code-design` skill and the `colgrep` skill for convention discovery").
-  Loaded 4 other skills but skipped colgrep.
-  User-caught ("I noticed you didn't load or use `colgrep`").
-  Impact: one extra round-trip with the user; no rework since the plan hadn't been committed yet.
-  The colgrep searches proved useful once run — highest-scoring hit for "dependency bag converted to plain constructor parameters" was `notification.ts`, directly confirming the target.
-- `wrong-abstraction` — When editing `src/ui/ui-observer.ts` to remove the `message_end` accumulation block, the replacement text closed the `session.subscribe(...)` callback but also added the function's closing brace, producing a duplicate `}`.
-  Autoformat caught the parse error immediately.
-  Impact: one follow-up edit, no downstream rework.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's intervention on colgrep was timely — caught before plan commit, not after.

package/docs/retro/0145-decompose-execute-push-ctx-to-boundary.md

@@ -1,56 +0,0 @@
----
-issue: 145
-issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
----
-
-# Retro: #145 — Decompose execute and push ExtensionContext to the boundary
-
-## Final Retrospective (2026-05-23)
-
-### Session summary
-
-Extracted config resolution into a pure `resolveSpawnConfig` function, injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` to eliminate `ctx` reads from `execute`, pushed `ParentSnapshot` to `AgentManager`'s public API, and dissolved three small dependency bags (`ForegroundDeps`, `BackgroundDeps`, `AdapterDeps`) into plain parameters.
-Released as `pi-subagents-v6.15.0`.
-
-### Observations
-
-#### What went well
-
-- User's two escalating questions ("Are there any other missing collaborators?"
-  → "Hiding dependencies in an object bag still counts as dependencies!") caught a `premature-convergence` before it landed as committed code.
-  The reverted partial step 3 attempt was ~4 files of changes that would have needed rework.
-  The resulting design (injected collaborators) is meaningfully better than the original plan's mechanical relocation.
-- Folding tightly-coupled TDD steps (ctx elimination + params shrinking + deps dissolution) into fewer commits avoided intermediate states with broken types.
-  The plan's 12-step sequence would have required lift-and-shift gymnastics; the actual 7-commit sequence was cleaner.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — the original plan relocated `buildParentSnapshot` calls to `execute` without questioning whether `execute` should read `ctx` at all.
-  The existing `code-design` skill has DIP and parameter-relay rules that should have flagged this.
-  The `service-adapter.ts` module already demonstrated the getter-injection pattern (`getCtx`, `getModelRegistry`), but I didn't search for it during plan writing.
-  Impact: one plan rewrite commit (76bb57b), one reverted partial implementation (~15 minutes of rework).
-  User-caught.
-
-- `missing-context` — didn't use `colgrep` during initial plan writing to discover the established getter-injection convention in `service-adapter.ts`.
-  Used `grep` exclusively for exact symbol matching.
-  When prompted by the user to use `colgrep`, the results were confirmatory rather than revelatory because I'd already read the relevant files by that point.
-  The miss was not using it *earlier* for intent-based exploration ("how do existing modules inject session-scoped state?").
-  Impact: added friction but no rework — the user's questions surfaced the pattern before code was committed.
-  User-caught.
-
-- `instruction-violation` — wrote an inline `import()` type assertion (`session.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext`) in `service-adapter.ts`.
-  AGENTS.md says "Use standard top-level imports only."
-  Impact: one extra edit round, caught before committing.
-  User-caught.
-
-#### What caused friction (user side)
-
-- The user's redirecting questions were well-timed and effective.
-  The escalation from "Are there any other missing collaborators?"
-  to the more pointed "Hiding dependencies in an object bag still counts as dependencies!"
-  was the right amount of pressure.
-  No friction observed on the user side.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added `colgrep` skill loading to the "Load skills" section for code-change plans, so convention discovery happens during exploration rather than after committing to a design.

package/docs/retro/0146-narrow-ui-context.md

@@ -1,70 +0,0 @@
----
-issue: 146
-issue_title: "Narrow UI context for menu handlers (Phase 9, Step N)"
----
-
-# Retro: #146 — Narrow UI context for menu handlers
-
-## Final Retrospective (2026-05-23T10:00:00Z)
-
-### Session summary
-
-Introduced a `MenuUI` interface in `agent-menu.ts` capturing the 6 `ctx.ui` methods used by menu handlers.
-Replaced `ExtensionContext` with `MenuUI` (plus explicit `ModelRegistry` and `ParentSnapshot`) in all inner functions across `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts`.
-Dissolved three ≤4-field dependency bags (`AgentConfigEditorDeps`, `GetResultDeps`, `SteerToolDeps`) into plain parameters; destructured `AgentMenuDeps` and `AgentCreationWizardDeps` in their factory signatures.
-Eliminated 42 `ctx as any` casts across 5 test files.
-Released as `pi-subagents-v6.16.2`.
-
-### Observations
-
-#### What went well
-
-- **User-initiated plan review caught three ordering bugs before implementation.**
-  The user asked the agent to "review the plan and judge its quality and clarity" after the initial commit.
-  The review identified three execution-blocking problems in the TDD order: `MenuUI` not defined before consumers, `ParentSnapshot` not threaded through the handler return type, and `index.ts` call sites not updated alongside their factories.
-  All three were fixed before TDD execution began, saving significant implementation friction.
-- The plan's TDD order (after fixes) worked well for a pure-refactoring change — all 806 tests stayed green throughout every step.
-- The type checker served as an effective safety net: every call-site mismatch was caught immediately by `pnpm run check`, preventing runtime surprises.
-
-#### What caused friction (agent side)
-
-##### Planning session
-
-- `missing-context` — The initial plan had three TDD ordering bugs: (1) `MenuUI` used before defined, (2) `ParentSnapshot` not threaded through handler return type, (3) `index.ts` call sites not updated alongside factory signature changes.
-  These were caught by a user-prompted plan review, not by the planning agent itself.
-  Impact: would have caused type-check failures during TDD execution; fixed before implementation started.
-
-- `wrong-abstraction` — After fixing the plan, the agent ran `git commit --amend --no-edit` to update the plan commit, but it landed on the wrong commit (a stacked prompt-changes commit from a different session).
-  This caused divergent history with origin.
-  Recovery required `git reset --hard origin/main` and re-applying the plan fixes as a new commit (`3d5b591`).
-  Impact: ~5 minutes of git recovery and re-application of edits.
-
-##### Implementation session
-
-- `missing-context` — In Step 3, the plan listed the `WizardManager.spawnAndWait` signature change (to accept `ParentSnapshot`) and the `AgentMenuManager.spawnAndWait` change as separate steps (3 and 4).
-  But `agent-menu.ts` passes `deps.manager` (typed as `AgentMenuManager`) to `createAgentCreationWizard`, which expects `WizardManager`.
-  Changing `WizardManager` without also changing `AgentMenuManager` broke the type checker.
-  I had to pull the `AgentMenuManager` change forward from Step 4 into Step 3.
-  Impact: minor — a few minutes of diagnosis and one extra edit, no rework.
-
-- `missing-context` — In Step 2, after dissolving `AgentConfigEditorDeps` and changing `showAgentDetail(ctx)` to `showAgentDetail(ui: MenuUI)`, I forgot to update the call site in `agent-menu.ts` from `editor.showAgentDetail(ctx, agentName)` to `editor.showAgentDetail(ctx.ui, agentName)`.
-  The type checker caught it immediately.
-  Impact: added friction but no rework — one extra `pnpm run check` cycle.
-
-- `missing-context` — In Step 4, the `makeUI()` test helper used `modelRegistry: {}` which didn't satisfy the `ModelRegistry` interface (requires `find` and `getAll`).
-  Impact: one extra `pnpm run check` cycle and a one-line fix.
-
-- `missing-context` — In Step 5, two tests called `createGetResultTool(makeDeps())` directly (not via the `execute()` helper).
-  After dissolving deps, the factory signature changed but I only updated `execute()`.
-  The type checker caught the two direct calls.
-  Impact: one extra `pnpm run check` cycle.
-
-#### What caused friction (user side)
-
-- None observed — the session ran autonomously with no user corrections needed.
-
-#### What caused friction (user side — planning)
-
-- The user had to explicitly ask for a plan review (“I'd like you to review the plan and judge its quality and clarity”) to surface three ordering bugs.
-  The planning agent should have caught these during plan authoring — the testing skill already contains rules about TDD step ordering and shared interface changes.
-  The user's intervention prevented significant implementation friction.

package/docs/retro/0147-inject-wrap-text-into-conversation-viewer.md

@@ -1,90 +0,0 @@
----
-issue: 147
-issue_title: "Inject text wrapping into ConversationViewer (Phase 9, Step O)"
----
-
-# Retro: #147 — Inject text wrapping into ConversationViewer (Phase 9, Step O)
-
-## Stage: Planning (2026-05-23T00:00:00Z)
-
-### Session summary
-
-Read the issue, loaded package-pi-subagents, code-design, testing, and markdown-conventions skills.
-Explored `src/ui/conversation-viewer.ts`, `src/ui/agent-menu.ts`, `test/conversation-viewer.test.ts`, and the Phase 9 architecture roadmap.
-Wrote and committed the plan at `packages/pi-subagents/docs/plans/0147-inject-wrap-text-into-conversation-viewer.md`.
-
-### Observations
-
-- The change is tightly scoped: two source files (`conversation-viewer.ts`, `agent-menu.ts`) and one test file.
-- `wrapTextWithAnsi` is called in exactly four places inside `buildContentLines` — all in the same private method, making the replacement straightforward.
-- The only production call site for `new ConversationViewer({…})` is `viewAgentConversation` in `agent-menu.ts`.
-  `wrapTextWithAnsi` is added as a static import there and passed as `wrapText` — no threading through `AgentMenuDeps` needed.
-- All `new ConversationViewer({…})` calls in the test file are inline (no shared factory helper), so every call site needs the new `wrapText` field added.
-  Grep confirms the count: 11+ calls, all in `test/conversation-viewer.test.ts`.
-- The plan uses 2 TDD cycles: Cycle 1 adds the field and updates all call sites (with the `vi.mock` still present for safety); Cycle 2 removes the mock and converts dynamic `await import()` to static imports.
-  This ordering avoids a large simultaneous change and gives the suite a stable intermediate state.
-- The "mock is intercepting wrapTextWithAnsi" test is deleted in Cycle 1 (it verified the mock mechanism, not production behavior).
-- No exported API symbols are removed; `wrapText` is a new required field on `ConversationViewerOptions`, which is a breaking change only for external constructors of `ConversationViewer` — confirmed none exist outside this package.
-
-## Stage: Implementation — TDD (2026-05-23T11:36:00Z)
-
-### Session summary
-
-Completed both TDD cycles from the plan.
-Cycle 1 added `wrapText` to `ConversationViewerOptions`, destructured options in the constructor, replaced all four `wrapTextWithAnsi` calls with `this.wrapText`, updated `agent-menu.ts` to import and pass `wrapTextWithAnsi`, and updated all 16 test constructor call sites (11 render-width-safety + 5 safety-net) while keeping the `vi.mock` shim in place.
-Cycle 2 removed the `vi.mock` block, `wrapOverride`, and `beforeEach` reset, then converted the dynamic `await import()` calls to ordinary static imports.
-Test count: 806 → 805 (deleted the mock-mechanism sentinel test).
-Full suite 50 files, 805 tests, all green.
-
-### Observations
-
-- The plan said the render-width-safety constructor calls numbered "11+" — the actual count was 16 total (11 render-width-safety + 5 safety-net), all in `test/conversation-viewer.test.ts`.
-  No external call sites existed.
-- `wrapTextWithAnsi` needed to be added to the dynamic import in Cycle 1 (`const { visibleWidth, wrapTextWithAnsi } = await import(...)`) because the render-width-safety tests reference it by name.
-  The plan didn't call this out explicitly — minor omission.
-- Used a Python script (inline via bash) to make the 17 constructor-call edits rather than 17 separate Edit-tool calls.
-  The safety-net tests each had a different stub character (`X`, `Y`, `Z`, `B`, `W`) which required a regex capture group to preserve.
-  The script worked on the first attempt.
-- Cycle 2 was a single Edit call replacing the entire mock block + the two dynamic imports + `beforeEach`.
-  The autoformatter then cleaned up import ordering automatically.
-- Architecture doc updated: smells table row struck-through and Step O marked ✓.
-
-## Stage: Final Retrospective (2026-05-23T11:45:00Z)
-
-### Session summary
-
-Planned, implemented, shipped, and released issue #147 across a single session chain.
-Two TDD cycles completed cleanly; CI passed; issue closed; `pi-subagents-v6.17.0` released.
-Test count: 806 → 805 (deleted mock-mechanism sentinel test).
-
-### Observations
-
-#### What went well
-
-- Python script for bulk constructor edits worked first-try on 17 call sites with per-test regex capture groups.
-  This is now a proven pattern — #116 and #147 both used it successfully for `ConversationViewer` constructor changes.
-- Two-cycle TDD approach (Cycle 1: add DI with mock still present; Cycle 2: remove mock) gave a stable intermediate state and caught the missing `wrapTextWithAnsi` import before proceeding.
-- Scope was tight: 3 files changed, 2 commits of substance, no rework on the production code.
-
-#### What caused friction (agent side)
-
-1. `instruction-violation` — Failed to load the `colgrep` skill during planning.
-   Constructed the path by pattern (`.pi/skills/colgrep/SKILL.md`) instead of using the `<location>` listed in the `<available_skills>` block (`packages/pi-colgrep/skills/colgrep/SKILL.md`).
-   Got ENOENT and silently moved on.
-   Impact: user-caught; required a follow-up exchange to load the skill and re-review the plan.
-   No rework needed — the plan was already correct.
-2. `wrong-abstraction` — Cycle 2 Edit replaced the entire `vi.mock` block + dynamic imports as one chunk, leaving the `ConversationViewer` static import stranded after `const testRegistry` instead of at the top with other imports.
-   Impact: user-caught ("Wait, we have a dynamic import?"); required a follow-up edit and amend into the retro commit.
-3. `missing-context` — Plan stated "11+" constructor call sites; actual count was 16 (11 render-width-safety + 5 safety-net).
-   The grep output during planning showed all 16 but the count wasn't verified.
-   Impact: no rework — the Python script handled all 17 (16 test + 1 production) regardless.
-
-#### What caused friction (user side)
-
-- No friction identified — user interventions were timely and precise.
-
-### Changes made
-
-1. Appended this final retrospective entry to `packages/pi-subagents/docs/retro/0147-inject-wrap-text-into-conversation-viewer.md`.
-2. Separated `colgrep` skill loading into its own bullet in `.pi/prompts/plan-issue.md` to reduce pattern-matching shortcuts.
-3. Replaced deterministic step in `.pi/prompts/retro.md` with a "Sync with remote" section matching the other prompts.

package/docs/retro/0148-split-agent-widget-rendering.md

@@ -1,39 +0,0 @@
----
-issue: 148
-issue_title: "Split AgentWidget rendering from lifecycle (Phase 9, Step P)"
----
-
-# Retro: #148 — Split AgentWidget rendering from lifecycle
-
-## Final Retrospective (2026-05-23T06:20:00Z)
-
-### Session summary
-
-Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
-The widget shrank from 374 to 198 lines — now a thin lifecycle wrapper. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
-Released as `pi-subagents-v6.16.1`.
-
-### Observations
-
-#### What went well
-
-- TDD cycles were fast and clean: 9 commits, all tests green on first or second try, zero test regressions across the full 806-test suite.
-- The `WidgetAgent` / `WidgetActivity` interfaces worked well as structural subsets — `AgentRecord` and `AgentActivityTracker` satisfy them without mapping code.
-- The stub `Theme` pattern from `test/renderer.test.ts` (`fg: (c, t) => \`[\${c}:\${t}]\``) transferred cleanly to the new test file, keeping assertions readable.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's `renderWidgetLines` API spec omitted `theme` from its parameters, even though the heading, tree connectors, and per-agent render calls all require it.
-  Caught immediately at step 4 (first `renderWidgetLines` test) and fixed by adding `theme` to the params.
-  Impact: deviation note in commit body; no rework.
-
-- `missing-context` — Step 3 (`renderRunningLines` implementation) initially missed importing `SPINNER` from `display.ts`.
-  The test caught it as a runtime `ReferenceError`, fixed in the same Red→Green cycle.
-  Impact: added friction but no rework.
-
-- `wrong-abstraction` — Step 8 ("Extract into `widget-renderer.ts`") was a no-op because the module was created incrementally during steps 1–7 (tests must import from the new module to run).
-  Impact: step skipped; noted in summary.
-
-#### What caused friction (user side)
-
-- None observed — the session ran autonomously from plan through ship with no user corrections needed.