@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0377-split-widget-delegation-from-runtime.md

@@ -1,254 +0,0 @@
----
-issue: 377
-issue_title: "Split widget delegation out of SubagentRuntime"
----
-
-# Split widget delegation out of SubagentRuntime
-
-## Problem Statement
-
-`SubagentRuntime.widget` is assigned after construction (`runtime.widget = new AgentWidget(...)` in `index.ts`), violating construct-complete (principle 8).
-The runtime then carries five relay-only delegation methods — `setUICtx`, `onTurnStart`, `markFinished`, `update`, `ensureTimer` — that do nothing but forward to `this.widget?`.
-That is a relay-only dependency (design-review check 5): the runtime holds the widget purely to hand it to others, and the coupling leaks into tests, where the `AgentToolRuntime` fixture stubs all five widget methods on the runtime mock.
-
-The issue's "Proposed change" — construct the widget before its consumers and pass the `WidgetLike` handle directly to the tool deps and `NotificationManager` — is the right intent but is **not directly feasible** as stated.
-`NotificationManager` is not just a consumer of the widget; it is a transitive *dependency* of the widget.
-The construction graph contains a genuine cycle:
-
-```text
-NotificationManager → widget → manager → observer (SubagentEventsObserver) → NotificationManager
-```
-
-The widget needs the manager (`listAgents()`); the manager needs the observer; the observer needs the `NotificationSystem`; and `NotificationManager` needs the widget (`markFinished`/`update`).
-The current `runtime.widget` lazy field exists precisely to break this cycle.
-Removing it forces the single unavoidable late seam to move — and the operator's design principles (no setters, instantiate ready-to-work, constructor DI) rule out relocating it to a setter or a forward-referenced `let`.
-
-The cycle has exactly one weak edge: `NotificationManager → widget`.
-Dissolving that edge collapses the cycle entirely, after which the remaining relay removal is mechanical.
-
-## Goals
-
-- Remove the `widget` field and the five relay methods (`setUICtx`, `onTurnStart`, `markFinished`, `update`, `ensureTimer`) from `SubagentRuntime`.
-- Eliminate the post-construction `runtime.widget =` write from `index.ts`.
-- Inject the `AgentWidget` handle directly into its real consumers (`AgentTool`, `ToolStartHandler`) via constructor DI.
-- Dissolve `NotificationManager`'s widget dependency so the construction graph is a clean linear DAG (`notifications → observer → manager → widget → tool/handler`) with no cycle, no setter, and no forward-referenced `let`.
-- Narrow `AgentToolRuntime` to drop the four widget methods it currently declares.
-- Behavior-preserving: no observable change to widget rendering, the finished-agent linger countdown, or completion notifications.
-
-This change is **not breaking** — it is an internal refactor.
-`SubagentRuntime` is not part of the published service surface (`src/service/service.ts`); no exported API, event channel, or config default changes.
-
-## Non-Goals
-
-- Reworking how the widget is rendered, the `/agents` menu, the conversation viewer, or any first-principles UI reconsideration — that is Phase 18.
-- Replacing the widget's poll-based refresh with an event-subscription model — heavier machinery, deferred.
-- Changing `NotificationManager`'s nudge scheduling, `sendMessage` wiring, or `agentActivity` ownership.
-- Touching the foreground-runner / background-spawner direct widget calls (they are already clean consumers that receive the widget from `AgentTool`) beyond the type of the handle they accept.
-- Phase 17 Steps 7–9 (test-fixture consolidation, settings-loader duplication).
-
-## Background
-
-Relevant modules and their current widget coupling:
-
-| Module                            | Current widget coupling                                                                                                                                                      | Disposition                                                       |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `src/runtime.ts`                  | `WidgetLike` interface, `widget` field, 5 relay methods                                                                                                                      | Remove all widget knowledge                                       |
-| `src/index.ts`                    | `runtime.widget = new AgentWidget(...)` post-construction; wires `runtime.markFinished`/`runtime.update` into `NotificationManager`                                          | Construct widget as a `const`; inject directly; reorder           |
-| `src/observation/notification.ts` | `NotificationManager` ctor takes `markFinished` + `updateWidget` callbacks; `sendCompletion`/`cleanupCompleted` call them                                                    | Drop both callbacks; keep `agentActivity.delete` + nudge          |
-| `src/ui/agent-widget.ts`          | `AgentWidget(manager, agentActivity, registry)`; `markFinished(id)` seeds `finishedTurnAge`; `update()` renders                                                              | Self-seed `finishedTurnAge` from `listAgents()` during `update()` |
-| `src/tools/agent-tool.ts`         | `AgentToolRuntime` declares `setUICtx`/`ensureTimer`/`update`/`markFinished`; `execute` calls `this.runtime.setUICtx`; passes `this.runtime` as the widget to runner/spawner | Add a `widget` ctor param; narrow `AgentToolRuntime`              |
-| `src/handlers/tool-start.ts`      | `ToolStartRuntime` declares `setUICtx`/`onTurnStart`; calls them on `this.runtime`                                                                                           | Accept a widget instead of the runtime                            |
-| `src/tools/foreground-runner.ts`  | `ForegroundWidgetDeps { ensureTimer, markFinished }`                                                                                                                         | Unchanged interface; receives the real widget                     |
-| `src/tools/background-spawner.ts` | `BackgroundWidgetDeps { ensureTimer, update }`                                                                                                                               | Unchanged interface; receives the real widget                     |
-
-Key facts establishing behavior preservation for the dissolve:
-
-- The widget timer (`ensureTimer()` → `setInterval(update, 80)`) runs while any agent is active or lingering, and is cleared only on `update()`'s idle path (`!hasActive && !hasFinished`).
-  A background agent is **active at the moment it completes**, so the timer is always running then, and `hasFinished` keeps it running through the linger window.
-- The linger countdown is **turn-based**: `markFinished` seeds `finishedTurnAge[id] = 0`, `onTurnStart` ages every entry by 1, and `shouldShowFinished` hides an agent once its age reaches `maxAge` (1 for completed, 2 for error/aborted).
-  Seeding ≤80ms later (on the next timer tick) lands in the same turn, so the expiry behavior is identical.
-- `NotificationManager.sendCompletion`/`cleanupCompleted` only deletes the live `AgentActivityTracker` (running-display state) — finished agents render from `listAgents()` + `finishedTurnAge`, so the deletion is orthogonal to linger.
-
-AGENTS.md / architecture constraints that apply:
-
-- Principle 8 (construct complete; no post-construction field writes from external code) is the motivating rule — the fix must not relocate the smell to a setter or forward-ref `let` (operator steer).
-- Phase 17 Step 1 deleted a `prefer-const` eslint-disable dance; reintroducing a forward-referenced `let widget` (which trips `prefer-const`, per the `code-design` skill) would regress that and is explicitly avoided.
-- `src/runtime.ts` is **not** in the rolled public type bundle (`exports` points at `src/service/service.ts`), so this change does not require `pnpm run verify:public-types`.
-
-`AgentWidget`, `NotificationManager`, and the runtime are all internal; the published `SubagentsService` (via `service-adapter.ts`, which consumes the runtime's `currentCtx`/`buildSnapshot` only) is untouched.
-
-## Design Overview
-
-### Decision: dissolve the cycle, don't relocate the seam
-
-Three candidate seam placements were considered (recorded for the retro):
-
-1. **Late-bind notifications into the observer via a setter** — rejected: violates the no-setters principle; leaves a post-construction write.
-2. **Forward-referenced `let widget` + closures into `NotificationManager`** — rejected: trips `prefer-const` → eslint-disable, reintroducing the exact smell Phase 17 Step 1 removed; not "ready-to-work."
-3. **Dissolve `NotificationManager`'s widget dependency (chosen)** — the widget owns its own finished-agent detection; `NotificationManager` no longer references the widget; the cycle disappears and every object is constructible ready-to-work in a single linear pass.
-
-### Tidy-first sequencing
-
-Per "make the change that makes the change easy, then make the easy change," the work splits into a hard preparatory refactor and a mechanical follow-up:
-
-- **Prep (Step 1, the hard part):** make the widget self-sufficient and remove the widget callbacks from `NotificationManager`.
-  This breaks the cycle while `SubagentRuntime` still carries its relay methods (so `AgentTool`/`ToolStartHandler` are untouched and the repo stays green).
-- **Easy (Step 2):** with the cycle gone, the widget becomes a `const` injected directly into `AgentTool` and `ToolStartHandler`; the five relay methods, the `widget` field, and the post-construction write delete cleanly.
-
-### Widget self-seeding
-
-Add a private helper invoked at the top of `update()`, before state assembly:
-
-```ts
-/** Seed linger tracking for any newly-observed finished agent (replaces external markFinished). */
-private seedFinishedAgents(agents: readonly AgentSummary[]): void {
-  for (const a of agents) {
-    if (a.completedAt && !this.finishedTurnAge.has(a.id)) {
-      this.finishedTurnAge.set(a.id, 0);
-    }
-  }
-}
-```
-
-`update()` calls `this.seedFinishedAgents(allAgents)` immediately after `const allAgents = this.manager.listAgents()`.
-The existing public `markFinished(id)` stays (foreground-runner still calls it directly for immediacy, and it remains idempotent — `seedFinishedAgents` only seeds when absent).
-
-### NotificationManager after the dissolve
-
-Constructor drops the last two params:
-
-```ts
-constructor(
-  private sendMessage: (msg: {...}, opts?: {...}) => void,
-  private agentActivity: Map<string, AgentActivityTracker>,
-) {}
-```
-
-`sendCompletion(record)` → `agentActivity.delete(record.id)`; `scheduleNudge(...)` (drop `markFinished` + `updateWidget`).
-`cleanupCompleted(id)` → `agentActivity.delete(id)` (drop `markFinished` + `updateWidget`).
-The `NotificationSystem` interface is unchanged (method signatures identical).
-
-### Consumer interfaces after the easy change (ISP — narrow per consumer)
-
-Drop the shared 5-method `WidgetLike` from `runtime.ts`.
-Each consumer declares only what it uses; `AgentWidget` satisfies all structurally:
-
-```ts
-// agent-tool.ts — the slice AgentTool + its runner/spawner need
-export interface AgentToolWidget {
-  setUICtx(ctx: UICtx): void;
-  ensureTimer(): void;
-  markFinished(id: string): void;
-  update(): void;
-}
-
-// tool-start.ts — the slice the turn handler needs
-export interface ToolStartWidget {
-  setUICtx(ctx: unknown): void;
-  onTurnStart(): void;
-}
-```
-
-`AgentTool` gains a `widget: AgentToolWidget` constructor param; `execute` calls `this.widget.setUICtx(...)` and passes `this.widget` to `runForeground`/`spawnBackground` (which already accept the narrow `ForegroundWidgetDeps`/`BackgroundWidgetDeps`).
-`ToolStartHandler` accepts a `ToolStartWidget` instead of `ToolStartRuntime` (rename).
-`AgentToolRuntime` loses `setUICtx`, `ensureTimer`, `update`, `markFinished` — keeping `agentActivity`, `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
-
-### Final construction order in `index.ts`
-
-```text
-registry → runtime → notifications(sendMessage, agentActivity)
-        → settings → observer(notifications) → limiter → manager(observer)
-        → service → lifecycle(runtime) → session handlers
-        → const widget = new AgentWidget(manager, agentActivity, registry)
-        → toolStart = new ToolStartHandler(widget)
-        → AgentTool(manager, runtime, widget, settings, registry, agentDir)
-        → GetResultTool / SteerTool / agentsMenu
-```
-
-No object is mutated after construction; the widget is a `const`.
-`service-adapter.ts` and `lifecycle.ts` keep consuming `runtime` for `currentCtx`/`buildSnapshot`/`setSessionContext` — none of which involve the widget.
-
-## Module-Level Changes
-
-- `src/observation/notification.ts` — remove `markFinished` and `updateWidget` constructor params; drop their calls in `sendCompletion`/`cleanupCompleted`.
-  `NotificationSystem` interface unchanged.
-- `src/ui/agent-widget.ts` — add private `seedFinishedAgents(agents)`; call it at the top of `update()` after `listAgents()`.
-  `markFinished` retained (idempotent).
-- `src/runtime.ts` — delete the `WidgetLike` interface, the `widget` field, and the five relay methods (`setUICtx`, `onTurnStart`, `markFinished`, `update`, `ensureTimer`); remove the now-unused `UICtx` import.
-  Update the class/file doc comment to drop "Persistent widget reference" / "Widget delegation methods."
-- `src/tools/agent-tool.ts` — add `AgentToolWidget` interface; add `widget` constructor param; `execute` uses `this.widget` for `setUICtx` and passes it to runner/spawner; narrow `AgentToolRuntime` (drop 4 widget methods); remove now-unused `WidgetLike`-related imports if any.
-- `src/handlers/tool-start.ts` — rename `ToolStartRuntime` → `ToolStartWidget`; constructor takes the widget; `handleToolExecutionStart` calls `this.widget.setUICtx`/`this.widget.onTurnStart`.
-- `src/index.ts` — construct `NotificationManager` with two args; construct `const widget = new AgentWidget(...)` after the manager; pass `widget` to `new ToolStartHandler(...)` and `new AgentTool(...)`; remove the `runtime.widget =` line and the stale comment block above the `NotificationManager` construction.
-- `test/observation/notification.test.ts` — drop the `markFinished`/`updateWidget` stub fields and the two `toHaveBeenCalled` assertions; assert `agentActivity.delete` + nudge behavior instead.
-- `test/ui/agent-widget.test.ts` — add coverage: `update()` self-seeds `finishedTurnAge` for a completed agent in `listAgents()`; the agent then expires after `maxAge` turns via `onTurnStart`; an already-seeded agent is not re-seeded.
-- `test/runtime.test.ts` — remove the "widget delegation methods" describe block, the "widget field accepts a `WidgetLike` stub" test, the `runtime.widget` default assertion, the `WidgetLike` import, and the `createWidgetStub` helper.
-- `test/helpers/make-deps.ts` — add a `widget` field (stub satisfying `AgentToolWidget`) to `AgentToolFixture`; narrow the `runtime` stub (drop `setUICtx`/`ensureTimer`/`update`/`markFinished`); update the doc comment that claims the runtime "also satisfies `BackgroundWidgetDeps`/`ForegroundWidgetDeps`."
-- `test/tools/agent-tool.test.ts` — `makeTool` passes `deps.widget`; the "sets UI context on runtime" test asserts on `deps.widget.setUICtx`.
-- `test/handlers/tool-start.test.ts` — construct `ToolStartHandler` with a widget stub; assert on `widget.setUICtx`/`widget.onTurnStart`.
-- `docs/architecture/architecture.md` — rewrite the Step 6 `- Change:` / `- Outcome:` bullets to the dissolve approach; add a `- Landed:` bullet and mark the heading `✅ Complete`.
-  The findings-summary line (~915) describing the smell stays accurate and is left unchanged.
-
-No `.pi/skills/package-pi-subagents/SKILL.md` references to `runtime.widget`, `WidgetLike`, or the relay methods exist (grep-verified), so no skill update is required.
-
-## Test Impact Analysis
-
-1. **New tests enabled by the extraction.**
-   Widget self-seeding (`seedFinishedAgents`) becomes directly unit-testable on `AgentWidget` via a stub manager whose `listAgents()` returns a completed record — previously the seeding path was only reachable through `NotificationManager.markFinished`.
-   `NotificationManager` becomes testable without any widget stub at all.
-2. **Tests simplified / made redundant.**
-   The two `NotificationManager` assertions on `markFinished`/`updateWidget` are deleted (the behavior moved to the widget).
-   The entire `SubagentRuntime` "widget delegation methods" describe block (5 trivial pass-through tests) and the `WidgetLike` stub plumbing are removed — pure relay tests with no remaining subject.
-3. **Tests that must stay as-is.**
-   The widget's render/linger/timer tests in `agent-widget.test.ts` (turn-aging via `onTurnStart`, `shouldShowFinished` thresholds, idle-path `clearWidget`) genuinely exercise the layer and are unchanged — the new self-seed test sits alongside them.
-   `NotificationManager`'s nudge-scheduling and `sendMessage` tests are unchanged.
-
-## Invariants at risk
-
-This step touches surfaces refactored by earlier Phase 17 steps; their documented outcomes must not regress:
-
-- **Step 1 (`#381`) — "every spawned agent has a `promise` at spawn; no forward-ref `prefer-const` eslint-disable."**
-  Pinned by the limiter/manager tests in `test/lifecycle/`.
-  Reintroducing a forward-ref `let widget` would regress this spirit — the chosen dissolve approach specifically avoids it.
-- **Step 5 (`#376`) — "`index.ts` < 170 lines; observer's three concerns unit-tested directly."**
-  This step removes lines from `index.ts` (relay wiring + `runtime.widget =`), so the line budget is preserved or improved; `SubagentEventsObserver` is untouched.
-  No new behavior is added to `index.ts`.
-- **Construct-complete (principle 8), the roadmap-wide Category-B/C invariant.**
-  Pinned after this change by the absence of any `runtime.widget =` (grep-verifiable) and by `test/runtime.test.ts` no longer constructing a widget — add the grep check to the acceptance criteria.
-
-## TDD Order
-
-1. **Widget self-detects finished agents (prep — make it easy).**
-   - Red: in `test/ui/agent-widget.test.ts`, assert `update()` seeds `finishedTurnAge` for a completed agent returned by `listAgents()` (rendered as finished), that it expires after `maxAge` turns via `onTurnStart`, and that an already-tracked agent is not re-seeded.
-   - Green: add `private seedFinishedAgents(agents)` and call it at the top of `update()`.
-   - Commit: `test:` then `feat:` — or a single `feat: self-seed finished agents in AgentWidget.update (#377)`.
-2. **Drop widget callbacks from NotificationManager (prep — breaks the cycle).**
-   - Red/Green: update `test/observation/notification.test.ts` to construct `NotificationManager` with two args and assert `agentActivity.delete` + nudge (drop the `markFinished`/`updateWidget` assertions); remove the two callbacks from the constructor and from `sendCompletion`/`cleanupCompleted`; update the `index.ts` construction site in the same commit (sole call site — the type checker requires it atomic).
-   - Commit: `refactor: dissolve NotificationManager widget dependency (#377)`.
-   - Outcome: the construction cycle is gone; `SubagentRuntime` still carries its relay methods (repo green).
-3. **Inject the widget directly; remove relay methods and the widget field from SubagentRuntime (the easy change).**
-   - This is one atomic commit: removing the `widget` field, the five relay methods, and narrowing `AgentToolRuntime` breaks `AgentTool`, `ToolStartHandler`, `index.ts`, and their tests at the type level simultaneously (export/field removal — per the workflow rule, fold all consumer and consumer-test updates into one step).
-   - Changes: add `AgentToolWidget` + `widget` param to `AgentTool`; rename `ToolStartRuntime` → `ToolStartWidget` and accept the widget in `ToolStartHandler`; delete `WidgetLike` + `widget` + 5 relay methods from `runtime.ts`; construct `const widget` and reorder `index.ts` (remove the `runtime.widget =` write); update `make-deps.ts` (add `widget` stub, narrow `runtime`), `agent-tool.test.ts`, `tool-start.test.ts`, and `runtime.test.ts` (delete the delegation describe block + `WidgetLike` plumbing).
-   - Commit: `refactor: inject widget directly, remove relay methods from SubagentRuntime (#377)`.
-   - Acceptance: `rg 'runtime\.widget|\.widget =' src/` returns nothing; `rg 'WidgetLike' src/ test/` returns nothing; `pnpm run check && pnpm run lint && pnpm -r run test && pnpm fallow dead-code` clean.
-4. **Update the architecture roadmap.**
-   - Rewrite Step 6 `- Change:`/`- Outcome:` to the dissolve approach, add `- Landed:`, mark `✅ Complete`.
-   - Commit: `docs: record Phase 17 Step 6 widget-delegation split (#377)`.
-
-## Risks and Mitigations
-
-- **Risk: self-seed timing differs from the old immediate `markFinished`/`update`.**
-  Mitigation: the timer is always running at a background completion (the agent was active); the seed lands ≤80ms later within the same turn; linger expiry is turn-based, so the rendered outcome is identical.
-  The new widget test pins the seed-then-expire behavior.
-- **Risk: a completed agent never expires if it is never seeded.**
-  Mitigation: `seedFinishedAgents` runs on every `update()` tick while the widget is live; the idle-path `clearWidget` only fires once nothing is active or finished, so a finished agent is always seeded before the widget can go idle.
-- **Risk: removing exports/fields breaks consumers mid-refactor.**
-  Mitigation: Step 2 breaks the cycle while leaving the relay methods in place (repo green); Step 3 folds the export/field removal and all consumers + tests into one atomic commit.
-- **Risk: regressing an earlier Phase 17 invariant (forward-ref dance, `index.ts` budget).**
-  Mitigation: the dissolve approach introduces no `let widget` and only removes lines from `index.ts`; the Invariants-at-risk grep checks are in the Step 3 acceptance criteria.
-
-## Open Questions
-
-- Should `AgentTool` receive one `AgentToolWidget` and forward it, or should it receive the narrower `ForegroundWidgetDeps`/`BackgroundWidgetDeps` separately?
-  Plan assumes a single `AgentToolWidget` superset (it also calls `setUICtx` itself) forwarded to the runner/spawner — revisit only if ISP pressure appears during implementation.
-- Whether foreground-runner's explicit `markFinished(fgId)` is now redundant given widget self-seeding.
-  Plan keeps it (immediacy; idempotent) to hold scope tight; a follow-up could remove it if the self-seed proves sufficient.

package/docs/plans/0378-consolidate-lifecycle-test-fixtures.md

@@ -1,243 +0,0 @@
----
-issue: 378
-issue_title: "Consolidate lifecycle test fixtures"
----
-
-# Consolidate lifecycle test fixtures
-
-## Problem Statement
-
-`pnpm fallow:dupes` reports clone families concentrated in `test/lifecycle/`: repeated spawn-and-await arrangements and session-factory stubs copy-pasted across files and within them.
-This is Phase 17 Step 7 (core consolidation), sequenced after Steps 2–6 reshaped `Subagent` construction so the lifecycle tests had already churned.
-The roadmap Outcome is: lifecycle clone families 5 → ≤ 1; package test duplication below 600 lines.
-
-The issue body cites five families across six files (including `concurrency-queue.test.ts` and `subagent.test.ts` at 766 LOC).
-That snapshot predates Steps 1–6.
-The current state — measured with `fallow dupes -r packages/pi-subagents` against today's `main` — is **four** lifecycle clone families, because the queue was renamed to `concurrency-limiter.test.ts` ([#381]) and `subagent.test.ts`/`concurrency-limiter.test.ts` no longer report families after the Step 2–4 reshaping.
-
-## Goals
-
-- Consolidate the four current lifecycle clone families into shared or file-local helpers so the lifecycle tree reports ≤ 1 family.
-- Bring package-wide test duplication below 600 lines (current baseline: 669 lines / 3.3% across 20 files; the four lifecycle families total ~122 lines).
-- Preserve every existing test assertion — the existing suite is the regression guard for this refactor.
-- Keep the change non-breaking: test-only, no production-code, public-surface, or behavior change.
-
-## Non-Goals
-
-- Step 8 ([#379]) — UI and tools clone families (`agent-config-editor`, `agent-creation-wizard`, `ui-observer`, `foreground-runner`, `service-adapter`).
-  These are separate families outside the lifecycle tree and are deferred to their own issue.
-- Step 9 ([#380]) — the cross-package settings-loader production clone.
-- Any production-code change in `src/`.
-- Adding new behavioral test cases — this is duplication removal, not coverage expansion (helper self-tests are the only new `it` blocks).
-
-## Background
-
-The lifecycle suite already has substantial shared scaffolding under `test/helpers/`:
-
-- `subagent-session-io.ts` — `createSubagentSessionIO()`, `createAgentLookup()`, `createSubagentSessionDeps()`, `createChildLifecycleMock()`.
-  The natural home for shared `createSubagentSession`-test scaffolding.
-- `manager-stubs.ts` — `createBlockingFactory()`, `createSessionFactory()`.
-- `mock-session.ts` — `createMockSession()`, `createSubagentSessionStub()`, `toSubagentSession()`, `toAgentSession()`.
-- `make-subagent.ts` — `createTestSubagent()`, `makeStubExecution()`.
-
-Convention: every shared helper module under `test/helpers/` has a companion `*.test.ts` (e.g. `subagent-session-io.test.ts`, `make-subagent.test.ts`).
-New or extended shared helpers must extend that companion test.
-
-The four current lifecycle clone families and the repeated blocks driving them:
-
-| File                                              | Family             | Repeated block                                                                                                                                                                                                                       |
-| ------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `create-subagent-session.test.ts`                 | 3 groups, 31 lines | A file-local `createSession()` mock-session builder, then `io.createSession.mockResolvedValue({ session })` + `await createSubagentSession({ snapshot, type }, createSubagentSessionDeps({ io, exec, registry[, lifecycle] }))`      |
-| `create-subagent-session-extension-tools.test.ts` | 3 groups, 29 lines | A near-identical file-local `createSessionWithExtensionToolRegistration()` builder, then the same `io.createSession.mockResolvedValue` + `createSubagentSession(...)` invoke block, plus post-bind `setActiveToolsByName` assertions |
-| `subagent-manager.test.ts`                        | 4 groups, 40 lines | `spawn(STUB_SNAPSHOT, "general-purpose", "test", { description, isBackground: true, parentSession: { toolCallId } })` and the "spawn two bg agents under limit 1, assert one queued" arrange                                         |
-| `subagent-session.test.ts`                        | 3 groups, 22 lines | Repeated arrange blocks around the already-local `createSession(finalText)` / `makeSubagentSession()` / `emitTurnEnd()` helpers                                                                                                      |
-
-The two `createSubagentSession`-test session builders (`createSession` and `createSessionWithExtensionToolRegistration`) build near-identical mock sessions — the same eight `vi.fn()` methods — differing only in that the extension-tools variant flips `getActiveToolNames` between a before-bind and after-bind set.
-That overlap is the one genuinely cross-file duplication and the strongest candidate for promotion to `test/helpers/`.
-The manager and `subagent-session` families are intra-file.
-
-AGENTS.md / testing-skill constraints that apply:
-
-- When consolidating duplicate test factories, diff the default values across all copies before writing the shared factory — different defaults cause cascading assertion failures during migration.
-- When a TDD step deletes a test helper, re-check the file's remaining imports for orphans — Biome's `noUnusedImports` is warning-level (exit 0), so it will not fail `pnpm run lint`.
-- Run the full suite (not just the touched file) after each shared-helper change.
-
-## Design Overview
-
-The guiding distinction: **promote to `test/helpers/` only what is genuinely shared across files; keep intra-file families as file-local helpers.**
-Fallow's own recommendation for three of the four families is "extract shared function from `<file>`, `<file>`" (same file on both sides) — promoting those to `test/helpers/` would manufacture cross-file coupling that does not exist.
-
-### 1. Shared: a mock-session builder for `createSubagentSession` tests
-
-Add `createFactorySession(overrides?)` to `test/helpers/subagent-session-io.ts`.
-It returns the eight-method mock session both `createSubagentSession` test files build by hand today, with `getActiveToolNames` supporting a static set or a before/after-bind flip:
-
-```typescript
-export interface FactorySessionOptions {
-  /** Tools active before bindExtensions(). Default ["read"]. */
-  toolsBeforeBind?: string[];
-  /** Tools active after bindExtensions(). Defaults to toolsBeforeBind (no extension registration). */
-  toolsAfterBind?: string[];
-}
-
-export function createFactorySession(options: FactorySessionOptions = {}) {
-  const before = options.toolsBeforeBind ?? ["read"];
-  const after = options.toolsAfterBind ?? before;
-  let bound = false;
-  return {
-    messages: [] as unknown[],
-    subscribe: vi.fn(() => () => {}),
-    prompt: vi.fn().mockResolvedValue(undefined),
-    abort: vi.fn(),
-    steer: vi.fn().mockResolvedValue(undefined),
-    dispose: vi.fn(),
-    getActiveToolNames: vi.fn(() => (bound ? after : before)),
-    setActiveToolsByName: vi.fn(),
-    bindExtensions: vi.fn(async () => { bound = true; }),
-  };
-}
-```
-
-Return type is deliberately unannotated so callers retain the `Mock<...>` methods (`mock.calls`, `mockResolvedValue`) — matching the existing `createSubagentSessionIO()` convention in this file.
-
-`create-subagent-session.test.ts` replaces `createSession()` with `createFactorySession()`; the existing static `getActiveToolNames: () => ["read"]` becomes the default branch (`bound === after === before === ["read"]`), so the lone `bindExtensions` flip is inert there — behavior-preserving.
-`create-subagent-session-extension-tools.test.ts` replaces `createSessionWithExtensionToolRegistration(before, after)` with `createFactorySession({ toolsBeforeBind: before, toolsAfterBind: after })`.
-
-Consumer call site (verifies Tell-Don't-Ask: the helper returns a ready mock; the test arranges and asserts on it):
-
-```typescript
-const session = createFactorySession({ toolsBeforeBind: ["read"], toolsAfterBind: ["read", "extension_tool"] });
-io.createSession.mockResolvedValue({ session });
-await createSubagentSession({ snapshot: STUB_SNAPSHOT, type: "test-agent" }, createSubagentSessionDeps({ io, exec, registry }));
-expect(session.setActiveToolsByName.mock.calls[0][0]).toContain("extension_tool");
-```
-
-The repeated `io.createSession.mockResolvedValue({ session })` + `createSubagentSession(...)` invoke pair is left in the tests rather than wrapped in an `invokeCreate()` helper: it is two lines, the `params` and `deps` overrides vary per test, and wrapping it would hide the system-under-test call behind a helper (procedure-splitting, not design improvement).
-Extracting only the session builder removes the bulk of both families because the builder is the larger half of each clone.
-
-### 2. File-local: manager spawn / queued-pair arrangements
-
-`subagent-manager.test.ts` already has file-local `spawnBg`/`spawnFg`/`createManager`/`defaultFactory`.
-The remaining 40 lines are two intra-file patterns; add two file-local helpers:
-
-```typescript
-/** Spawn a background agent carrying a parentSession.toolCallId (notification path). */
-function spawnBgWithToolCall(mgr: SubagentManager, toolCallId: string, prompt = "test") {
-  return mgr.spawn(STUB_SNAPSHOT, "general-purpose", prompt, {
-    description: prompt,
-    isBackground: true,
-    parentSession: { toolCallId },
-  });
-}
-
-/** Arrange a manager at limit 1 with two bg agents: first runs, second queues. */
-function arrangeQueuedPair() {
-  const { manager } = createManager({ createSubagentSession: createBlockingFactory(), getMaxConcurrent: () => 1 });
-  const running = spawnBg(manager, "a");
-  const queued = spawnBg(manager, "b");
-  return { manager, running, queued };
-}
-```
-
-These stay file-local: they reference manager-specific concerns and fallow scores the family as same-file.
-
-### 3. File-local: `subagent-session.test.ts` arrange blocks
-
-The three small groups (22 lines) sit around the existing file-local `createSession(finalText)`, `makeSubagentSession()`, and `emitTurnEnd()` helpers.
-Fold the repeated "build session, build SubagentSession, run/emit" arrange into one file-local helper (e.g. `arrangeSession(finalText, metaOverrides?)` returning `{ session, listeners, sub }`), keeping the per-test assertions inline.
-No promotion to `test/helpers/` — this builder is specific to `subagent-session.test.ts`'s turn-loop assertions and is not used elsewhere.
-
-## Module-Level Changes
-
-- `test/helpers/subagent-session-io.ts` — add `createFactorySession()` and `FactorySessionOptions`.
-- `test/helpers/subagent-session-io.test.ts` — add a `describe("createFactorySession")` block: default tool set, before/after-bind flip, all eight methods present.
-- `test/lifecycle/create-subagent-session.test.ts` — delete local `createSession()`; import and use `createFactorySession()`; re-check imports for orphans.
-- `test/lifecycle/create-subagent-session-extension-tools.test.ts` — delete local `createSessionWithExtensionToolRegistration()`; use `createFactorySession({ toolsBeforeBind, toolsAfterBind })`; re-check imports.
-- `test/lifecycle/subagent-manager.test.ts` — add file-local `spawnBgWithToolCall()` and `arrangeQueuedPair()`; route the cloned spawn/queued-pair sites through them.
-- `test/lifecycle/subagent-session.test.ts` — add a file-local `arrangeSession()` helper; route the cloned arrange blocks through it.
-- `docs/architecture/architecture.md` — mark Step 7 ✅ Complete and add a `Landed:` bullet (matching Steps 1–6), updating the families and duplication figures.
-
-No `src/` files change.
-No public surface changes, so `verify:public-types` is unaffected.
-The `package-pi-subagents` SKILL.md's test count line ("994 tests across 63 files as of Phase 17 Step 4") is a point-in-time figure, not a Step-7 reference, and is left untouched.
-
-## Test Impact Analysis
-
-This is a test-refactoring issue, so the lens is inverted from a production extraction:
-
-1. **New tests the change enables.**
-   Only helper self-tests: a `createFactorySession` block in `subagent-session-io.test.ts` (per the `test/helpers/` companion-test convention).
-   No new behavioral tests — the refactor must not change coverage.
-2. **Existing tests that become redundant.**
-   None are removed.
-   The duplication being removed is *arrange-block* duplication inside `it()` bodies, not duplicate `it()` cases.
-   Every existing assertion stays.
-3. **Tests that must stay as-is.**
-   All 228 lifecycle test cases keep their assertions; they are the regression guard.
-   Migration is green-to-green: after each file's migration the full suite must stay passing.
-   In particular, the post-bind `setActiveToolsByName` assertions in the extension-tools file and the turn-limit/`emitTurnEnd` assertions in `subagent-session.test.ts` are unchanged — only their session-construction arrange is swapped.
-
-## Invariants at risk
-
-This step touches `subagent-manager.test.ts`, which pins invariants from earlier Phase 17 steps.
-The `arrangeQueuedPair()` helper must not swallow these:
-
-- **Step 1 ([#381]) / Step 3 ([#374]) — "every spawned agent has a `promise` at spawn, even while queued."**
-  Pinned by `subagent-manager.test.ts` → `it("gives a queued agent an awaitable promise at spawn (before its slot opens)")`, which asserts `getRecord(queuedId)!.promise` is a `Promise` while status is `"queued"`.
-  When this test adopts `arrangeQueuedPair()`, the helper must still return the queued id so the test can assert on `.promise` directly.
-- **Step 3 ([#374]) — "zero external writes to `Subagent.promise`/`.notification` outside `subagent.ts`" (grep-verifiable).**
-  The helper migration must not reintroduce `record.promise =` or `record.notification =`.
-  The existing `record.notification!.markConsumed()` sites are method calls, not writes, and stay as-is.
-  Re-grep `test/lifecycle/` for `\.promise =` and `\.notification =` after the manager migration to confirm none were added.
-
-## TDD Order
-
-This is a lift-and-shift refactor of tests; the suite is green at every step (no red phase — the existing assertions are the spec).
-Each migration step runs the full package suite before committing.
-
-1. **Add shared `createFactorySession` + helper test.**
-   Surface: `test/helpers/subagent-session-io.ts`, `test/helpers/subagent-session-io.test.ts`.
-   Covers: default tool set, before/after-bind flip, method presence.
-   Run `pnpm --filter @gotgenes/pi-subagents exec vitest run test/helpers/subagent-session-io.test.ts` then `pnpm run check`.
-   Commit: `test: add shared createFactorySession mock-session builder (#378)`.
-2. **Migrate `create-subagent-session.test.ts` to `createFactorySession`.**
-   Delete local `createSession()`, re-check imports, run full suite green.
-   Commit: `test: use shared factory session in create-subagent-session tests (#378)`.
-3. **Migrate `create-subagent-session-extension-tools.test.ts` to `createFactorySession({ toolsBeforeBind, toolsAfterBind })`.**
-   Delete local `createSessionWithExtensionToolRegistration()`, re-check imports, run full suite green.
-   Commit: `test: use shared factory session in extension-tools tests (#378)`.
-4. **Consolidate `subagent-manager.test.ts` spawn/queued-pair arrangements.**
-   Add `spawnBgWithToolCall()` and `arrangeQueuedPair()`; route the cloned sites through them; re-grep for `.promise =`/`.notification =`; run full suite green.
-   Commit: `test: consolidate manager spawn arrangements (#378)`.
-5. **Consolidate `subagent-session.test.ts` arrange blocks.**
-   Add `arrangeSession()`; route cloned sites; run full suite green.
-   Commit: `test: consolidate subagent-session arrange blocks (#378)`.
-6. **Verify and record outcome.**
-   Run `pnpm exec fallow dupes -r packages/pi-subagents` and confirm lifecycle families ≤ 1 and package duplication < 600 lines; run `pnpm run check && pnpm run lint && pnpm fallow dead-code`.
-   Update `docs/architecture/architecture.md` Step 7 to ✅ Complete with a `Landed:` bullet and refreshed figures.
-   Commit: `docs: mark Phase 17 Step 7 complete (#378)`.
-
-Steps 2–5 are independent of each other and order-insensitive; each only depends on Step 1's helper.
-
-## Risks and Mitigations
-
-- **Divergent defaults between the two session builders cause assertion failures.**
-  Mitigation: the two builders are diffed in Background — they share eight identical methods and differ only in `getActiveToolNames`.
-  `createFactorySession` defaults `toolsAfterBind` to `toolsBeforeBind` so the non-extension file's static behavior is preserved exactly.
-- **Over-extraction / procedure-splitting to chase the metric.**
-  Mitigation: the invoke pair (`mockResolvedValue` + `createSubagentSession(...)`) and the per-test assertions are left inline; only value-returning builders are extracted.
-  File-local families stay file-local rather than being force-promoted to `test/helpers/`.
-- **Orphaned imports after deleting local builders (Biome `noUnusedImports` is warning-level, exit 0).**
-  Mitigation: re-check each migrated file's imports as part of its step; the Step 6 `pnpm run lint` + dead-code pass is the backstop.
-- **Regressing a cross-step invariant with a green suite (the Step 3 lesson).**
-  Mitigation: the "Invariants at risk" section names the pinning tests and the grep checks folded into Step 4.
-
-## Open Questions
-
-- Whether package-wide duplication lands below 600 lines from Step 7 alone or needs Step 8 ([#379]).
-  Arithmetic says yes (669 − ~122 ≈ 547), but the Step 6 `fallow dupes` measurement is the authority; if it lands above 600, note it and confirm the lifecycle-families target (≤ 1) is still met rather than pulling Step 8 work forward.
-
-[#374]: https://github.com/gotgenes/pi-packages/issues/374
-[#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