@gotgenes/pi-subagents 18.0.1 → 18.0.2

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.

package/docs/retro/0108-extract-agent-type-registry.md

@@ -1,41 +0,0 @@
----
-issue: 108
-issue_title: "refactor(pi-subagents): extract AgentTypeRegistry class from module-scoped state"
----
-
-# Retro: #108 — extract AgentTypeRegistry class
-
-## Final Retrospective (2026-05-21T13:30:00Z)
-
-### Session summary
-
-Planned and implemented the `AgentTypeRegistry` class extraction from module-scoped state in `agent-types.ts`.
-The lift-and-shift approach across 7 TDD steps (9 commits including plan and docs) migrated 11 source files and 11 test files while keeping 574 tests green at every commit.
-The `reloadCustomAgents` callback was removed from `AgentToolDeps` and `AgentMenuDeps`, replaced by `deps.registry.reload()`.
-
-### Observations
-
-#### What went well
-
-- The `AgentConfigLookup` narrow interface (ISP) for `session-config.ts` kept tests simple — plain objects with 2 methods, no class instantiation needed.
-- Using `vi.spyOn` on a real `AgentTypeRegistry` instance in `agent-menu.test.ts` was cleaner than `vi.hoisted` + `vi.fn()` factories: correct types, automatic cleanup via `vi.restoreAllMocks()`.
-- Step 2 (inject through 4-file config-assembly chain) was the riskiest single step but landed cleanly because the `vi.mock("agent-types.js")` stubs were narrowed to only the free functions that `session-config.ts` still imports (`getMemoryToolNames`, `getReadOnlyMemoryToolNames`).
-
-#### What caused friction (agent side)
-
-1. `missing-context` — The plan's "Test files affected" table listed 8 files but missed 3 (`prompts.test.ts`, `tools/get-result-tool.test.ts`, `conversation-viewer.test.ts`) that directly import symbols being removed in step 7.
-   The grep during planning found `prompts.test.ts` as an importer of `registerAgents` but didn't include it in the table.
-   Impact: 3 extra test files needed updating in step 7; caught by the full-suite run, not by surprise in CI.
-
-2. `wrong-abstraction` — First `perl -0777` regex for bulk-updating 16 `ConversationViewer` constructor calls in `conversation-viewer.test.ts` failed because the character class `[^)]+` didn't match the multi-line arguments.
-   A simpler pattern targeting just the `vi.fn(),\n  );` suffix worked on the second try.
-   Impact: added friction but no rework — ~2 minutes.
-
-3. `missing-context` — Type check after step 7 revealed `promptMode: string` vs `"replace" | "append"` narrowing issue in `agent-runner-extension-tools.test.ts`.
-   The `agentConfigMock.current` object had `promptMode: "replace"` which TypeScript widened to `string` when spread into the mock `AgentConfigLookup` return.
-   Impact: one additional edit with a return-type annotation; caught by `pnpm run check` as recommended by the testing skill.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The issue description was clear, the architecture doc had the design already sketched, and no mid-session redirects were needed.

package/docs/retro/0109-extract-settings-manager.md

