@gotgenes/pi-subagents 15.0.1 → 15.0.2

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [15.0.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v15.0.1...pi-subagents-v15.0.2) (2026-06-12)
+
+
+### Miscellaneous Chores
+
+* **deps:** bump Pi SDK to 0.79.1 ([#370](https://github.com/gotgenes/pi-packages/issues/370)) ([704f3b3](https://github.com/gotgenes/pi-packages/commit/704f3b3457ceb12b9df9efffe7a56812a5667d5d))
+* **deps:** bump rollup to 4.61.1 ([#370](https://github.com/gotgenes/pi-packages/issues/370)) ([250b729](https://github.com/gotgenes/pi-packages/commit/250b7296093b091297c57463693eaa2db59d5fe3))
+
 ## [15.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v15.0.0...pi-subagents-v15.0.1) (2026-06-10)
 
 

package/docs/architecture/architecture.md

@@ -10,8 +10,9 @@ This document describes the architecture of the pi-subagents fork: a focused, co
 3. **Typed API boundary** — this package exports a `SubagentsService` interface and `Symbol.for()` accessors (`publishSubagentsService` / `getSubagentsService`).
    Consumers declare this package as an optional peer dependency and use dynamic import for compile-time types.
    The runtime bridge is `Symbol.for("@gotgenes/pi-subagents:service")` on `globalThis` — no separate API package.
-4. **No scheduling** — in-process scheduling is removed from the core.
-   Scheduling is a separate concern that any extension can implement by calling `spawn()` on the published API.
+4. **No time-based scheduling** — cron-style timed dispatch (upstream's `schedule.ts` subsystem) is removed from the core (#52).
+   Timed dispatch is a separate concern that any extension can implement by calling `spawn()` on the published API.
+   The max-concurrent admission gate is not scheduling in this sense — concurrency management stays in core.
 5. **UI extraction is deferred** — the widget, conversation viewer, and `/agents` command menu stay in the core for now.
    They are the first candidate for extraction once the API boundary is proven stable.
 6. **Snapshot, don't capture** — mutable parent state (ctx, session, model) is read once at spawn time and frozen into a `ParentSnapshot` data object.
@@ -526,7 +527,7 @@ In the target state, pi-subagents publishes events and a provider seam; other pa
 
 Composition test: install neither extension, only permissions, only workspaces, or both — the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
 
-This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert dependencies — extensions on a minimal core), and Phase 17 (extract UI).
+This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert dependencies — extensions on a minimal core), and Phase 18 (extract UI).
 
 ## Current structural analysis
 
@@ -765,16 +766,164 @@ All five steps are closed: [#261], [#262], [#263], [#264], [#265].
 The earlier "agent collaborator architecture" framing (#256 superseded, #257 parked, #258 and #259 closed not-planned) was abandoned; its structural win was reached cleanly via the workspace seam.
 See [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md) for details.
 
-## Improvement roadmap (Phase 17 — extract UI)
+## Improvement roadmap (Phase 17 — core consolidation)
 
-Phase 17 is the long-deferred UI extraction (originally Phase 6).
-The widget, conversation viewer, and `/agents` command menu move to a separate `pi-subagents-ui` extension that consumes the `SubagentsService` API.
-By this point the core is minimal and stable — the API boundary has been proven across Phases 14–16.
+Phase 17 consolidates the core's remaining structural debt before the UI extraction (now Phase 18).
+The findings come from the standard discovery pass — fallow suite, entry-point trace, design-review checklist, and test-constructibility audit — run after Phase 16 landed.
+
+### Findings summary
+
+Updated health metrics (fallow, package-wide including tests):
+
+| Metric                     | Phase 16 baseline              | Current                                       |
+| -------------------------- | ------------------------------ | --------------------------------------------- |
+| Health score               | 78/100 (B)                     | 78/100 (B)                                    |
+| Source LOC                 | 7,778 (57 files)               | ~7,400 (56 files)                             |
+| Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                            |
+| Maintainability index      | 90.8 (good)                    | 90.8 (good)                                   |
+| Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                       |
+| Production duplication     | 11 lines (1 internal group)    | 34 lines (1 internal + 1 cross-package group) |
+| Test duplication           | 42 groups, 661 lines           | 44 groups, ~750 lines                         |
+| Fallow refactoring targets | 0                              | 0                                             |
+| Top churn hotspot          | `index.ts` 65.0 ▲ accelerating | `index.ts` 31.3 ▼ cooling                     |
+
+The syntactic metrics are healthy and stable — the remaining debt is structural, mostly invisible to fallow, and concentrated in three places:
+
+1. **`Subagent` construction duality.**
+   `SubagentInit` carries ~20 fields, nearly all optional with "required for run(), optional for tests" semantics, and `run()` compensates with runtime throws ("not configured for execution").
+   This violates principle 8 (construct complete): the class is simultaneously a passive record (tests build display-only snapshots) and an executor (production wires factory, observer, run config, workspace provider).
+   The symptoms are in the tests: external writes `record.promise = …` (manager, queue callback, four test files) and `record.notification = new NotificationState(…)` (seven test sites) are output-argument smells on fields the object should own.
+2. **Wiring debt in `index.ts`.**
+   Two forward references (settings → queue, queue → manager) are replicated with an `eslint-disable prefer-const` dance in `test/lifecycle/subagent-manager.test.ts`; the queue's start callback (`record.promise = record.run()` after a status check) is duplicated verbatim between `index.ts` and the test helper.
+   A ~70-line inline `SubagentManagerObserver` literal mixes three concerns (event emission, `appendEntry` persistence, notification dispatch).
+   `runtime.widget` is assigned post-construction behind five relay-only delegation methods on `SubagentRuntime`.
+3. **Duplication.**
+   A 23-line cross-package production clone (`settings.ts:198-211` ↔ `pi-subagents-worktrees/src/config.ts:51-73`: the layered global/project settings-file loader) and 44 test clone groups (~750 lines), with clone families concentrated in `test/lifecycle/` and `test/ui/`.
+
+Deferred findings (scored below the priority cut, tracked here rather than as steps): the `resolveModel` error-as-string union return (callers branch on `typeof resolved === "string"`), the file-top SDK `eslint-disable` headers in 14 files (re-audit when the Pi SDK exports improve), missing unit tests for `observation/renderer.ts` (the top CRAP-risk file), and the 11-line internal clone in `ui/agent-config-editor.ts` (folds into the Phase 18 UI extraction).
+
+### Steps
+
+Priority = Impact × (6 − Risk).
+
+| Step | Title                                                                                | Category | Impact | Risk | Priority |
+| ---- | ------------------------------------------------------------------------------------ | -------- | ------ | ---- | -------- |
+| 1    | Replace ConcurrencyQueue with a thunk-based ConcurrencyLimiter                       | A/C      | 4      | 2    | 16       |
+| 2    | Decompose `SubagentInit` into `SubagentOptions` (identity, run spec, execution deps) | B/D      | 4      | 3    | 12       |
+| 3    | Encapsulate run start and notification attachment on Subagent                        | C        | 3      | 2    | 12       |
+| 4    | Extract run-listener and workspace-bracket collaborators from Subagent               | B/C      | 3      | 2    | 12       |
+| 5    | Extract the manager observer from index.ts into a class                              | B/E      | 3      | 2    | 12       |
+| 6    | Split widget delegation out of SubagentRuntime                                       | C        | 3      | 3    | 9        |
+| 7    | Consolidate lifecycle test fixtures                                                  | D        | 3      | 1    | 15       |
+| 8    | Consolidate UI and tools test fixtures                                               | D        | 2      | 1    | 10       |
+| 9    | Resolve the cross-package settings-loader duplication                                | A        | 2      | 2    | 8        |
+
+#### Step 1 — Replace ConcurrencyQueue with a thunk-based ConcurrencyLimiter ([#381])
+
+- Targets: `src/lifecycle/concurrency-queue.ts` (→ `concurrency-limiter.ts`), `src/lifecycle/subagent-manager.ts`, `src/index.ts`, `test/lifecycle/concurrency-queue.test.ts`, `test/lifecycle/subagent-manager.test.ts`.
+- Smell: Category C (forward references: the queue's ID-registry design forces a start callback that reaches back into the manager, duplicated between `index.ts` and the test helper) and Category A (dual counting: the queue's `running` counter is fed by `markStarted`/`markFinished` relays in the manager's observer, mirroring state the agents already carry).
+- Change: replace the ID-registry queue with a `ConcurrencyLimiter` that schedules thunks FIFO against a dynamic `getLimit()` — the injected limiter knows nothing about agents, IDs, or the manager.
+  Spawn gates background runs with `limiter.schedule(() => record.run())` (the thunk guards on `queued` status, covering abort-while-queued; Step 3 later folds the guard into `Subagent.start()`); foreground and `bypassQueue` runs invoke directly.
+  The settings `onMaxConcurrentChanged` hook wires to `limiter.recheck()` in `index.ts`; `dispose()` calls `limiter.clear()` to drop pending thunks.
+- Outcome: dependency direction is strictly manager → limiter (no callback back-edge; the `prefer-const` eslint-disable in the test helper is deleted); the observer's two queue relays are gone; every spawned agent has a `promise` at spawn, collapsing `waitForAll`'s `while (true)` drain loop and its eslint-disable.
+
+#### Step 2 — Decompose `SubagentInit` into `SubagentOptions` (identity, run spec, execution deps) ([#373])
+
+- Targets: `src/lifecycle/subagent.ts` (`SubagentInit`, constructor, `run()` guards), `src/lifecycle/subagent-manager.ts` (`spawn`), `test/helpers/make-subagent.ts`.
+- Smell: Category B (god interface — ~20 fields) and Category D (constructibility: "optional for tests" fields with compensating runtime throws).
+- Change: group the per-run fields (snapshot, prompt, model, maxTurns, thinkingLevel, parentSession, signal) into a `SubagentRunSpec` and the shared collaborators (createSubagentSession, observer, getRunConfig, getWorkspaceProvider, baseCwd) into `SubagentExecutionDeps`; the pair is either fully present (executable agent) or fully absent (passive record), collapsing `run()`'s two guards into one.
+  Rename the decomposed bag `SubagentInit` → `SubagentOptions`: it is the codebase's only DOM-style `*Init` name, while sibling constructor bags use `Options` (`SubagentManagerOptions`, `TurnLoopOptions`).
+- Outcome: `SubagentOptions` (née `SubagentInit`) top-level fields ~20 → ≤ 9; a passive test record is constructible without any execution fields; the record-vs-executor duality is explicit in the types.
+
+#### Step 3 — Encapsulate run start and notification attachment on Subagent ([#374])
+
+- Targets: `src/lifecycle/subagent.ts`, `src/lifecycle/subagent-manager.ts`, `test/tools/get-result-tool.test.ts`, `test/lifecycle/subagent-manager.test.ts`, `test/service/service-adapter.test.ts`, `test/observation/notification.test.ts`, `test/helpers/make-subagent.ts`.
+- Smell: Category C — output arguments: external writes to `record.promise` (3 production/test sites) and `record.notification` (7 test sites).
+- Change: add `Subagent.start()` that runs and stores its own promise (plus an awaitable accessor for `spawnAndWait`/`waitForAll`); make `promise` and `notification` externally read-only; tests attach notification state through `SubagentOptions.parentSession.toolCallId` or a dedicated options field.
+- Outcome: zero external writes to `Subagent` fields outside its own methods (grep-verifiable: `\.promise =` and `\.notification =` appear only inside `subagent.ts`).
+
+#### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375])
+
+- Targets: `src/lifecycle/subagent.ts` (533 LOC — largest source file, accelerating churn).
+- Smell: Category B (oversized class; per-run listener fields declared mid-class) and Category C (state owns its mutations: workspace dispose logic appears in `run()`'s catch, `completeRun`, and `failRun`).
+- Change: extract a `RunListeners` object owning the observer-unsubscribe and signal-detach handles (`attach`/`release`), and a workspace-bracket collaborator owning prepare/dispose-with-addendum, so the three dispose paths collapse into one.
+- Outcome: `subagent.ts` ≤ 450 LOC; workspace disposal logic in exactly one place; listener handles no longer raw nullable fields.
+
+#### Step 5 — Extract the manager observer from index.ts into a class ([#376])
+
+- Targets: `src/index.ts` (inline `SubagentManagerObserver` literal, ~70 lines), new module under `src/observation/`.
+- Smell: Category B/E — `index.ts` is the dominant churn hotspot (31.3, 91 commits); the literal mixes event emission, record persistence (`appendEntry`), and notification dispatch; principle 9 (state and behavior belong in classes, not closure-captured literals).
+- Change: extract a class (e.g. `SubagentEventsObserver`) constructed with narrow deps (`emit`, `appendEntry`, the `NotificationSystem`).
+- Outcome: `index.ts` < 170 lines; the observer's three concerns unit-tested directly without booting the extension.
+
+#### Step 6 — Split widget delegation out of SubagentRuntime ([#377])
+
+- Targets: `src/runtime.ts`, `src/tools/agent-tool.ts` (`AgentToolRuntime`), `src/tools/foreground-runner.ts`, `src/tools/background-spawner.ts`, `src/observation/notification.ts` (`NotificationManager` constructor), `src/index.ts`.
+- Smell: Category C — relay-only dependency (five delegation methods that only forward to `widget`) and a post-construction `runtime.widget =` write violating principle 8.
+- Change: pass the existing `WidgetLike` handle directly to the consumers that need it (tool deps, `NotificationManager`) and construct the widget before them; remove the `widget` field and the five relay methods from `SubagentRuntime`.
+- Outcome: `SubagentRuntime` has zero widget knowledge; no post-construction field writes in `index.ts`; tool fixtures stub a 5-method `WidgetLike` instead of widget methods on the runtime mock.
+
+#### Step 7 — Consolidate lifecycle test fixtures ([#378])
+
+- Targets: `test/lifecycle/subagent-manager.test.ts` (766 LOC), `test/lifecycle/subagent.test.ts`, `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/lifecycle/create-subagent-session-extension-tools.test.ts`, `test/lifecycle/concurrency-queue.test.ts`, `test/helpers/`.
+- Smell: Category D — fallow reports five clone families across the lifecycle tests.
+- Change: extract the repeated spawn/run/factory arrangements into shared helpers, migrating incrementally (lift-and-shift, never a single-step rewrite of a large test file).
+- Outcome: lifecycle clone families 5 → ≤ 1; package test duplication below 600 lines.
+
+#### Step 8 — Consolidate UI and tools test fixtures ([#379])
+
+- Targets: `test/ui/agent-creation-wizard.test.ts`, `test/ui/agent-config-editor.test.ts`, `test/ui/ui-observer.test.ts`, `test/tools/foreground-runner.test.ts`, `test/tools/background-spawner.test.ts`, `test/session/session-config.test.ts`.
+- Smell: Category D — remaining clone families outside the lifecycle tree.
+- Change: extract per-file repeated arrangements into local helpers or `test/helpers/` where shared across files.
+- Outcome: package clone groups 44 → ≤ 25; overall duplication ≤ 0.6%.
+
+#### Step 9 — Resolve the cross-package settings-loader duplication ([#380])
+
+- Targets: `src/settings.ts:198-211`, `packages/pi-subagents-worktrees/src/config.ts:51-73`.
+- Smell: Category A — 23-line production clone: the layered global/project JSON read-sanitize-warn-merge loader.
+- Change: decide explicitly between (a) exporting a small `loadLayeredSettings` helper from pi-subagents' public surface for worktrees to consume, and (b) documenting the duplication as intentional (separate release cadences, registry-resolved dependency) with a recorded fallow suppression.
+  The issue weighs the public-API cost (type bundle, `verify:public-types`, docs for third-party authors) against living with the flag.
+- Outcome: `pnpm fallow:dupes` no longer reports the pair, via extraction or recorded suppression.
+
+### Step dependencies
+
+```mermaid
+flowchart TB
+    S1["Step 1 (#381)<br/>ConcurrencyLimiter replacement"]
+    S2["Step 2 (#373)<br/>SubagentOptions decomposition"]
+    S3["Step 3 (#374)<br/>Encapsulate start + notification"]
+    S4["Step 4 (#375)<br/>Run collaborators extraction"]
+    S5["Step 5 (#376)<br/>Observer class from index.ts"]
+    S6["Step 6 (#377)<br/>Widget handle out of runtime"]
+    S7["Step 7 (#378)<br/>Lifecycle test fixtures"]
+    S8["Step 8 (#379)<br/>UI/tools test fixtures"]
+    S9["Step 9 (#380)<br/>Settings-loader duplication"]
+
+    S1 --> S3
+    S2 --> S3
+    S3 --> S4
+    S4 --> S7
+    S5 --> S6
+```
+
+Steps 8 and 9 have no dependencies and can run at any point.
+
+### Tracks
+
+| Track                         | Steps         | Theme                                                                              |
+| ----------------------------- | ------------- | ---------------------------------------------------------------------------------- |
+| A — Subagent constructibility | 2 → 3 → 4 → 7 | Construct complete; encapsulate run state; then consolidate the tests that churned |
+| B — Wiring debt               | 1, 5 → 6      | Shrink index.ts; eliminate forward references and relay delegation                 |
+| C — Test hygiene              | 8             | Clone families outside the lifecycle tree                                          |
+| D — Duplication policy        | 9             | Cross-package clone decision                                                       |
+
+Tracks A and B intersect only at Step 3 (which needs Step 1's queue relocation); otherwise they proceed in parallel.
+Tracks C and D are fully independent.
 
 ## Refactoring history
 
 Phases 1–5, 7–16 are complete.
-Phase 6 (UI extraction to a separate package) is deferred → Phase 17.
+Phase 6 (UI extraction to a separate package) is deferred → Phase 18.
 Detailed records are preserved in per-phase history files:
 
 | Phase | Title                                               | Status              | History                                                                              |
@@ -795,7 +944,8 @@ Detailed records are preserved in per-phase history files:
 | 14    | Strip policy from core                              | Complete            | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
 | 15    | Domain model evolution                              | Complete            | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
 | 16    | Invert dependencies (extensions on a minimal core)  | Complete            | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
-| 17    | Extract UI to separate package                      | Planned             | —                                                                                    |
+| 17    | Core consolidation                                  | Planned             | —                                                                                    |
+| 18    | Extract UI to separate package                      | Planned             | —                                                                                    |
 
 ### Structural refactoring issues
 
@@ -861,4 +1011,13 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#264]: https://github.com/gotgenes/pi-packages/issues/264
 [#265]: https://github.com/gotgenes/pi-packages/issues/265
 [#277]: https://github.com/gotgenes/pi-packages/issues/277
+[#373]: https://github.com/gotgenes/pi-packages/issues/373
+[#374]: https://github.com/gotgenes/pi-packages/issues/374
+[#375]: https://github.com/gotgenes/pi-packages/issues/375
+[#376]: https://github.com/gotgenes/pi-packages/issues/376
+[#377]: https://github.com/gotgenes/pi-packages/issues/377
+[#378]: https://github.com/gotgenes/pi-packages/issues/378
+[#379]: https://github.com/gotgenes/pi-packages/issues/379
+[#380]: https://github.com/gotgenes/pi-packages/issues/380
+[#381]: https://github.com/gotgenes/pi-packages/issues/381
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "15.0.1",
+  "version": "15.0.2",
   "type": "module",
   "exports": {
     ".": {
@@ -59,11 +59,11 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
-    "@earendil-works/pi-ai": "0.75.4",
-    "@earendil-works/pi-coding-agent": "0.75.4",
-    "@earendil-works/pi-tui": "0.75.4",
+    "@earendil-works/pi-ai": "0.79.1",
+    "@earendil-works/pi-coding-agent": "0.79.1",
+    "@earendil-works/pi-tui": "0.79.1",
     "@types/node": "^22.15.3",
-    "rollup": "^4.60.4",
+    "rollup": "^4.61.1",
     "rollup-plugin-dts": "^6.4.1",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",