@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/retro/0061-session-format-transcript.md

@@ -1,41 +0,0 @@
----
-issue: 61
-issue_title: "feat: port subagent transcript logging to Pi's official JSONL session format"
----
-
-# Retro: #61 — port subagent transcript logging to Pi's official JSONL session format
-
-## Final Retrospective (2026-05-20T17:15:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a migration from the bespoke `output-file.ts` transcript format to Pi's official JSONL session format via `SessionManager.create()`.
-The change replaced 143 lines of manual streaming code with 3 lines leveraging the SDK's native persistence, nested subagent sessions under the parent session directory with `parentSession` header linking.
-Released as `pi-subagents-v6.0.0` (major version bump due to breaking transcript format change).
-
-### Observations
-
-#### What went well
-
-- The plan-to-implementation translation was clean: 6 TDD steps mapped to 7 commits (one extra `fix:` for biome lint).
-  No steps needed reordering or merging.
-- The `ask_user` design decision gates during planning (persistence strategy, file location) produced clear answers that avoided rework during implementation.
-- Research into nicobailon/pi-subagents, edxeth/pi-subagents, and HazAT/pi-interactive-subagents provided useful reference for the session directory layout, confirming the parent-relative nesting pattern.
-- The biome lint catch on the unused `cwd` parameter led to a better design — incorporating `cwd` into the temp fallback path for project namespacing — rather than a mechanical underscore prefix.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan listed test impact for `agent-runner.test.ts` but didn't grep for other test files mocking `SessionManager` or `ctx.sessionManager`.
-  Three additional files needed updating: `agent-runner-extension-tools.test.ts`, `print-mode.test.ts`, and `test/tools/agent-tool.test.ts`.
-  The testing skill explicitly says "grep for ALL test files that construct a compatible mock — not just factory helpers."
-  Impact: ~5 minutes of reactive fixes during Step 4.
-  Self-identified at implementation time.
-
-- `missing-context` — The plan didn't account for the timing difference between the old synchronous `record.outputFile` assignment (immediately after `spawn()`) and the new asynchronous availability (after `SessionManager.create()` runs inside `runAgent()`).
-  This required adding `session.sessionManager.getSessionFile()` in the `onSessionCreated` callback — a design decision made during implementation.
-  Impact: minor within-step rework, no extra commit needed.
-
-#### What caused friction (user side)
-
-- The dependency update to 0.75.4 was a reasonable pre-plan request, but it added ~10 minutes of tangential work (diagnosing `pnpm update` resolution behavior, normalizing version specifiers).
-  This could have been a separate commit/session, though batching it was pragmatic since it gave the plan access to the latest SDK types.

package/docs/retro/0066-replace-as-any-with-sdk-types.md

@@ -1,44 +0,0 @@
----
-issue: 66
-issue_title: "refactor: replace `as any` casts in extracted tool/menu factories with proper SDK types"
----
-
-# Retro: #66 — replace `as any` casts with proper SDK types
-
-## Final Retrospective (2026-05-20T18:50:00Z)
-
-### Session summary
-
-Replaced all 14 `as any` casts in `src/index.ts` by typing 5 factory dep interfaces with proper SDK types (`ExtensionContext`, `AgentSession`, `ExtensionAPI`, `ModelRegistry`) and the newly-exported `SpawnOptions`.
-Released as `pi-subagents-v5.8.1` with zero behavioral change across 520 tests.
-The plan, implementation, and shipping were completed in a single session with 6 implementation commits.
-
-### Observations
-
-#### What went well
-
-- Thorough context-gathering during planning paid off: reading all 5 dep interfaces, the SDK `.d.ts` files, test mock helpers, and the `ExtensionUIContext` shape before writing the plan meant most steps landed on first `pnpm run check`.
-- The plan's risk table anticipated the cascading `as any` issue on `createAgentTool` and prepared a mitigation ("add explicit `satisfies ToolDefinition<…>` if needed"), which was close to the actual fix needed.
-- Steps 4 and 5 (`GetResultDeps`, `SteerToolDeps`) were trivially clean — single-type-import changes that compiled immediately.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan assumed `NotificationDeps.sendMessage.display` could be optional (`display?: boolean`) but the SDK's `CustomMessage.display` is required `boolean`.
-  First `pnpm run check` after step 2 failed; required one extra edit-verify cycle.
-  Impact: added friction but no rework (fixed in the same commit).
-
-- `missing-context` — The plan did not check the `execute` function's full signature in `agent-tool.ts`.
-  Removing the outer `as any` on `createAgentTool({...})` exposed three additional type mismatches: `onUpdate` parameter type (`unknown` vs `AgentToolResult<any>`), `signal` optionality (`AbortSignal` vs `AbortSignal | undefined`), and `params.description` (`unknown` vs `string`).
-  The plan flagged cascading risk but assumed only the return type would be affected.
-  Impact: step 3 required three extra edits and two extra `pnpm run check` cycles, noted as a deviation in the commit body.
-
-- `missing-context` — Steps 6 and 7 had to be folded into one commit.
-  The plan listed them as independent steps but typing `AgentMenuManager.spawnAndWait(ctx: ExtensionContext)` immediately made `MenuContext` incompatible — `showGenerateWizard` passes `ctx: MenuContext` to the dep callback that now expects `ExtensionContext`.
-  The testing skill already warns: "when a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k."
-  The planner failed to recognize that `MenuContext` and `AgentMenuManager.spawnAndWait` share a type dependency through `ctx`.
-  Impact: no rework — the steps were folded successfully — but the plan's step count was inaccurate.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The user ran three sequential prompts (`/plan-issue 66`, `/tdd-plan`, `/ship-issue`) with no corrections or redirects needed.