@@ -1,55 +0,0 @@
----
-issue: 109
-issue_title: "refactor(pi-subagents): extract SettingsManager class"
----
-
-# Retro: #109 — extract SettingsManager class
-
-## Final Retrospective (2026-05-21T17:30:00Z)
-
-### Session summary
-
-Planned and implemented the `SettingsManager` class extraction across 8 TDD cycles plus doc updates.
-The class owns `defaultMaxTurns`, `graceTurns`, and `maxConcurrent` with normalizing property accessors, a `load()` method for merged config, and `saveAndNotify()` for persistence + lifecycle events.
-Six settings-related callback fields in `AgentMenuDeps` collapsed to a single `settings` collaborator (13 → 8 fields), and `SettingsAppliers`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` were removed.
-A follow-up issue (#118) was filed for a LoD/Tell-Don't-Ask violation the user identified in the post-implementation review.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift TDD approach worked cleanly: the new class was built and tested in isolation (cycles 1–2), consumers migrated one at a time (cycles 3–5), wiring consolidated (cycle 6), and old code removed last (cycles 7–8).
-  Each commit left the repo in a valid state.
-- The user's design critique (LoD / Tell-Don't-Ask on `deps.settings.saveAndNotify()` orchestration) was sharp and led to a concrete follow-up issue (#118) with a clear fix.
-  The session handled it well — acknowledged, designed the fix, filed the issue, updated the architecture doc, and stopped without scope-creeping into implementation.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — The plan did not anticipate that changing `AgentMenuDeps` (cycle 3) would immediately break `index.ts` type-checking.
-   Each interface change in cycles 3, 4, and 5 required a same-commit bridge fix in `index.ts` to keep `pnpm run check` clean.
-   The plan's separation of "migrate consumers" (cycles 3–5) from "wire in index.ts" (cycle 6) was too coarse — interface changes propagate to the call site immediately.
-   Impact: three unplanned bridge edits in `index.ts`, each small but requiring context-switching mid-cycle.
-
-2. `missing-context` — The `sed` command in cycle 5 (`sed -i '' 's/maxConcurrent: 1,/getMaxConcurrent: () => 1,/g'`) missed two call sites where `maxConcurrent: 1` had no trailing comma (end of object literal).
-   A `grep` check after the `sed` would have caught this immediately.
-   Impact: two tests failed unexpectedly; required a follow-up read + manual edit before the cycle could complete.
-
-3. `missing-context` — The Edit tool failed on `runtime.ts` because the file uses `─` (U+2500, BOX DRAWINGS LIGHT HORIZONTAL) in section separators, not `—` (U+2014, EM DASH).
-   The Unicode characters looked identical in the terminal, and the Edit tool's exact-match requirement meant the mismatch was silent until the replacement failed.
-   Impact: three failed Edit attempts before falling back to a Python script for the replacement.
-   This is the same class of issue seen in previous sessions with Unicode characters in source files.
-
-4. `premature-convergence` — The plan designed `SettingsManager` as a data holder with persistence methods but didn't consider whether the menu should orchestrate across `settings` and `manager` or whether `SettingsManager` should own the full consequence chain.
-   The user caught this as a LoD/Tell-Don't-Ask violation in post-implementation review.
-   Impact: no rework (filed as follow-up #118), but the design could have been better from the start if the plan had applied the design-review checklist's LoD check to the proposed `showSettings` interaction pattern.
-
-#### What caused friction (user side)
-
-- The user's LoD critique was well-timed — after implementation was complete, avoiding mid-stream rework.
-  If the critique had surfaced during planning (e.g., by the agent applying the design-review checklist to the proposed consumer interaction pattern), the follow-up issue might have been part of the original scope.
-  This is an opportunity for the planning step to simulate the consumer's call sites before finalizing the design, not just the class interface.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — Added consumer call-site sketch heuristic to the "Design Overview" section: when a new collaborator is introduced, sketch 3–5 lines of consumer pseudocode to verify Tell-Don't-Ask and LoD.
-2. `.pi/skills/testing/SKILL.md` — Added TDD planning rule: when a step changes an interface with a single call site, the step must include updating that call site (type checker enforces co-location).

package/docs/retro/0110-agent-activity-tracker.md

@@ -1,44 +0,0 @@
----
-issue: 110
-issue_title: "refactor(pi-subagents): wrap AgentActivity in AgentActivityTracker class"
----
-
-# Retro: #110 — wrap AgentActivity in AgentActivityTracker class
-
-## Final Retrospective (2026-05-21T23:30:00Z)
-
-### Session summary
-
-Planned and implemented `AgentActivityTracker` class across 6 TDD cycles plus doc updates, released as `pi-subagents-v6.7.0`.
-The 7-field mutable `AgentActivity` interface was replaced with a class exposing explicit transition methods (`onToolStart`, `onToolEnd`, `onMessageStart`, `onMessageUpdate`, `onTurnEnd`, `onUsageUpdate`, `setSession`) and read-only accessors.
-All 7 source files and 3 test files were migrated incrementally without any big-bang commit.
-
-### Observations
-
-#### What went well
-
-- **TDD Red phase caught all three implementation bugs.**
-  1. `onToolEnd` initially incremented `toolUses` unconditionally (ported from original code), but the plan specified no-op defensive behavior.
-     The Red phase test `"onToolEnd with no matching tool is a no-op"` caught it instantly.
-  2. `Date.now()` key collision in `activeTools` Map — two `onToolStart("Read")` calls in the same millisecond produced identical keys, so the second overwrote the first.
-     The Red phase test `"multiple concurrent tools with same name tracked independently"` caught it.
-  3. `describeActivity` signature needed `ReadonlyMap<string, string>` after the accessor change — caught by `pnpm run check` in step 3.
-  All three were fixed immediately with no cascading rework.
-- **Incremental migration avoided type breakage.**
-  The plan kept `AgentActivity` alive in `agent-widget.ts` until step 3, so steps 1–2 compiled without touching downstream files.
-  Each step only broke the files it was about to migrate, keeping intermediate states valid.
-- **Monotonic counter is strictly better than `Date.now()` for tool keys.**
-  The extraction enabled replacing the `toolName + "_" + Date.now()` key strategy with `toolName + "_" + (++this._toolKeySeq)`, which never collides regardless of timing.
-  This is a concrete improvement the original inline code couldn't easily adopt.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan specified the `Date.now()` key strategy from the original code, but didn't account for same-millisecond collisions in test execution.
-  Impact: ~1 minute debugging in step 1; trivial fix to monotonic counter.
-- `premature-convergence` — Initial `onToolEnd` implementation copied the original's unconditional `toolUses++` before checking the plan's specified no-op behavior.
-  Impact: caught immediately by the Red phase test, single-line fix.
-
-#### What caused friction (user side)
-
-- No material friction observed.
-  The session ran end-to-end (plan → implement → ship → release) without user intervention.

package/docs/retro/0111-split-agent-record-lifecycle.md

@@ -1,61 +0,0 @@
----
-issue: 111
-issue_title: "refactor(pi-subagents): split AgentRecord lifecycle state into phase-specific objects"
----
-
-# Retro: #111 — split AgentRecord lifecycle state into phase-specific objects
-
-## Final Retrospective (2026-05-22T01:50:00Z)
-
-### Session summary
-
-Planned and implemented the `AgentRecord` lifecycle split across 12 TDD cycles plus doc updates, released as `pi-subagents-v6.8.0`.
-Three new phase-specific collaborators (`ExecutionState`, `WorktreeState`, `NotificationState`) replace 9 post-construction mutable fields.
-`pendingSteers` moved to a `Map` on `AgentManager`; stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods with read-only getters.
-`AgentRecordInit` trimmed from 19 optional fields to 4.
-
-### Observations
-
-#### What went well
-
-- **Lift-and-shift scaled from 7 files (#110) to 18 files (#111) without any intermediate test breakage.**
-  Every commit left all 41 test files passing.
-  The pattern — add new alongside old, migrate consumers with fallbacks (`record.execution?.session ?? record.session`), strip fallbacks in a final commit — is reliable for multi-step encapsulation refactors.
-- **Stats encapsulation was simpler than expected.**
-  Converting `toolUses`, `lifetimeUsage`, `compactionCount` to private fields with getters and mutation methods required zero changes to read-only consumers because the getter names match the old field names.
-  Only `record-observer.ts` (the sole writer) needed updating.
-- **The `createTestRecord` factory intersection type trick preserved backward compatibility.**
-  The factory accepts `toolUses?: number` via `Partial<AgentRecordInit> & { toolUses?: number; ... }` and internally calls `record.incrementToolUses()` in a loop.
-  This let 10+ test files continue passing `toolUses: 5` without rewriting each to call mutation methods directly.
-- **`Promise.withResolvers` timing analysis in the plan was unnecessary.**
-  The plan spent ~40 lines analyzing whether `promise` should live inside `ExecutionState` and concluded it should stay separate.
-  Implementation confirmed: `record.execution` is set in `onSessionCreated` (async callback), `record.promise` is set after `runner.run()` (synchronous return) — different moments, straightforward.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In the step 7 test for `record.execution`, the initial mock runner used `mockResolvedValue(...)` which doesn't call `onSessionCreated`, so `record.execution` stayed `undefined`.
-  Had to switch to `mockImplementation(async (..., opts) => { opts.onSessionCreated?.(session); ... })`.
-  The existing tests in the same file already use this pattern for record-observer tests, but I didn't check them first.
-  Impact: one test rewrite (~2 minutes), no rework to production code.
-- `scope-drift` — Step 4 absorbed step 5 (adding collaborator fields) without noting the merge in the commit or session log.
-  Step 5 became a no-op.
-  Impact: no rework, but the session narrative skipped a plan step without explanation.
-- `wrong-abstraction` — Step 12 was planned as a simple cleanup ("remove old fields and trim `AgentRecordInit`") but required coordinated changes across 18 files: removing 9 fields from `AgentRecordInit`, updating the `createTestRecord` factory, fixing 5 test files that passed removed fields, and stripping all fallback patterns.
-  This was 2-3 steps' worth of work compressed into one.
-  Impact: step 12 took significantly longer than other steps, though it landed cleanly.
-- `missing-context` — Did not proactively flag the `as ReturnType<typeof vi.fn>` cast smell in `service-adapter.test.ts` while migrating that file.
-  The user noticed it and asked about it.
-  Filed as #123.
-  Impact: added friction but no rework; follow-up issue created.
-  User-caught.
-
-#### What caused friction (user side)
-
-- No material friction observed.
-  The user's `ask_user` decisions during planning (NotificationState collaborator, Map on AgentManager) gave clear direction.
-  Quick "follow-up" response on the cast smell kept scope tight.
-
-### Changes made
-
-1. `packages/pi-subagents/docs/retro/0111-split-agent-record-lifecycle.md` — this retro file.
-2. `.pi/skills/testing/SKILL.md` — added field-removal rule symmetric to the existing field-addition rule (esbuild silent pass-through on unknown init properties).

package/docs/retro/0112-replace-agent-manager-callbacks.md

@@ -1,35 +0,0 @@
----
-issue: 112
-issue_title: "refactor(pi-subagents): replace AgentManager callbacks with observer interface"
----
-
-# Retro: #112 — replace AgentManager callbacks with observer interface
-
-## Final Retrospective (2026-05-21T21:00:00-04:00)
-
-### Session summary
-
-Replaced three fire-and-forget callback fields (`onStart`, `onComplete`, `onCompact`) on `AgentManagerOptions` with a single `AgentManagerObserver` interface.
-The refactoring touched `agent-manager.ts`, `index.ts`, and `agent-manager.test.ts` with zero test-count delta (652/652).
-Released as `pi-subagents-v6.8.2`.
-
-### Observations
-
-#### What went well
-
-- The issue description was thorough and unambiguous — no `ask_user` needed during planning, and the design mapped directly to implementation.
-- Self-identified the testing skill's single-call-site rule during execution: the plan split Steps 2 and 3 into separate commits, but `AgentManagerOptions` has one call site in `index.ts`, so both had to land together.
-  Merged them without rework.
-- Pre-existing lint issue (unused `ExecutionState` import in `agent-manager.ts`) caught and fixed proactively during the lint step.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` (self-identified) — The plan wrote TDD Steps 2 and 3 as separate commits, but the testing skill says "when a TDD step changes an interface that has a single call site, the step must include updating that call site."
-  The planning phase loaded the testing skill but didn't apply this specific rule when structuring the TDD order.
-  Impact: added friction but no rework — caught during execution when `pnpm run check` surfaced the expected type error in `index.ts` after Step 2.
-- `other` (tool interaction) — One `Edit` tool `oldText` match failure in `agent-manager.ts` because the selected block included a blank line that didn't exist between `subscribeRecordObserver` and `options.onSessionCreated`.
-  Impact: one extra read + edit cycle (~30 seconds).
-
-#### What caused friction (user side)
-
-- Nothing — the session ran without user corrections or redirections.

