@gotgenes/pi-subagents 7.3.0 → 7.3.2

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.3.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.1...pi-subagents-v7.3.2) (2026-05-25)
+
+
+### Documentation
+
+* mark Phase 13 Step 1 complete ([8d62590](https://github.com/gotgenes/pi-packages/commit/8d62590aeded8aba25df96ea2fbba6581572eaf7))
+* **pi-subagents:** link Phase 13 issues [#214](https://github.com/gotgenes/pi-packages/issues/214)–[#219](https://github.com/gotgenes/pi-packages/issues/219) in architecture roadmap ([636a1e5](https://github.com/gotgenes/pi-packages/commit/636a1e500319b9ce1007c0a571dd13199cdd2606))
+* **pi-subagents:** propose Phase 13 improvement roadmap ([caf2a53](https://github.com/gotgenes/pi-packages/commit/caf2a5376c69744db1743a9362096e764d9524b1))
+* plan convert remaining closure factories to classes ([#214](https://github.com/gotgenes/pi-packages/issues/214)) ([2225920](https://github.com/gotgenes/pi-packages/commit/222592007e2ce29d5e6d5678a303f6cb781dae39))
+* **retro:** add planning stage notes for issue [#214](https://github.com/gotgenes/pi-packages/issues/214) ([3072e61](https://github.com/gotgenes/pi-packages/commit/3072e618f08080065ef9f3c7520ff44e8dbc84b4))
+* **retro:** add retro notes for issue [#208](https://github.com/gotgenes/pi-packages/issues/208) ([1436396](https://github.com/gotgenes/pi-packages/commit/1436396d71e79cbbf519877e9dc899000ebd0001))
+* **retro:** add TDD stage notes for issue [#214](https://github.com/gotgenes/pi-packages/issues/214) ([201e1eb](https://github.com/gotgenes/pi-packages/commit/201e1ebbaba66e0d83cc006ef77b711c22fb1bb8))
+
+## [7.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.0...pi-subagents-v7.3.1) (2026-05-25)
+
+
+### Bug Fixes
+
+* add parameter type annotations to shared test fixture factories ([2953adc](https://github.com/gotgenes/pi-packages/commit/2953adc5761dd4aa2d3c592ea5f8856161e01e3a))
+
+
+### Documentation
+
+* plan extract shared test fixtures ([#208](https://github.com/gotgenes/pi-packages/issues/208)) ([22fafed](https://github.com/gotgenes/pi-packages/commit/22fafed860134f00f1b5d6cb7c87fa42be7dcf09))
+* **retro:** add planning stage notes for issue [#208](https://github.com/gotgenes/pi-packages/issues/208) ([aaa9d5d](https://github.com/gotgenes/pi-packages/commit/aaa9d5d0a4654b2ebb25a7ad4d11a3a54db7c206))
+* **retro:** add retro notes for issue [#207](https://github.com/gotgenes/pi-packages/issues/207) ([3b97a5c](https://github.com/gotgenes/pi-packages/commit/3b97a5c5b3fbb98a78ba280fbdbbdf55f61d82fc))
+* **retro:** add TDD stage notes for issue [#208](https://github.com/gotgenes/pi-packages/issues/208) ([65d0606](https://github.com/gotgenes/pi-packages/commit/65d0606167e531518bd8de4d33f91c6080e21723))
+* update Phase 12 Step 4 to reference test/helpers/ ([8e9e406](https://github.com/gotgenes/pi-packages/commit/8e9e406bfe12487f67363b223d037664f842acce))
+
 ## [7.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.8...pi-subagents-v7.3.0) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -431,36 +431,38 @@ These are fire-and-forget broadcast events — no request IDs, no reply channels
 
 ### Health metrics
 
-| Metric                    | Value                        |
-| ------------------------- | ---------------------------- |
-| Health score              | 75/100 (B)                   |
-| Total LOC                 | 8,218 (53 files)             |
-| Dead code                 | 0 files, 0 exports           |
-| Maintainability index     | 90.7 (good)                  |
-| Avg cyclomatic complexity | 1.5                          |
-| P90 cyclomatic complexity | 2                            |
-| Production duplication    | 18 lines (1 clone group)     |
-| Test duplication          | 71 clone groups, 1,424 lines |
+| Metric                     | Value                                |
+| -------------------------- | ------------------------------------ |
+| Health score               | 78/100 (B)                           |
+| Total LOC                  | 8,180 (53 files)                     |
+| Test LOC                   | 12,026                               |
+| Dead code                  | 0 files, 0 exports                   |
+| Maintainability index      | 90.7 (good)                          |
+| Avg cyclomatic complexity  | 1.5                                  |
+| P90 cyclomatic complexity  | 2                                    |
+| Production duplication     | 20 lines (1 clone group)             |
+| Test duplication           | 59 clone groups, 1,046 lines         |
+| Fallow refactoring targets | 1 (buildParentContext, cognitive 30) |
 
 ### Dependency bag inventory
 
 These interfaces carry hidden dependencies that obscure true coupling.
 Bags with 10+ fields are the highest priority for decomposition.
 
-| Interface                   | Fields                                                 | Consumers                                         | Severity |
-| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | -------- |
-| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done   |
-| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done   |
-| `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done   |
-| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done   |
-| `NotificationDetails`       | 10                                                     | notification                                      | Medium   |
-| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Medium   |
-| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done   |
-| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done   |
-| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | Low      |
-| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low      |
-| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low      |
+| Interface                   | Fields                                                 | Consumers                                         | Severity  |
+| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | --------- |
+| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done    |
+| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done    |
+| `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done    |
+| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done    |
+| `NotificationDetails`       | 10                                                     | notification                                      | Low (DTO) |
+| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Low (SDK) |
+| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done    |
+| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Low (SDK) |
+| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done    |
+| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | ✓ done    |
+| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low       |
+| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low       |
 
 ### Complexity hotspots
 
@@ -472,18 +474,22 @@ No functions remain above the critical threshold — all hotspots resolved in Ph
 
 Files with highest commit frequency × complexity (accelerating trend):
 
-| Score | File                  | Commits |
-| ----- | --------------------- | ------- |
-| 85.7  | `index.ts`            | 65      |
-| 35.9  | `agent-manager.ts`    | 31      |
-| 25.9  | `ui/agent-menu.ts`    | 26      |
-| 23.3  | `tools/agent-tool.ts` | 30      |
+| Score | File                        | Commits | Trend          |
+| ----- | --------------------------- | ------- | -------------- |
+| 43.3  | `index.ts`                  | 81      | ▲ accelerating |
+| 26.0  | `ui/agent-menu.ts`          | 33      | ▲ accelerating |
+| 13.6  | `tools/agent-tool.ts`       | 41      | ▲ accelerating |
+| 13.3  | `ui/conversation-viewer.ts` | 16      | ▲ accelerating |
+| 12.6  | `ui/agent-config-editor.ts` | 10      | ▼ cooling      |
+| 11.7  | `ui/agent-widget.ts`        | 14      | ▲ accelerating |
+
+Note: accelerating trends reflect recent refactoring phases, not feature churn.
+Once structural work stabilizes, these are expected to cool.
 
 ### Production duplication
 
-The 18-line clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
-`ToolCallContent`, `getToolCallName`, and `extractAssistantContent` now live in `session/content-items.ts`.
-No known production duplication remains.
+The prior clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
+One 20-line clone group remains between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` — both implement the same overwrite-guard + write + reload + notify pattern.
 
 ### Proposed bag decompositions
 
@@ -600,51 +606,125 @@ Phase 11 converted all closure factories to classes, eliminating adapter closure
 Four layers: SessionContext typing → runtime query methods → interface alignment → class conversions → index.ts simplification.
 See [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md) for details.
 
-## Improvement roadmap (Phase 12)
+## Phase 12 (complete)
+
+Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures.
+All four steps are closed: [#205], [#206], [#207], [#208].
+
+## Improvement roadmap (Phase 13)
+
+Phase 13 addresses the remaining fallow refactoring target, `agent-manager.ts` oversized method, production duplication, SDK boundary coupling, and the heaviest test clone families.
+Health score target: 80+ (A).
+
+### Findings summary
+
+| Finding                                                          | Category       | Impact | Risk | Priority |
+| ---------------------------------------------------------------- | -------------- | ------ | ---- | -------- |
+| 3 remaining closure factories (Phase 11 survivors)               | C: Coupling    | 4      | 2    | 16       |
+| `buildParentContext` cognitive 30 (only fallow target)           | B: Oversized   | 3      | 1    | 15       |
+| `startAgent` in agent-manager.ts (~130 LOC method)               | B: Oversized   | 4      | 3    | 12       |
+| Test duplication: 59 clone groups, 1,046 lines                   | D: Testability | 3      | 2    | 12       |
+| Overwrite guard duplicated across UI modules (20 lines)          | A: Redundant   | 2      | 1    | 10       |
+| `settings.ts` calls SDK function `getAgentDir()` at module level | C: Coupling    | 2      | 1    | 10       |
+
+### Step 1: Convert remaining closure factories to classes — [#214] ✓
+
+Three closure factories converted to classes in [#214].
+
+| Factory → Class                                        | File                          | Captures                                 |
+| ------------------------------------------------------ | ----------------------------- | ---------------------------------------- |
+| `createAgentConfigEditor()` → `AgentConfigEditor`      | `ui/agent-config-editor.ts`   | `fileOps`, `registry`, 2 dirs            |
+| `createAgentCreationWizard()` → `AgentCreationWizard`  | `ui/agent-creation-wizard.ts` | `fileOps`, `manager`, `registry`, 2 dirs |
+| `createSubagentsService()` → `SubagentsServiceAdapter` | `service/service-adapter.ts`  | `manager`, `resolveModel`, `runtime`     |
+
+- Smell: C (coupling — deps hidden in closure scope instead of explicit on class)
+- Outcome: 0 remaining closure factories (excluding pure-function factories), deps visible as constructor parameters
 
-Phase 12 addresses the remaining fallow refactoring targets and test duplication.
-These are independent of Phase 11 and can proceed in parallel if desired.
+### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215]
 
-### Step 1: Decompose `renderWidgetLines` (cognitive 44) — [#205]
+`buildParentContext` in `session/context.ts` is the only remaining fallow refactoring target.
+The function loops over branch entries with 3 type-check branches, each with sub-branches for role or summary.
+Extract per-entry-type formatters: `formatMessageEntry(entry)` and `formatCompactionEntry(entry)`.
 
-`renderWidgetLines` in `ui/widget-renderer.ts` handles agent-status formatting, tree connectors, overflow, and empty states.
-Extract per-status renderers and a tree-connector utility.
+- Target: `src/session/context.ts`
+- Smell: B (oversized function)
+- Outcome: cognitive complexity < 10, function < 15 LOC
 
-- Target: `src/ui/widget-renderer.ts`
-- Outcome: cognitive complexity < 10
+### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216]
 
-### Step 2: Decompose `showAgentDetail` (cognitive 33) — [#206]
+`startAgent` is a ~130-line private method that chains worktree setup → state transitions → observer notification → abort-signal wiring → runner invocation → `.then()` completion handler (~35 lines) → `.catch()` error handler (~15 lines).
+Both the `.then()` and `.catch()` blocks share common finalization logic (background counter decrement, observer notification, queue drain, worktree cleanup, detach signal).
 
-`showAgentDetail` in `ui/agent-config-editor.ts` handles display, edit, eject, and delete flows.
-Extract sub-functions per menu action.
+Extract:
 
-- Target: `src/ui/agent-config-editor.ts`
-- Outcome: cognitive complexity < 10
+1. `handleRunCompletion(record, options, result)` — worktree cleanup, state transition, execution update, observer notification.
+2. `handleRunError(record, options, err)` — error marking, worktree cleanup.
+3. `finalizeBackgroundRun(record)` — shared `runningBackground--`, observer, `drainQueue()`.
 
-### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31) — [#207]
+- Target: `src/lifecycle/agent-manager.ts`
+- Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
+- Outcome: no method > 40 LOC, `agent-manager.ts` < 480 LOC
 
-`update` mixes timer lifecycle, agent list assembly, render delegation, and visibility state.
-Extract `assembleWidgetState` (pure) and timer management.
+### Step 4: Extract overwrite guard from UI — [#217]
 
-- Target: `src/ui/agent-widget.ts`
-- Outcome: cognitive complexity < 10
+The 20-line pattern duplicated between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` checks file existence, prompts for confirmation, writes the file, reloads the registry, and notifies the user.
+Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, label)` function.
 
-### Step 4: Extract shared test fixtures — [#208]
+- Target: new `src/ui/agent-file-writer.ts`, consumers `src/ui/agent-config-editor.ts` and `src/ui/agent-creation-wizard.ts`
+- Smell: A (production duplication)
+- Outcome: 0 production clone groups
 
-The 3 heaviest clone families:
+### Step 5: Push SDK boundary in `settings.ts` — [#218]
 
-- `agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` (60-line shared setup)
-- `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
-- `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
+`globalPath()` calls `getAgentDir()` (a Pi SDK function) at invocation time.
+This hides a platform dependency inside a module that is otherwise pure configuration logic.
+Inject `agentDir: string` as a constructor parameter to `SettingsManager` and pass the global settings path from the boundary in `index.ts`.
+
+- Target: `src/settings.ts`, `src/index.ts`
+- Smell: C (platform type threading)
+- Outcome: `settings.ts` has 0 Pi SDK imports, `loadSettings`/`saveSettings` become fully testable without SDK stubs
+
+### Step 6: Reduce test duplication — top 3 clone families — [#219]
+
+The three heaviest remaining clone families after Phase 12:
+
+1. `agent-manager.test.ts` — 16 clone groups, 160 duplicated lines.
+   Extract shared setup/assertion helpers into `test/helpers/manager-stubs.ts`.
+2. `conversation-viewer.test.ts` — 8 clone groups, 91 duplicated lines.
+   Extract entry-builder helpers into existing `test/helpers/` or inline factory.
+3. `agent-config-editor.test.ts` — 5 clone groups, 42 duplicated lines.
+   Extract shared setup helpers.
+
+- Target: `test/lifecycle/agent-manager.test.ts`, `test/conversation-viewer.test.ts`, `test/ui/agent-config-editor.test.ts`
+- Smell: D (test duplication)
+- Outcome: test duplication reduced by ~200 lines (from 1,046 to < 850)
+
+### Step dependency diagram
+
+```mermaid
+flowchart LR
+    S1["Step 1\nclosure to class"]
+    S2["Step 2\nbuildParentContext"]
+    S3["Step 3\nstartAgent decomp"]
+    S4["Step 4\noverwrite guard"]
+    S5["Step 5\nsettings SDK"]
+    S6["Step 6\ntest duplication"]
+
+    S1 --> S4
+    S1 --> S6
+    S3 --> S6
+    S2 ~~~ S5
+```
 
-Extract shared factories into `test/fixtures/` modules.
+### Tracks
 
-- Target: new `test/fixtures/` modules
-- Outcome: test duplication reduced by ~400 lines
+1. **Track A — Structural** (Steps 1, 3): closure-to-class conversions and method decomposition.
+2. **Track B — Complexity and coupling** (Steps 2, 5): independent, can proceed in parallel with Track A.
+3. **Track C — Duplication** (Steps 4, 6): Step 4 depends on Step 1 (overwrite guard lives in files being converted); Step 6 depends on Steps 1 and 3 (production code they test changes first).
 
 ## Refactoring history
 
-Phases 1–5 and 7–11 are complete.
+Phases 1–5 and 7–12 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
@@ -661,6 +741,7 @@ Detailed records are preserved in per-phase history files:
 | 9     | Observation consolidation, ctx elimination          | Complete | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
 | 10    | Domain organization, bag decomposition, complexity  | Complete | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
 | 11    | Closure factories to classes                        | Complete | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
+| 12    | Complexity reduction and test fixture extraction    | Complete | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
 
 ### Structural refactoring issues
 
@@ -677,6 +758,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 10           | #164, #165, #166, #167, #168, #169, #170, #171, #172       | Domain directories, ResolvedSpawnConfig, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult, content-items |
 | Phase 11           | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                         |
 | Phase 12           | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                  |
+| Phase 13           | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                 |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -704,3 +786,9 @@ The upstream test suite is run periodically as a regression canary for the agent
 [#206]: https://github.com/gotgenes/pi-packages/issues/206
 [#207]: https://github.com/gotgenes/pi-packages/issues/207
 [#208]: https://github.com/gotgenes/pi-packages/issues/208
+[#214]: https://github.com/gotgenes/pi-packages/issues/214
+[#215]: https://github.com/gotgenes/pi-packages/issues/215
+[#216]: https://github.com/gotgenes/pi-packages/issues/216
+[#217]: https://github.com/gotgenes/pi-packages/issues/217
+[#218]: https://github.com/gotgenes/pi-packages/issues/218
+[#219]: https://github.com/gotgenes/pi-packages/issues/219

package/docs/architecture/history/phase-12-complexity-test-fixtures.md

@@ -0,0 +1,55 @@
+# Phase 12: Complexity reduction and test fixture extraction
+
+## Summary
+
+Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures into `test/helpers/`.
+
+## Steps
+
+### Step 1: Decompose `renderWidgetLines` (cognitive 44) — [#205]
+
+`renderWidgetLines` in `ui/widget-renderer.ts` handled agent-status formatting, tree connectors, overflow, and empty states.
+Extracted per-status renderers and a tree-connector utility.
+
+- Target: `src/ui/widget-renderer.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 2: Decompose `showAgentDetail` (cognitive 33) — [#206]
+
+`showAgentDetail` in `ui/agent-config-editor.ts` handled display, edit, eject, and delete flows.
+Extracted sub-functions per menu action.
+
+- Target: `src/ui/agent-config-editor.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31) — [#207]
+
+`update` mixed timer lifecycle, agent list assembly, render delegation, and visibility state.
+Extracted `assembleWidgetState` (pure) and timer management.
+
+- Target: `src/ui/agent-widget.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 4: Extract shared test fixtures — [#208]
+
+The 3 heaviest clone families:
+
+- `agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` (60-line shared setup)
+- `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
+- `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
+
+Extracted shared factories into `test/helpers/runner-io.ts` and `test/helpers/ui-stubs.ts`.
+Test duplication reduced from 71 clone groups (1,424 lines) to 59 clone groups (1,046 lines).
+
+## Metrics change
+
+| Metric                     | Before                 | After                  |
+| -------------------------- | ---------------------- | ---------------------- |
+| Health score               | 75/100 (B)             | 78/100 (B)             |
+| Fallow refactoring targets | 4                      | 1                      |
+| Test duplication           | 71 groups, 1,424 lines | 59 groups, 1,046 lines |
+
+[#205]: https://github.com/gotgenes/pi-packages/issues/205
+[#206]: https://github.com/gotgenes/pi-packages/issues/206
+[#207]: https://github.com/gotgenes/pi-packages/issues/207
+[#208]: https://github.com/gotgenes/pi-packages/issues/208