package/docs/retro/0069-create-subagent-runtime.md

@@ -1,43 +0,0 @@
----
-issue: 69
-issue_title: "refactor: eliminate module-scope mutable state in pi-subagents — create SubagentRuntime"
----
-
-# Retro: #69 — create SubagentRuntime
-
-## Final Retrospective (2026-05-19T16:47:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped `SubagentRuntime` — a composition-root object that replaces module-scope mutable state in `agent-runner.ts` and closure-scoped state in `index.ts`.
-Six TDD steps completed with one deviation: `agent-tool.ts` and `agent-menu.ts` also imported the removed getter/setter exports, requiring unplanned fixes.
-Released as `pi-subagents-v5.2.0`.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift strategy (introduce `RunOptions` fields alongside module-scope fallback, wire consumers, then remove old path) kept the 460-test suite green through every intermediate commit.
-  No step broke existing tests.
-- `pnpm run check` caught the two missing downstream files (`agent-tool.ts`, `agent-menu.ts`) immediately after the removal step.
-  The typecheck-after-removal safety net worked exactly as intended.
-- The `pi-permission-system` prior art (`ExtensionRuntime` in #43) provided a clear structural template, reducing design decisions to near zero.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's Module-Level Changes listed `agent-runner.ts`, `agent-manager.ts`, and `index.ts` but missed `src/tools/agent-tool.ts` and `src/ui/agent-menu.ts`, both of which imported `getDefaultMaxTurns`/`setDefaultMaxTurns`/`getGraceTurns`/`setGraceTurns` from `agent-runner.ts`.
-  A grep for all importers of the removed symbols during planning would have caught this.
-  Impact: 4 extra files touched in step 5 (the two source files + their test helpers); no rework of earlier steps, but the commit scope was wider than planned. (self-identified at `pnpm run check` time)
-
-- `missing-context` — In step 3 (`agent-manager.test.ts`), checked `vi.mocked(runAgent).mock.calls[0]` without clearing the mock first.
-  The module-level `vi.mock("../src/agent-runner.js")` is shared across all describe blocks, so `calls[0]` picked up a stale invocation from an earlier test.
-  Impact: one debug cycle adding `vi.mocked(runAgent).mockClear()` after `resolvedRun()`. (self-identified)
-
-#### What caused friction (user side)
-
-- Nothing notable.
-  The plan was unambiguous, and the session ran without user intervention beyond the initial prompts.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added grep-importers rule to the Module-Level Changes bullet: when a step removes or renames an export, grep all `src/` and `test/` files for every removed symbol before finalizing the file list.

package/docs/retro/0070-extract-event-handlers.md

@@ -1,49 +0,0 @@
----
-issue: 70
-issue_title: "refactor: extract event handlers from pi-subagents index.ts into src/handlers/"
----
-
-# Retro: #70 — extract event handlers from index.ts
-
-## Final Retrospective (2026-05-20T19:30:00Z)
-
-### Session summary
-
-Planned and implemented #70 — extracting four inline event handler lambdas from `src/index.ts` into `src/handlers/lifecycle.ts` (`SessionLifecycleHandler` class) and `src/handlers/tool-start.ts` (`ToolStartHandler` class).
-During planning, the user identified that the initial plain-function design missed shared collaborators and structural smells, prompting a redesign to class-based handlers and a predecessor issue (#87) to evolve `SubagentRuntime` from a data bag to an object with methods.
-Released as `pi-subagents-v5.8.0` with 8 new handler tests (520 total).
-
-### Observations
-
-#### What went well
-
-- The user's progressive questioning during planning ("Are you confident?", "Keep digging", Kent Beck quote) surfaced two concrete structural smells — output arguments on `runtime.currentCtx` writes and 8 LoD violations via `runtime.widget!` reach-throughs — that the initial design would have just relocated rather than fixed.
-- Filing predecessor #87 was the right sequencing call.
-  By the time #70 executed, the runtime had proper methods and the handler extraction was purely mechanical.
-- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
-  The only issue was a `tsc` type error (`vi.fn()` return type not assignable to `() => void`) caught during the post-TDD type check and fixed in-place before the final commit.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — The initial plan used plain functions with per-call `LifecycleDeps`/`ToolStartDeps` interfaces, the first viable approach, without analyzing whether handlers shared collaborators.
-  The user had to prompt three times before I switched to class-based handlers with constructor-injected shared deps.
-  Impact: three rounds of plan revision before the design was correct; no rework commits, but significant planning churn.
-
-- `instruction-violation` (user-caught) — The `/plan-issue` prompt says "load the `design-review` skill and run its checklist on the affected modules."
-  I loaded the skill but did not actually run the checklist (grep for access patterns, check LoD, check output arguments) until the user explicitly told me to "keep digging."
-  Had I run the checklist proactively, the output-argument and LoD findings would have surfaced on the first pass, and the predecessor issue (#87) would have been identified without user escalation.
-  Impact: user had to escalate three times; planning took ~3× longer than necessary.
-
-- `wrong-abstraction` — I initially reasoned at the mechanical level ("handlers are small, 1–5 lines, so plain functions are fine") instead of the structural level ("do these handlers share collaborators that a class captures naturally?").
-  The code-style skill explicitly says "Do not pass a shared dependency bag to functions that only use a subset" — but I applied it backwards (splitting into per-function deps) rather than recognizing the shared deps as a class cohesion signal.
-  Impact: same as premature-convergence above; folded into the same rework cycle.
-
-#### What caused friction (user side)
-
-- The progressive escalation approach (question → directive → quote) was effective pedagogically but required three turns of user attention on what a proactive design-review checklist run would have caught automatically.
-  Earlier intervention with a specific redirect (e.g., "Run the design-review checklist before writing the plan") could have resolved it in one turn.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0070-extract-event-handlers.md`.
-2. Updated `packages/pi-subagents/docs/architecture/architecture.md` — marked #87 and #70 as done (✓), updated Phase 2 status to complete, updated next-issue pointer to #66.

package/docs/retro/0071-extract-session-config-assembler.md

@@ -1,60 +0,0 @@
----
-issue: 71
-issue_title: "refactor: extract pure agent-session assembler from agent-runner.ts"
----
-
-# Retro: #71 - extract session-config assembler
-
-## Final Retrospective (2026-05-19T22:15:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped `assembleSessionConfig()` - a pure configuration assembler extracted from `runAgent()` in `agent-runner.ts`.
-Eight TDD steps completed across three phases (plan, implement, ship), adding 33 new tests in `test/session-config.test.ts` and reducing `runAgent()` from ~390 lines to ~198.
-Released as `pi-subagents-v5.3.0`.
-Filed follow-up #80 (consolidate `getConfig`/`getAgentConfig`) and updated the architecture roadmap.
-
-### Observations
-
-#### What went well
-
-- The user's redirecting question ("Do we need more decomposition?
-  Are there any seams we can exploit?") at the `as any` fix point was perfectly timed.
-  It shifted the approach from mechanical casting (8 `as any` casts) to a structural fix: `unknown` for opaque model handles, `Array<{ provider: string; id: string }>` for the availability check.
-  The final design removed the `@earendil-works/pi-ai` import from `session-config.ts` entirely - cleaner than the plan's original specification of `Model<any>`.
-- The prior art from `pi-permission-system` (`evaluate()` extraction) provided a clear template for the pure-core-from-IO-shell pattern.
-  Design decisions were minimal.
-- All 451 existing tests stayed green through every intermediate commit.
-  The mock-at-module-boundary strategy (`vi.mock("../src/agent-types.js")` etc.) meant existing `agent-runner.test.ts` mocks continued to intercept the same module paths even after the assembler delegated to them.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` - When `pnpm run check` surfaced 10 type errors from `Model<any>` in `SessionConfig`, the first fix attempt was adding `as any` casts to the `vi.fn` factory return values and all test model objects (8 casts total).
-  This partially addressed the symptom but created new `never[]` inference errors and left a fundamentally wrong interface.
-  The user's first pushback ("Can we find a real type?") prompted a proper analysis of `Model<TApi>`'s ~10 required fields, leading to the `unknown` solution.
-  Impact: ~20 minutes of rework across 3 attempts (the `as any` factory cast, diagnosing the residual `never[]` errors, and the final `unknown` rewrite). (user-caught)
-
-- `missing-context` - The plan omitted `agentMaxTurns` from the `SessionConfig` return type.
-  `runAgent()`'s turn-limit resolution reads `agentConfig?.maxTurns`, which is no longer available after the assembly delegation.
-  Caught during step 7 (wiring) when the code wouldn't compile without it.
-  Impact: added one field to `SessionConfig` and `assembleSessionConfig`; no rework of earlier steps, but the commit body noted the deviation. (self-identified at implementation time)
-
-- `missing-context` - The `vi.fn(() => [])` → `never[]` TypeScript inference issue wasn't anticipated.
-  Five mock factories (`mockGetMemoryToolNames`, `mockGetReadOnlyMemoryToolNames`, `mockPreloadSkills`, `mockRegistry.find`, `mockRegistry.getAvailable`) needed explicit return-type annotations.
-  Impact: one debug cycle to diagnose, then a second to fix with `import type` annotations. (self-identified during `pnpm run check`)
-
-#### What caused friction (user side)
-
-- The user's second pushback ("Do we need more decomposition?") was the highest-leverage intervention in the session.
-  Without it, the `as any` approach would have landed and the `pi-ai` import would have stayed in `session-config.ts` - defeating the goal of a SDK-free business-logic module.
-  The pattern of catching design-level issues through "is there a better seam?"
-  questions is worth preserving.
-
-#### Design observations (not actionable as rules)
-
-- The `cfg.model as Model<any> | undefined` cast in `agent-runner.ts` is a legitimate interim cost — it's one line at the SDK boundary and will be resolved when #66 (replace `as any` casts with proper SDK types) and #72 (AgentManager DI) refine the interface contracts.
-  Codifying “use `unknown` + boundary cast” as a general pattern would normalize something that should feel uncomfortable and motivate further interface refinement.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added `vi.fn()` return-type annotation rule under “Vitest mock patterns”: annotate factories that return empty arrays or narrow literals to prevent `never[]` inference.

package/docs/retro/0072-inject-agent-manager-collaborators.md

@@ -1,46 +0,0 @@
----
-issue: 72
-issue_title: "refactor: dependency-inject AgentManager's collaborators"
----
-
-# Retro: #72 — dependency-inject AgentManager's collaborators
-
-## Final Retrospective (2026-05-20T17:50:00Z)
-
-### Session summary
-
-Defined `AgentRunner` and `WorktreeManager` interfaces, converted `AgentManager`'s 6-positional-parameter constructor to an options bag with injected collaborators, migrated all 19 test sites from `vi.mock()` to `vi.fn()` stubs, and added 7 new DI-enabled tests.
-The planning phase required significant user redirection to arrive at the right abstractions; the TDD execution phase was clean with zero rework.
-Released as `pi-subagents-v5.6.0`.
-
-### Observations
-
-#### What went well
-
-- The `ask_user` interactions during planning surfaced genuine design decisions (options bag vs positional constructor, lifecycle callback grouping) that the issue body left open.
-  The user's responses were substantive and redirecting.
-- The user's "make the change that makes the change easy" framing identified #84 (`GitWorktreeManager` extraction) as a prerequisite, which made #72's implementation clean — zero type-shuffling needed.
-- The lift-and-shift test migration (Phase B → Phase C) worked exactly as planned: introduce `createManager()` helper under the old constructor, then switch it to the options bag atomically.
-  All 19 test sites migrated with no logic changes.
-- `Promise.withResolvers` (ES2024) in the new queueing test made controlled async coordination clean — no manual resolve/reject wiring.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Spent ~4 analysis cycles on "how to move types between files" (`ToolActivity`, `RunOptions`, `WorktreeInfo` → `types.ts`) when the real question was "what objects want to exist?"
-  The user had to redirect three times: "are there real objects with state?", "what state IS in AgentRunner?", and "we haven't pulled all the threads."
-  Impact: added ~10 minutes of back-and-forth during planning, but ultimately produced a better design (stateful `WorktreeManager` vs stateless `AgentRunner` seam, plus #84 as prep).
-  The dependency-graph analysis itself was sound — it confirmed no circular deps — but it answered a question nobody was asking.
-
-- `premature-convergence` — First draft of the plan included `WorktreeManager` extraction as "Phase A step 1" inside #72.
-  The user asked "did we create another issue that we need to tackle first?"
-  — pointing out that the prep work should be its own issue.
-  Impact: minor rework to update the plan and file #84; no code rework since it was caught during planning. (User-caught.)
-
-#### What caused friction (user side)
-
-- The user's early redirect ("take a step back — does the AgentManager really need six params?") could have been even more direct — e.g., "before we discuss constructor shape, what higher-level abstractions are missing?"
-  That said, the Socratic approach ultimately led to a better shared understanding of why `WorktreeManager` is a real object and `AgentRunner` is a seam.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0072-inject-agent-manager-collaborators.md`.

package/docs/retro/0076-inject-cwd-into-agent-manager.md

@@ -1,35 +0,0 @@
----
-issue: 76
-issue_title: "refactor: inject cwd into AgentManager constructor instead of reading process.cwd() in dispose()"
----
-
-# Retro: #76 — inject cwd into AgentManager constructor
-
-## Final Retrospective (2026-05-19T21:00:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a single-step refactoring that injects `cwd: string` into the `AgentManager` constructor, replacing the `process.cwd()` call in `dispose()` with `this.cwd`.
-Released as `pi-subagents-v5.4.1`.
-The entire cycle (plan → TDD → ship → release) completed in one session with one minor friction point.
-
-### Observations
-
-#### What went well
-
-- Clean single-commit implementation: one `refactor:` commit touched 3 files, updated 18 test constructor calls plus one production call site, and added one new assertion — all green on first run.
-- TDD Red phase worked well despite the plan calling this a "single-step refactoring."
-  Writing a new test (`"calls pruneWorktrees with the cwd passed to the constructor"`) gave a clear Red signal before the implementation change, even though the constructor signature change had to be applied atomically.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan's "Test Impact Analysis" stated "No new unit tests are needed" and framed existing tests as sufficient.
-  In practice, the existing tests only called `dispose()` in `afterEach` hooks without assertions on `pruneWorktrees` arguments, so a new test was needed for a proper Red phase.
-  The user noticed the discrepancy before TDD began ("We will at least alter some tests, right?").
-  Impact: one clarifying exchange, no rework.
-  User-caught.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's question about test changes was a useful early catch that would have surfaced during TDD anyway.

package/docs/retro/0077-inject-project-agents-dir.md

@@ -1,33 +0,0 @@
----
-issue: 77
-issue_title: "refactor: add projectAgentsDir to AgentMenuDeps instead of reading process.cwd() inline"
----
-
-# Retro: #77 — inject projectAgentsDir into AgentMenuDeps
-
-## Final Retrospective (2026-05-20T16:15:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a refactoring that adds `projectAgentsDir: string` to `AgentMenuDeps`, replacing the inline `process.cwd()` lambda in `createAgentsMenuHandler`.
-The change mirrors the existing `personalAgentsDir` injection pattern.
-Released as `pi-subagents-v5.8.2`.
-
-### Observations
-
-#### What went well
-
-- Clean end-to-end execution: plan → TDD → ship with zero corrections or rework.
-- The Red test was well-targeted: exercised `findAgentFile` through the menu navigation path and naturally failed because `process.cwd()` produced a different path than the injected `/test-project/.pi/agents`.
-- Correctly identified at execution time that the plan's two-step TDD split was impractical (interface change is atomic) and combined into a single `refactor:` commit.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` — The plan listed two TDD commits (step 1: `test:`, step 2: `refactor:`) but adding a required field to `AgentMenuDeps` is an atomic change — the test references the new field, so both must land together.
-  The testing skill's shared-type-definition rule ("changing that type in step N breaks steps N+1…N+k — fold them into one step") should have been applied during planning.
-  Impact: added friction but no rework — the deviation was self-identified at execution time and the steps were combined.
-  Self-identified.
-
-#### What caused friction (user side)
-
-- None observed.

package/docs/retro/0080-consolidate-agent-config-lookup.md

@@ -1,35 +0,0 @@
----
-issue: 80
-issue_title: "refactor: consolidate getConfig / getAgentConfig into a single resolution path"
----
-
-# Retro: #80 — consolidate getConfig / getAgentConfig
-
-## Final Retrospective (2026-05-20T00:35:00Z)
-
-### Session summary
-
-Consolidated two overlapping agent config lookup functions (`getConfig` and `getAgentConfig`) into a single `resolveAgentConfig(type): AgentConfig` with a guaranteed-non-null return and internal fallback chain.
-Migrated all 6 source callers and 5 test files across 6 TDD commits, then shipped as `pi-subagents-v5.4.0`.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift migration strategy (add new function → migrate callers incrementally → remove old functions) kept every commit green.
-  No intermediate step broke the test suite.
-- The planning phase correctly identified an under-documented scope question (callers beyond the two mentioned in the issue) and used `ask-user` to resolve it before writing the plan.
-- The `test/prompts.test.ts` caller, missed by the plan, was caught cleanly during the final grep sweep in step 6 — no rework needed, just an additional edit in the same commit.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan specified that `resolveAgentConfig` should fall back for disabled types (matching `getConfig`'s semantics), but didn't trace what `agent-menu.ts` actually reads from disabled configs.
-  `agent-menu.ts` iterates `getAllTypes()` (including disabled agents) and needs the real config to render `✕` indicators, source badges, and `(disabled)` descriptions.
-  With fallback-for-disabled semantics, disabled agents would silently display as general-purpose.
-  Caught during step 4 while editing `agent-menu.ts`, before any wrong test assertions ran.
-  Impact: required changing `resolveAgentConfig` semantics (only fall back for unknown types, not disabled) and updating the step 1 test — a ~5 minute fix folded into the step 4 commit.
-
-#### What caused friction (user side)
-
-- Nothing notable.
-  The user's `ask-user` response during planning ("remove both, migrate all callers") was clear and included a useful directional note about computing values earlier.

package/docs/retro/0084-extract-git-worktree-manager.md

@@ -1,37 +0,0 @@
----
-issue: 84
-issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
----
-
-# Retro: #84 — extract GitWorktreeManager class from worktree.ts free functions
-
-## Final Retrospective (2026-05-20T13:31:00Z)
-
-### Session summary
-
-Extracted a `WorktreeManager` interface and `GitWorktreeManager` class from the three free functions in `worktree.ts`.
-The two-step TDD cycle (add tests → add implementation) executed cleanly with no rework or deviations from the plan.
-Released as `pi-subagents-v5.5.0`.
-
-### Observations
-
-#### What went well
-
-- The issue body included an exact "Proposed Interface" section with TypeScript code, which made the plan nearly mechanical and eliminated all design ambiguity.
-  The `ask-user` step was correctly skipped.
-- The two-step TDD cycle was appropriately minimal for a thin delegation extraction — no over-engineering of the test or commit structure.
-- The full pipeline (plan → TDD → ship → release) completed in a single pass with zero corrections.
-
-#### What caused friction (agent side)
-
-No friction observed.
-The issue was well-scoped and the existing pipeline instructions handled every step.
-
-#### What caused friction (user side)
-
-No friction observed.
-The pipeline was driven cleanly with `/plan-issue` → `/tdd-plan` → `/ship-issue`.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0084-extract-git-worktree-manager.md`.

package/docs/retro/0087-evolve-subagent-runtime-methods.md

@@ -1,42 +0,0 @@
----
-issue: 87
-issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
----
-
-# Retro: #87 — evolve SubagentRuntime from data bag to object with methods
-
-## Final Retrospective (2026-05-20T18:00:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped #87 — converting `SubagentRuntime` from a plain interface + factory into a class with session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
-All 10 call sites in `index.ts` were migrated, eliminating raw `currentCtx` field writes and `runtime.widget!` reach-throughs.
-Released as `pi-subagents-v5.7.0`.
-
-### Observations
-
-#### What went well
-
-- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
-  Test count went from 5 → 16 in `runtime.test.ts`; all 512 package tests stayed green throughout.
-- The user identified a missing architecture update and a pre-existing hallucination (`@earendil-works/pi-subagents` → `@gotgenes/pi-subagents`) after the plan commit.
-  The fix was a single well-scoped commit (`ddee1a0`) that corrected 10 scope references, updated the dependency graph to include #87 as a precursor to #70, and fixed list numbering per phase heading.
-- The plan's "Call sites to migrate" tables with exact line numbers and before/after code made step 3 (the refactoring commit) purely mechanical — no design decisions at implementation time.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In TDD step 2, the new `describe` block used `vi.fn()` but the test file's import was `{ describe, expect, it }` without `vi`.
-  The first red run surfaced this immediately (`ReferenceError: vi is not defined`) and it was fixed before the green step.
-  Impact: one extra test run, no rework commits.
-- `scope-drift` — The `/plan-issue` prompt does not instruct updating `architecture.md`, but the user noticed #87 was missing from the roadmap's dependency graph.
-  The agent hadn't checked `architecture.md` during planning even though #87 is explicitly listed as a precursor to #70 in the #70 plan.
-  Impact: user-caught; required a follow-up edit pass after the plan commit.
-
-#### What caused friction (user side)
-
-No friction observed.
-The user's correction about `architecture.md` was well-targeted and caught a real gap.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0087-evolve-subagent-runtime-methods.md`.

package/docs/retro/0098-extract-agent-record-state-machine.md

@@ -1,46 +0,0 @@
----
-issue: 98
-issue_title: "Extract AgentRecord state machine from scattered status transitions"
----
-
-# Retro: #98 — Extract AgentRecord state machine
-
-## Final Retrospective (2026-05-20T23:45:00Z)
-
-### Session summary
-
-Converted `AgentRecord` from a plain interface to a class with 7 encapsulated transition methods, centralizing the scattered status-transition logic from 6 locations in `agent-manager.ts`.
-The prerequisite issue #102 (shared test factory) made the class conversion a 2-file change instead of an 8-file rewrite.
-Released as `pi-subagents-v6.1.0`.
-
-### Observations
-
-#### What went well
-
-- The "encapsulate last" TDD strategy (cycles 1–5 with public fields, cycle 6 makes them private) let the compiler verify migration completeness before locking down access.
-  `get-result-tool.test.ts` and `make-record.test.ts` failures were caught immediately.
-- The worktree-reorder design insight (compute final result including branch text before calling the transition method) avoided the need for an `appendToResult()` method and survived implementation unchanged.
-- The prerequisite issue #102 (shared `createTestRecord` factory) proved essential — the class conversion touched only the factory and `agent-manager.ts`, not 8 individual test files.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — The initial plan proposed `MutableAgentRecord` alongside the existing interface, which was the lowest-friction path but the wrong abstraction.
-  The user redirected twice ("It should definitely become a class" → "I meant encapsulate") before the design was right.
-  Impact: full plan rewrite and an extra prerequisite issue (#102).
-  The plan template's "use ask-user for ambiguous design choices" instruction applied (class vs wrapper was genuinely ambiguous), but I didn't invoke it.
-
-- `missing-context` — The revised plan stated "No test files need updating (except the shared factory)" but missed `{ ...baseRecord, field }` spread patterns in `test/notification.test.ts`, `test/service-adapter.test.ts`, `test/tools/get-result-tool.test.ts`, and `test/helpers/make-record.test.ts`.
-  Spreading a class instance produces a plain object that lacks the class's methods.
-  Impact: 4 extra test files needed mechanical fixes in cycles 4 and 6; plan's "Unchanged files" list was wrong.
-  The compiler caught all of them, so no behavioral risk, but the plan should have predicted the churn.
-
-#### What caused friction (user side)
-
-- The issue body was intentionally flexible ("onto AgentRecord (or a thin wrapper)"), which left the wrapper-vs-class decision open.
-  The user's preference for a class with encapsulated state became clear only after seeing the initial plan.
-  Earlier signal (e.g., labeling the issue with a "class conversion" tag or stating "must encapsulate" in the issue body) would have avoided the plan rewrite.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — Added interface→class spread-pattern rule to TDD planning rules.
-2. `.pi/skills/package-pi-subagents/SKILL.md` — Added `agent-record.ts` to the Core engine module table and updated `types.ts` description.

package/docs/retro/0099-replace-ctx-with-parent-snapshot.md

@@ -1,37 +0,0 @@
----
-issue: 99
-issue_title: "Replace live `ctx` capture with ParentSnapshot in AgentManager"
----
-
-# Retro: #99 — Replace live ctx capture with ParentSnapshot
-
-## Final Retrospective (2026-05-20T20:30:00-04:00)
-
-### Session summary
-
-Implemented the `ParentSnapshot` extraction — Step 2 of the AgentManager internal decomposition.
-The user prompted a mid-planning restructure using Kent Beck's "make the change that makes the change easy" principle, which split the work into two clean phases: pi-elimination prep (cycles 1–2), then snapshot introduction (cycles 3–5).
-All 5 cycles landed first-try with no rework, releasing as `pi-subagents-v6.2.0`.
-
-### Observations
-
-#### What went well
-
-- The two-phase plan structure (prep then payload) kept each cycle focused on one concern.
-  Cycle 5 was particularly clean — only 2 files changed because `buildParentSnapshot` was mocked in agent-manager tests.
-- `sed` for mechanical bulk replacements (27 `spawn(mockPi,` → `spawn(mockCtx,`) was the right tool — faster and less error-prone than 27 individual edits.
-- The `pnpm run check` after cycle 4 caught exactly the expected type error in `agent-manager.ts`, confirming the incremental approach was working as designed.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Initial plan (before user intervention) interleaved pi-elimination and snapshot concerns across all 5 cycles.
-  The user had to invoke Kent Beck's principle to trigger the restructure.
-  Impact: one plan rewrite (amend commit), but no implementation rework since it happened before coding started.
-
-- `missing-context` — Used `Parameters<typeof createAgentSession>[0]["modelRegistry"]` as a type cast without checking that the SDK's `createAgentSession` parameter type is a union including `undefined`.
-  Impact: minimal — caught immediately by `pnpm run check`, fixed with a simple `as any` in the same cycle.
-
-#### What caused friction (user side)
-
-- The user's "make the change easy" prompt was well-timed — after the plan was written but before implementation.
-  No suggestions for improvement here; the intervention was strategic and well-placed.

package/docs/retro/0100-replace-callback-threading-with-session-subscription.md

@@ -1,36 +0,0 @@
----
-issue: 100
-issue_title: "Replace callback threading with direct session-event subscription"
----
-
-# Retro: #100 — Replace callback threading with direct session-event subscription
-
-## Final Retrospective (2026-05-20T22:30:00-04:00)
-
-### Session summary
-
-Implemented Step 3 of the AgentManager internal decomposition — replacing the 3-layer callback-threading pattern with two independent session observers (`subscribeRecordObserver` and `subscribeUIObserver`).
-Five TDD cycles landed with only one unanticipated test breakage, releasing as `pi-subagents-v6.3.0`.
-`SpawnOptions` dropped 5 `on*` fields, `RunOptions` dropped 5, and `ResumeOptions` dropped 3, with net −220 lines of source code removed.
-
-### Observations
-
-#### What went well
-
-- The phased plan structure (extract observers → wire AgentManager → wire agent-tool → simplify runner) created clean isolation between cycles.
-  Each cycle touched 1–2 source files and 1 test file, making changes easy to review.
-- Upgrading `mockSession()` once in cycle 3 to support `subscribe()` and `emit()` was a one-time investment that made the stat-verification tests more realistic — events now drive record state instead of manually calling callbacks on `RunOptions`.
-- The `resume()` simplification was particularly clean: 10 lines of callback wiring reduced to 2 lines (`subscribeRecordObserver` + `runner.resume` with only `{ signal }`).
-- All 5 TDD cycles except one landed first-try with no rework.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan listed `bindExtensions({ onError })` as part of the unchanged runner code, but the `onError` handler called `options.onToolActivity` which was removed in cycle 5.
-  The plan said "grep for `ToolActivity`" but the reference was inside a function literal passed to `bindExtensions`, not a type import.
-  Impact: one unexpected test failure in cycle 5 (`bindExtensions` test expected `onError`), caught immediately and fixed in the same commit.
-  Noted in commit body as a plan deviation.
-
-#### What caused friction (user side)
-
-- No friction observed.
-  The issue description was thorough and unambiguous, and the user's involvement was limited to triggering each phase (`/plan-issue`, `/tdd-plan`, `/ship-issue`).

package/docs/retro/0102-consolidate-test-record-factory.md

@@ -1,30 +0,0 @@
----
-issue: 102
-issue_title: "Consolidate test AgentRecord construction into a shared factory"
----
-
-# Retro: #102 — Consolidate test AgentRecord construction into a shared factory
-
-## Final Retrospective (2026-05-20T15:30:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a shared `createTestRecord()` factory in `test/helpers/make-record.ts`, migrating 7 test files from local factories and inline literals.
-The session completed in three slash-command phases (plan → TDD → ship) with zero rework, zero test failures, and zero deviations from the plan.
-Released as `pi-subagents-v6.0.1`.
-
-### Observations
-
-#### What went well
-
-- The Explore subagent surveyed all 8 test files' factory patterns in parallel, producing a structured comparison table that directly informed the plan's default-value decisions.
-- Before migrating `service-adapter.test.ts`, reading the `toSubagentRecord` source confirmed that `!== undefined` guards make absent-property vs. property-set-to-undefined semantically equivalent — avoiding a subtle test failure.
-- All 4 TDD steps passed on first run, confirming the plan's migration strategy (preserve old defaults via overrides) was sound.
-
-#### What caused friction (agent side)
-
-No friction points — the mechanical nature of the refactoring and the well-specified plan eliminated ambiguity.
-
-#### What caused friction (user side)
-
-No friction points — the three-phase slash-command workflow required no manual intervention.