package/docs/retro/0113-disambiguate-spawn-options.md

@@ -1,29 +0,0 @@
----
-issue: 113
-issue_title: "refactor(pi-subagents): disambiguate SpawnOptions (public vs internal)"
----
-
-# Retro: #113 — disambiguate SpawnOptions (public vs internal)
-
-## Final Retrospective (2026-05-21T21:10:00-04:00)
-
-### Session summary
-
-Renamed the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig` to disambiguate it from the public `SpawnOptions` in `service.ts`.
-Pure mechanical rename across 4 files with zero test-count delta (652/652).
-Released as `pi-subagents-v6.8.3`.
-
-### Observations
-
-#### What went well
-
-- Completely frictionless execution — single-step plan executed exactly as written with no corrections, rework, or failed edits.
-- The session benefited from context already loaded during the preceding #112 cycle (same package, same skills, same source files), which made planning and execution faster.
-
-#### What caused friction (agent side)
-
-- Nothing — the rename was purely mechanical and the plan matched reality exactly.
-
-#### What caused friction (user side)
-
-- Nothing — no user intervention needed.

package/docs/retro/0114-narrow-agent-tool-menu-deps.md

@@ -1,38 +0,0 @@
----
-issue: 114
-issue_title: "refactor(pi-subagents): narrow AgentToolDeps and AgentMenuDeps"
----
-
-# Retro: #114 — narrow AgentToolDeps and AgentMenuDeps
-
-## Final Retrospective (2026-05-21T21:43:48-04:00)
-
-### Session summary
-
-Narrowed `AgentToolDeps` from 9 to 6 fields and `AgentMenuDeps` from 8 to 7 fields.
-Moved `subagents:created` event emission from the Agent tool to a new `AgentManagerObserver.onAgentCreated` method.
-Extracted `buildTypeListText` to `tools/helpers.ts`, derived description text inside `createAgentTool`, removed dead `emitEvent` from `AgentMenuDeps`, and narrowed `agentActivity` to typed `AgentActivityAccess`/`AgentActivityReader` interfaces.
-Test count increased from 638 to 660.
-Released as `pi-subagents-v6.9.0`.
-
-### Observations
-
-#### What went well
-
-- The `ask_user` gate during planning was well-targeted.
-  The first question (where to move `emitEvent`) had a clear answer.
-  The second (description-text derivation) genuinely needed user input, and the user requested more context via the "I could use more context" response — the follow-up `preview`-type question with fenced code blocks handled this cleanly.
-- The 6-step TDD plan mapped to implementation with only one deviation (see below), caught exactly where the workflow is designed to catch it (the `pnpm run check` step).
-- All 6 prerequisites (#108, #109, #110, #112, #113, #118) were verified as closed before planning.
-  The observer issue (#112) was correctly identified from a `gh issue list` grep despite not being explicitly numbered in the issue body (the issue said "the observer issue").
-
-#### What caused friction (agent side)
-
-- `missing-context` (self-identified) — Step 6 narrowed `agentActivity` from `Map<string, AgentActivityTracker>` to `AgentActivityAccess` (which exposes only `get`/`set`/`delete`), but the test in `agent-tool.test.ts` used `.has()` on the map.
-  The `pnpm run check` typecheck caught `Property 'has' does not exist on type 'AgentActivityAccess'`.
-  Fixed by replacing `.has(id)` with `.get(id) !== undefined` in the same commit.
-  Impact: one extra read + edit cycle (~30 seconds), no rework.
-
-#### What caused friction (user side)
-
-- Nothing — no user corrections or redirections needed during the session.

package/docs/retro/0115-decompose-agent-tool.md

@@ -1,51 +0,0 @@
----
-issue: 115
-issue_title: "refactor(pi-subagents): decompose agent-tool.ts into foreground/background modules"
----
-
-# Retro: #115 — decompose agent-tool.ts into foreground/background modules
-
-## Final Retrospective (2026-05-21T22:30:00-04:00)
-
-### Session summary
-
-Decomposed the 579-line `tools/agent-tool.ts` into focused modules: `foreground-runner.ts` (spinner, streaming, cleanup) and `background-spawner.ts` (activity setup, notification wiring), with `agent-tool.ts` remaining as the orchestrator (411 lines).
-Before extracting, fixed two upstream API gaps: widened `onSessionCreated` callback to `(session, record)` to eliminate a `listAgents()` reverse-search, and added `toolCallId` to `AgentSpawnConfig` so the manager wires `NotificationState` at spawn time.
-Test count increased from 641 to 690.
-Released as `pi-subagents-v6.9.1`.
-
-### Observations
-
-#### What went well
-
-- The revised plan (after user feedback) was structurally clean — fixing API gaps first made the extraction trivial; each extracted module received only what it needed without workarounds.
-- TDD execution was smooth: 6 steps, all green after each commit, only minor deviations (type annotation issue, `index.ts` call-site fix).
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` (user-caught) — The initial plan was a mechanical code-move that defined 4 new interfaces (`ForegroundRunDeps`, `BackgroundSpawnDeps`, `ForegroundRunParams`, `BackgroundSpawnParams`) to paper over two upstream API gaps: a `listAgents()` reverse-search in the foreground `onSessionCreated` callback, and a post-spawn `record.notification` mutation in the background path.
-  The user asked *"What dependencies are still missing for these split tools, that they want, rather than some low level state or collaborators that they have?"*
-  — redirecting me to fix the API surface before extracting.
-  Impact: entire plan rewritten (~15 minutes), but the revised plan was significantly cleaner and the implementation went smoothly.
-
-- `missing-context` (self-identified) — During step 5 (foreground extraction), two tests in `foreground-runner.test.ts` failed because mock sessions were `{}` objects lacking a `subscribe` method required by `subscribeUIObserver`.
-  The function's dependency on `SubscribableSession` (requiring `.subscribe()`) wasn't accounted for in the test mock.
-  Impact: one test fix cycle (~2 minutes), no rework.
-
-- `missing-context` (self-identified) — Annotating `runForeground` with an explicit `Promise<AgentToolResult<any>>` return type widened the content array type from `{ type: "text", text: string }[]` to `(TextContent | ImageContent)[]`, breaking existing `content[0].text` patterns in tests.
-  Fixed by removing the explicit annotation and letting TypeScript infer the narrow type.
-  Impact: three edit cycles to diagnose and fix (~5 minutes).
-
-- `missing-context` (self-identified) — Step 1 removed `listAgents` from `AgentToolManager` but didn't update the construction site in `index.ts`.
-  `pnpm run check` caught it in step 4.
-  Impact: one-line fix in the same commit, no rework.
-
-#### What caused friction (user side)
-
-- The initial plan's size and mechanical nature required a user redirect.
-  The `/plan-issue` prompt's Design Overview section asks to sketch consumer call sites for *new collaborators*, but the same Tell-Don't-Ask check should apply to *extracted* modules' interactions with their upstream dependencies.
-  A prompt tweak could help the agent catch this pattern earlier.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added extraction-specific Tell-Don't-Ask verification step to the Design Overview section: sketch the extracted module's upstream interactions before planning the extraction, fix API gaps first.

package/docs/retro/0116-type-housekeeping.md

@@ -1,42 +0,0 @@
----
-issue: 116
-issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
----
-
-# Retro: #116 — type housekeeping and small structural cleanups
-
-## Final Retrospective (2026-05-21T23:00:00Z)
-
-### Session summary
-
-Planned and executed 6 refactoring steps for issue #116: relocated 3 misplaced types from `types.ts` to their natural home modules, converted `createNotificationSystem` closure to a `NotificationManager` class, switched `ConversationViewer` to an options-bag constructor, and defined `AgentIdentity`/`AgentPromptConfig` narrow subset interfaces.
-All 690 tests stayed green throughout; no behavioral changes.
-Released as `pi-subagents-v6.9.2`.
-
-### Observations
-
-#### What went well
-
-- The Python script approach for bulk-converting 16 `ConversationViewer` positional constructor calls to options-bag syntax was efficient and correct on the first attempt — all 17 tests passed immediately after the conversion.
-- Proactive `grep -rn 'new ConversationViewer'` before step 5 caught the `agent-menu.ts` call site that the plan's Module-Level Changes section had omitted, avoiding a broken commit.
-- The architecture doc update was clean — 5 targeted edits to mark E2 done, update smells table, and fix metrics.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In all three type-relocation steps (1–3), I updated source-file imports but did not pre-flight grep for test-file imports of the relocated symbol.
-  Each time, `pnpm run check` caught the stale test import, requiring an extra edit-check round trip.
-  This happened with `test/renderer.test.ts` (step 1), `test/agent-runner.test.ts` + `test/agent-runner-extension-tools.test.ts` (step 2), and `test/prompts.test.ts` (step 3).
-  Impact: 3 unnecessary edit-check cycles; no broken commits since the type checker caught every case before `git commit`.
-
-- `missing-context` — In step 4, the first `Edit` call on `src/index.ts` failed because the autoformatter had merged the `NotificationDetails` type import (added in step 1) into the existing notification import line, changing the text I expected.
-  Had to re-read the file to find the current import text.
-  Impact: one wasted edit call plus a file read; added ~10 seconds of friction.
-
-#### What caused friction (user side)
-
-- No friction observed — the user's prompts were clear and the `/tdd-plan` and `/ship-issue` templates provided all needed structure.
-
-### Takeaway
-
-When relocating a type or symbol, always run `grep -rn 'SymbolName' src/ test/` before editing to identify *all* importers upfront — both source and test files.
-This avoids the repeated pattern of "edit source → type-check fails on test → fix test → type-check again."

package/docs/retro/0118-settings-manager-apply-methods.md

@@ -1,40 +0,0 @@
----
-issue: 118
-issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
----
-
-# Retro: #118 — SettingsManager apply methods
-
-## Final Retrospective (2026-05-21T21:00:00Z)
-
-### Session summary
-
-Planned and implemented 3 `apply*` methods on `SettingsManager` (`applyMaxConcurrent`, `applyDefaultMaxTurns`, `applyGraceTurns`) across 5 TDD cycles plus doc updates, released as `pi-subagents-v6.6.0`.
-Each method owns the full consequence chain (normalize → set → callback → persist → emit → return toast), eliminating the LoD/Tell-Don't-Ask violation in `showSettings` that was identified during the #109 retro.
-`notifyConcurrencyChanged` was removed from `AgentMenuManager`; the menu no longer coordinates between settings and the agent manager.
-
-### Observations
-
-#### What went well
-
-- **Retro-driven improvement validated.**
-  Issue #118 was filed during the #109 retro as a LoD/Tell-Don't-Ask follow-up, and the plan-issue prompt's consumer call-site sketch heuristic (added in #109's retro) was already in the plan template.
-  The plan for #118 included concrete before/after call-site sketches that made the design unambiguous — no `ask-user` decision needed.
-- **Interface-then-wiring TDD order worked cleanly.**
-  The #109 retro noted that interface changes propagate to `index.ts` immediately, forcing unplanned bridge edits.
-  This time the plan accounted for it: Cycle 4 committed only menu files (leaving a known `index.ts` type error), and Cycle 5 fixed the wiring in a separate commit.
-  The intermediate type error was contained and expected.
-- **`defaultMaxTurns` branch consolidation.**
-  During Cycle 4, the separate `n === 0` and `n >= 1` branches in `showSettings` were consolidated to a single `n >= 0` check, since `applyDefaultMaxTurns` handles the 0→unlimited mapping internally.
-  This was a minor but correct simplification that emerged naturally from the Tell-Don't-Ask refactor.
-
-#### What caused friction (agent side)
-
-- No material friction.
-  All 5 TDD cycles completed without rework, failed edits, or unexpected test failures.
-  The plan was tight and the issue's "Proposed change" section was unambiguous.
-
-#### What caused friction (user side)
-
-- No material friction observed.
-  The session ran end-to-end (plan → implement → ship → release) without user intervention.