@gotgenes/pi-subagents 16.3.1 → 16.5.0

package/docs/architecture/architecture.md

@@ -271,7 +271,7 @@ sequenceDiagram
 
 ## Module organization
 
-The extension has 58 source files organized into six domains plus entry-point wiring.
+The extension has 62 source files organized into six domains plus entry-point wiring.
 All eight domains have directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
 Issue #164 moved the 26 previously flat root-level files into five new domain directories, reducing the root to 5 files + 8 directories.
 
@@ -284,6 +284,7 @@ src/
 ├── types.ts                        shared type definitions
 ├── settings.ts                     SettingsManager (persistent operational settings)
 ├── debug.ts                        debug logging utility
+├── layered-settings.ts             loadLayeredSettings helper (published as @gotgenes/pi-subagents/settings)
 │
 ├── config/                         agent type definitions and resolution
 │   ├── agent-types.ts              AgentTypeRegistry class
@@ -320,7 +321,8 @@ src/
 │   ├── record-observer.ts          session-event stats observer
 │   ├── notification.ts             completion nudges
 │   ├── notification-state.ts       per-agent notification tracking
-│   └── renderer.ts                 notification TUI component
+│   ├── renderer.ts                 notification TUI component
+│   └── subagent-events-observer.ts manager lifecycle observer (event emission + persistence + notification)
 │
 ├── service/                        cross-extension API boundary
 │   ├── service.ts                  SubagentsService interface + Symbol.for() accessors
@@ -520,7 +522,7 @@ The governing rule — **no vacant hooks**: the architecture must _admit_ a seam
 A provider seam with no consumer is a speculative abstraction that taxes every reader and that `fallow` flags as dead.
 Latent extensibility is the deliverable; a vacant hook is not.
 
-The [first-principles refinement](#first-principles-refinement-the-deeper-target) below sharpens this two-surface split.
+The [first-principles refinement](#first-principles-refinement-and-the-deeper-target) below sharpens this two-surface split.
 The awaited, behavior-affecting lifecycle events (notably `session-created` before `bindExtensions`) are _hooks_ — the child's own extension surface applied recursively, generative because the core waits on the handler before deciding what to do next.
 The observational surface then carries only fire-and-forget broadcasts of immutable snapshots, which no consumer can use to change the core.
 
@@ -554,14 +556,14 @@ In the target state, pi-subagents publishes events and a provider seam; other pa
 
 - **pi-permission-system** (observational) subscribes to child-session lifecycle events, detects subagent execution context in the child, and gates tool calls at runtime.
 - **pi-subagents-worktrees** (generative) registers a `WorkspaceProvider` that prepares a git worktree at run-start and tears it down after, supplying the child's cwd.
-- **pi-subagents-ui** (future, under reconsideration — see the [first-principles refinement](#first-principles-refinement-the-deeper-target)) subscribes to the broadcast and the query/behavior interfaces; whether the inherited widget, conversation viewer, and `/agents` menu survive is judged on our principles, not preserved by default.
+- **pi-subagents-ui** (future, under reconsideration — see the [first-principles refinement](#first-principles-refinement-and-the-deeper-target)) subscribes to the broadcast and the query/behavior interfaces; whether the inherited widget, conversation viewer, and `/agents` menu survive is judged on our principles, not preserved by default.
 - **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
 
 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 18 (reconsider UI).
 
-### First-principles refinement (the deeper target)
+### First-principles refinement and the deeper target
 
 The two-surface model above is correct but coarse.
 Pushing it against our own principles — construct complete, state owns its mutations, tell-don't-ask, dependency inversion — surfaces sharper boundaries that the current code draws through the middle of classes.
@@ -643,17 +645,17 @@ That method — testability friction as a boundary probe, with its limits — is
 
 ### Health metrics
 
-| Metric                     | Value                                   |
-| -------------------------- | --------------------------------------- |
-| Health score               | 78/100 (B)                              |
-| Total LOC                  | 8,356 (61 files, as of Phase 17 Step 5) |
-| Dead code                  | 0 files, 0 exports                      |
-| Maintainability index      | 90.8 (good)                             |
-| Avg cyclomatic complexity  | 1.4                                     |
-| P90 cyclomatic complexity  | 2                                       |
-| Production duplication     | 11 lines (1 internal clone group)       |
-| Test duplication           | 42 clone groups, 661 lines              |
-| Fallow refactoring targets | 0                                       |
+| Metric                     | Value                                        |
+| -------------------------- | -------------------------------------------- |
+| Health score               | 78/100 (B)                                   |
+| Total LOC                  | 7,751 (62 files, end of Phase 17)            |
+| Dead code                  | 0 files, 0 exports                           |
+| Maintainability index      | 90.8 (good)                                  |
+| Avg cyclomatic complexity  | 1.4                                          |
+| P90 cyclomatic complexity  | 2                                            |
+| Production duplication     | 11 lines (1 internal clone group)            |
+| Test duplication           | 28 clone groups, 503 lines (end of Phase 17) |
+| Fallow refactoring targets | 0                                            |
 
 ### Dependency bag inventory
 
@@ -877,191 +879,163 @@ 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 — core consolidation)
+## Phase 17 (complete)
+
+Phase 17 consolidated the core's remaining structural debt before the UI reconsideration (Phase 18).
+The `Subagent` record/executor duality was resolved by extracting `SubagentState` (status, result, timestamps, metrics) into a private owned value object and making `SubagentExecution` a mandatory constructor collaborator — eliminating ~20 optional fields and the two "not configured for execution" runtime throws.
+The concurrency queue was replaced with a thunk-based `ConcurrencyLimiter` that knows nothing about agents or IDs.
+Run collaborators (`RunListeners`, `WorkspaceBracket`) were extracted from the 455-LOC `Subagent` class.
+The inline `SubagentManagerObserver` literal was promoted to `SubagentEventsObserver`, making its three concerns (event emission, record persistence, notification dispatch) unit-testable in isolation.
+Widget delegation and the post-construction `runtime.widget =` write were removed from `SubagentRuntime` by dissolving the notification→widget cycle via `AgentWidget.seedFinishedAgents`.
+Lifecycle, UI/tools, and cross-package test fixture clones were consolidated.
+`loadLayeredSettings<T>` was extracted to `src/layered-settings.ts` and published via the `@gotgenes/pi-subagents/settings` subpath export, eliminating the 23-line production clone with `pi-subagents-worktrees`.
+All nine steps are closed: [#381], [#373], [#374], [#375], [#376], [#377], [#378], [#379], [#380].
+[#412] unified the overlapping session-mock builders identified during Step 7.
+[#415] migrated `pi-subagents-worktrees` to `loadLayeredSettings` after the Step 9 published release.
+See [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md) for the full findings, step outcomes, dependency diagram, and tracks.
+
+## Phase 18 Reconsider UI from first principles
+
+After 17 phases the core is in very good shape: health 78/100 (B), zero dead code, zero fallow refactoring targets, average cyclomatic 1.4.
+The one structural debt that remains is not spread thin across the core — it is concentrated in a single place: the UI's live-streaming state (the "activity tier") is woven into the core's runtime, spawn tools, the LLM-facing `subagent` tool, and the notification path.
+This is the entanglement the [first-principles refinement](#first-principles-refinement-and-the-deeper-target) predicted — "the activity/metrics push tier is provisional; its only reactive consumer is the inherited widget" — observed in the code.
+Disentangling it is what lets the core reach a great state, and it is the prerequisite to any "reconsider the UI" decision: today the UI cannot be a clean consumer because the core does its streaming bookkeeping for it.
+
+### Findings
+
+Six findings tell one story — the activity tier has metastasized out of the UI and into the core.
+
+1. **UI state lives on the core runtime.**
+   `SubagentRuntime.agentActivity: Map<string, AgentActivityTracker>` puts a UI streaming-state map on the core composition root.
+   `SubagentRuntime` owns session-scoped lifecycle state; `AgentActivityTracker` (active tools, response text, turn count) is pure rendering state the core never reads.
+   Category C (coupling).
+2. **Core spawn tools wire UI streaming.**
+   `foreground-runner.ts` and `background-spawner.ts` construct `AgentActivityTracker`, call `subscribeUIObserver` (a second session subscription parallel to the core's own `record-observer`), call `setSession`, and populate or delete the activity map and drive the widget (`ensureTimer`, `update`, `markFinished`).
+   Their own doc comments list "AgentActivityTracker creation, UI observer subscription" as responsibilities.
+   Category C (mixed responsibility, parameter relay).
+3. **The LLM-facing tool depends on the widget.**
+   `AgentTool` takes a 4-method `widget` dependency plus `runtime.agentActivity` and calls `this.widget.setUICtx(ctx.ui)`.
+   Every `AgentTool` unit test must stub the widget and the activity map (`createToolDeps`), although the tool's real concern is dispatch — testability friction marking a domain seam.
+   Category C/D.
+4. **Two parallel observers split the run-metric domain.**
+   Each child session gets two subscriptions: `record-observer` accumulates `SubagentState` (tool uses, usage, compactions) and `ui-observer` accumulates `AgentActivityTracker` (active tools, response text, turn count).
+   `turnCount` is a genuine run metric that lives only in the UI tracker, so `notification.ts` and the foreground result text reach into the tracker to recover it.
+   Category C (anemic split, duplication).
+5. **A core observation concern reaches into UI state.**
+   `NotificationManager` holds the activity map and reads `turnCount`/`maxTurns` from it to build notification details, and deletes entries from it.
+   Category C (Law of Demeter).
+6. **The public event contract is both vacant and incomplete.**
+   `SUBAGENT_EVENTS.ACTIVITY = "subagents:activity"` is declared in the service surface and the doc's lifecycle-events table but is never emitted anywhere — a vacant hook the doc's own "no vacant hooks" rule forbids.
+   Meanwhile three emitted channels (`subagents:failed`, `subagents:compacted`, `subagents:created`) are absent from the constant map.
+   Category A/E.
 
-Phase 17 consolidates the core's remaining structural debt before the UI reconsideration (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.
-
-Phase 17 is the consolidation slice of the [first-principles refinement](#first-principles-refinement-the-deeper-target), not the full domain split.
-It lands the first cut of the lifecycle-state domain (Step 2's `SubagentState`) plus the wiring, queue, and duplication cleanups.
-The fuller four-domain split — metrics as a projection, result delivery as its own domain, the hook/broadcast reclassification, and the push/pull (DIP) inversion — is recorded in the refinement and sequenced into later phases.
-
-### 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)               | 8,356 (61 files, landed Phase 17 Step 5)      |
-| 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.
-   This duality is the two most visible of four domains fused into `Subagent`; Phase 17 resolves it (Step 2) and defers the remaining split (metrics, result delivery) to a later phase per the [first-principles refinement](#first-principles-refinement-the-deeper-target).
-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/`.
+### Health metrics
 
-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).
+| Metric                                   | Value                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| Health score                             | 78/100 (B)                                                         |
+| Source LOC                               | 7,751 (62 files)                                                   |
+| Dead code                                | 0 files, 0 exports                                                 |
+| Maintainability index                    | 90.9 (good)                                                        |
+| Avg cyclomatic complexity                | 1.4                                                                |
+| P90 cyclomatic complexity                | 2                                                                  |
+| Fallow refactoring targets               | 0                                                                  |
+| Production duplication                   | 11 lines (1 internal clone group in `agent-config-editor.ts`)      |
+| Test duplication                         | 28 clone groups, 503 lines                                         |
+| Activity-tier modules slated for removal | `ui-observer.ts` (61) + `agent-activity-tracker.ts` (84) = 145 LOC |
 
 ### 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    | Extract `SubagentState`; make `Subagent` execution deps mandatory                    | 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]) ✅ Complete
-
-- 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.start())` — `start()` owns the abort-while-queued status guard and stores the promise internally; foreground and `bypassQueue` runs invoke `record.start()` 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 — Extract `SubagentState`; make `Subagent` execution deps mandatory ([#373]) ✅ Complete
-
-- Targets: `src/lifecycle/subagent.ts` (state fields, transition/accumulation methods, constructor, `run()` guards), `src/lifecycle/subagent-manager.ts` (`spawn`), `test/helpers/make-subagent.ts`, `test/lifecycle/subagent.test.ts`, `test/observation/record-observer.test.ts`.
-- Smell: Category B (god interface — ~20 fields) and Category D (constructibility: "optional for tests" fields with compensating runtime throws).
-  The record/executor duality is the two most visible of the four conflated domains (see [First-principles refinement](#first-principles-refinement-the-deeper-target)).
-- Change: extract the passive-record state — status, result, error, timestamps, and the stats (toolUses, lifetimeUsage, compactionCount) — into a `SubagentState` value object that owns the transition and accumulation methods.
-  `Subagent` holds one privately; its existing getters and `markX`/`incrementX`/`addUsage` methods become one-line delegations, so the ~40 read sites and the mutation callers are unchanged.
-  This is not reach-through: `SubagentState` is a private owned value, not a foreign collaborator (contrast [#277], which removed reach-through to the raw SDK session).
-  With the readable state extracted, the remaining execution inputs (snapshot, prompt, model, maxTurns, thinkingLevel, parentSession, signal, createSubagentSession, observer, getRunConfig, getWorkspaceProvider, baseCwd) collapse into a single **mandatory** `SubagentExecution` collaborator: production always supplies it (the one `spawn()` site), the passive-record construction moves entirely into `make-subagent.ts`, and `run()`'s two "not configured" throws vanish by construction.
-- Outcome: state-machine and observer tests target `SubagentState` directly (no stub execution); `Subagent` is construct-complete with no optional execution fields and no runtime throws (grep-verifiable: no "not configured for execution" in `subagent.ts`); the record-vs-executor duality is resolved, not type-encoded.
-- Scope boundary: stats stay on `SubagentState` for now.
-  Hoisting **metrics** into a projection over the child session's event stream and extracting **result delivery** (`notification`/`resultConsumed`) into its own domain are the remaining two of the four domains, deferred to a later phase per the refinement.
-- Landed: `SubagentState` (`src/lifecycle/subagent-state.ts`) owns status/result/error/timestamps/stats and the transition/accumulation methods; `Subagent` delegates getters and `markX`/`incrementX`/`addUsage` to it.
-  `subscribeSubagentObserver` targets `SubagentState`, so observer and state-machine tests no longer stub execution.
-  `SubagentExecution` is a mandatory constructor collaborator (production wires it in the single `spawn()` site; passive records build via `make-subagent.ts`), and the two `run()` throws are gone.
-
-#### Step 3 — Encapsulate run start and notification attachment on Subagent ([#374]) ✅ Complete
-
-- 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.test.ts`, `test/lifecycle/subagent.test.ts`.
-- Smell: Category C — output arguments: external writes to `record.promise` (2 production sites in `subagent-manager.ts`, 4 test sites) and `record.notification` (7 test sites; the production path was resolved in Step 2 — the constructor creates `notification` from `execution.parentSession?.toolCallId`, so Step 3's remaining work is making the field read-only and updating tests to supply it via `parentSession`).
-- 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 (private `_promise`/`_notification` fields backed by public getters); the abort-while-queued status guard folds into `start()`, removing the inline check from the limiter callback; tests use `createTestSubagent({ toolCallId })` or spawn with `parentSession.toolCallId` instead of post-construction assignment.
-- Outcome: zero external writes to `Subagent` fields outside its own methods (grep-verifiable: `\.promise =` and `\.notification =` appear only inside `subagent.ts`); 6 new unit tests for `start()` behaviour; test count +6 (975 → 981).
-- Landed: `Subagent.start()` (immediate path) and `Subagent.scheduleVia(schedule)` (queued path) own the promise and the shared `guardedRun()` status guard; `SubagentManager.spawn()` calls one or the other; `TestSubagentOptions.toolCallId` wires notification state via the constructor path.
-- Correction (post-merge): the first cut used `void this.limiter.schedule(() => record.start())`, which left a queued agent's `promise` unset until its slot opened — silently regressing Step 1's "every spawned agent has a `promise` at spawn" invariant.
-  Fixed by inverting control: `scheduleVia` captures the limiter promise eagerly inside the agent (no external `.promise =` write), restoring the invariant.
-  Lesson: a step's acceptance criteria must include the cross-step invariants it could regress, not only its own grep-verifiable outcome.
-
-#### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375]) ✅ Complete
-
-- Targets: `src/lifecycle/subagent.ts` (455 LOC after Step 2 extracted SubagentState — still the largest source file).
-- 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 (`wireSignal`/`attachObserver`/`release`), and a `WorkspaceBracket` collaborator owning prepare/dispose-with-addendum, centralising the dispose logic.
-- Outcome: `subagent.ts` ≤ 450 LOC; workspace disposal logic in exactly one place; listener handles no longer raw nullable fields.
-- Landed: `RunListeners` (`src/lifecycle/run-listeners.ts`) owns the signal-detach and observer-unsub handles with a single `release()` call; `WorkspaceBracket` (`src/lifecycle/workspace-bracket.ts`) owns prepare-at-run-start and dispose-with-addendum — `completeRun` and `failRun` call `workspaceBracket.dispose(outcome)` and receive the addendum string (or `""`) without reaching through to the workspace object directly.
-  `Subagent.wireSignal`, `attachObserver`, and `releaseListeners` are removed.
-  `subagent.ts`: 488 → 448 LOC.
-  Test count: 982 → 994 (+12: 7 RunListeners + 13 WorkspaceBracket − 8 redundant Subagent listener tests).
-
-#### Step 5 — Extract the manager observer from index.ts into a class ([#376]) ✅ Complete
-
-- 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.
-- Landed: `src/observation/subagent-events-observer.ts` (new, 97 LOC); `index.ts` 226 → 177 lines; 60 → 61 source files; 994 → 1009 tests (+15 covering all four observer methods).
-
-#### Step 6 — Split widget delegation out of SubagentRuntime ([#377]) ✅ Complete
-
-- Targets: `src/runtime.ts`, `src/tools/agent-tool.ts` (`AgentToolRuntime`), `src/handlers/tool-start.ts` (`ToolStartRuntime`), `src/observation/notification.ts` (`NotificationManager` constructor), `src/ui/agent-widget.ts`, `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.
-- Constraint discovered in planning: "pass the handle directly to the consumers" is infeasible for `NotificationManager`, which is a _transitive dependency_ of the widget (`NotificationManager → widget → manager → observer → NotificationManager`).
-  The `runtime.widget` lazy field exists to break exactly this cycle; removing it forces the one late seam to move, and the operator's principles (no setters, instantiate ready-to-work) rule out relocating it to a setter or forward-ref `let`.
-- Change (tidy-first): first dissolve the cycle by giving `AgentWidget.update()` self-seeding of `finishedTurnAge` for finished agents it observes via `listAgents()`, then drop the `markFinished`/`updateWidget` callbacks from `NotificationManager` (it keeps `agentActivity.delete` + nudge scheduling).
-  With the cycle gone, the widget is constructed as a `const` after the manager and injected directly into `AgentTool` and `ToolStartHandler`; the `widget` field, the five relay methods, and the post-construction write delete cleanly, and `AgentToolRuntime` narrows to its context-query slice.
-- Outcome: `SubagentRuntime` has zero widget knowledge; no post-construction field writes in `index.ts`; the construction graph is a cycle-free DAG (`notifications → observer → manager → widget → {AgentTool, ToolStartHandler}`).
-- Landed: `AgentWidget.seedFinishedAgents` owns completion detection; `NotificationManager` has no widget dependency (2-arg constructor); `AgentToolWidget` (in `agent-tool.ts`) and `ToolStartWidget` (in `tool-start.ts`) are narrow per-consumer interfaces the real widget satisfies structurally; tool fixtures stub a `widget` separate from the narrowed `runtime` mock.
-  Behavior-preserving: the widget timer runs through every background completion, so self-seeding lands ≤80ms later within the same turn (linger is turn-based).
-  Test count: 1009 → 1005 (+3 widget self-seed tests, −7 removed relay/field tests).
-
-#### 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-limiter.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
+The spine (Steps 1–5) removes the activity-tier entanglement, leaving the core a pure orchestrator whose run state lives in one place and whose UI is a reactive consumer of broadcast events plus discrete queries.
+Steps 6–7 are independent hygiene.
+Step 8 is the user-driven UI reconsideration the disentangled core finally makes possible — a decision about the UI's distribution once it is substitutable, not optional.
+
+The deeper target in the [first-principles refinement](#first-principles-refinement-and-the-deeper-target) — metrics as a pure observer projection rather than mutable fields — is deliberately **not** forced here.
+Folding the live activity onto the record (the single owner of run state, consistent with Phase 17's `SubagentState`) removes the duplication without inventing the asynchronous-observation seam the `improvement-discovery` skill warns is essential, not structural.
+
+1. **Fold run metrics and live activity onto the core record (pure addition).**
+   ([#420]) Target: `lifecycle/subagent-state.ts`, `observation/record-observer.ts`, `lifecycle/subagent.ts`.
+   Extend the single owned run-state value object with `turnCount`, active tools, and response text; have the already-subscribed `record-observer` handle `turn_end`, `tool_execution_start`, `message_start`, `message_update`; expose read-only `turnCount`/`maxTurns`/`activeTools`/`responseText` getters on `Subagent`.
+   `AgentActivityTracker` still exists; nothing reads the new getters yet (tidy-first).
+   Smell: Category C. Outcome: `Subagent` is the single home for all run state; getters available for migration.
+2. **Migrate every activity reader to the record getters.**
+   ([#421]) Target: `ui/widget-renderer.ts`, `ui/conversation-viewer.ts`, `ui/agent-menu.ts`, `tools/foreground-runner.ts`, `observation/notification.ts`.
+   Switch each reader from `AgentActivityTracker` to the record getters added in Step 1 (widget-renderer reads activity off `listAgents()`; viewer/menu drop the `activity` param; notification reads `turnCount`/`maxTurns` off the record).
+   Smell: Category C (Law of Demeter).
+   Outcome: no consumer references `AgentActivityTracker`.
+3. **Delete `AgentActivityTracker` and `ui-observer`; drop the activity map from the runtime and spawn tools.**
+   ([#422]) Target: `ui/agent-activity-tracker.ts` (delete), `ui/ui-observer.ts` (delete), `runtime.ts`, `tools/foreground-runner.ts`, `tools/background-spawner.ts`.
+   The spawn tools stop constructing trackers, subscribing, and populating maps; `SubagentRuntime.agentActivity` is removed.
+   Smell: Category A + C. Outcome: −145 LOC, one session subscription per child, runtime holds zero UI state.
+4. **Make the widget self-drive from lifecycle events.**
+   ([#423]) Target: `ui/agent-widget.ts`, `lifecycle/subagent-manager.ts` (observer), `index.ts`.
+   The widget starts/stops its timer in response to started/created/completed notifications instead of tool calls; spawn tools no longer call `ensureTimer`/`update`/`markFinished`.
+   Smell: Category C (coupling direction).
+   Outcome: the widget is a reactive consumer; no inbound calls from core spawn tools.
+5. **Drop the widget and activity-map dependencies from the `subagent` tool.**
+   ([#424]) Target: `tools/agent-tool.ts`, `test/helpers/make-deps.ts`.
+   `AgentTool` loses its `widget` and `agentActivity` constructor params (UICtx capture stays in `ToolStartHandler`); `createToolDeps` sheds the widget and map stubs.
+   Smell: Category C/D.
+   Outcome: the LLM tool depends only on manager/runtime/settings/registry; fixture drops 2 fields.
+6. **Reconcile the public event contract.**
+   ([#425]) Target: `service/service.ts`, this document's lifecycle-events table.
+   Remove the vacant `ACTIVITY` channel (or emit a real broadcast for it) and add the emitted `failed`/`compacted`/`created` channels so declared constants match emitted events.
+   Smell: Category A/E.
+   Outcome: declared channels equal emitted channels; no vacant hook.
+7. **Consolidate residual test clone families.**
+   ([#426]) Target: `test/settings.test.ts` + `test/layered-settings.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/ui/agent-config-editor.test.ts`.
+   Extract shared fixtures for the clone families fallow reports that the spine does not already rewrite.
+   Smell: Category D. Outcome: test clone groups drop below 15.
+8. **Reconsider the UI direction (first-principles ADR).**
+   ([#427]) Target: `docs/decisions/`, `ui/`.
+   The spine already made the UI _substitutable_; this step decides its _distribution_, not whether the experiment is possible.
+   The goal is **substitutable, not optional**: a human needs some surface, but the specific UI is replaceable — the way Pi ships a default TUI built on the same public API any extension targets.
+   The disentangled core stays byte-for-byte identical whether or not a given UI consumer is installed (the composition test), so a replacement UI is a downstream concern even though _some_ UI is not.
+   Unlike the worktrees provider seam (generative, rationed — one provider the core consults), the UI is an observational consumer (unlimited, the core never waits on it) reading the broadcast-plus-query surface, which is why packaging it is the secondary question and decoupling it was the real win.
+   Two standing concerns are the evidence this decision weighs and the better boundaries the reconsideration is meant to surface:
+   - **Truncated transcript.**
+     The conversation viewer shows a truncated view, yet `Subagent.messages` already exposes the full history and the core already persists each child as a standard Pi session JSONL (`outputFile`) — the limit is the bespoke overlay's rendering, not data access.
+   - **Foreground widget redundancy.**
+     In foreground the tool's inline `onUpdate` stream already shows progress, so the above-editor widget duplicates it; the widget earns its keep only for background agents — a per-mode judgment the fused UI cannot vary.
+   Candidate redesign to record: replace the bespoke overlay with "open the child session in the same viewer Pi uses for any session," following the recursive-Pi insight and the already-persisted session file.
+   Judge the widget, conversation viewer, and `/agents` menu per component — keep, shrink, extract to `@gotgenes/pi-subagents-ui`, or remove — and capture the decision in an ADR that gateways Phase 19.
+   Smell: Category E (organization / boundary).
+   Outcome: a recorded per-component decision motivated by the two concerns; the inherited UI is substitutable and no longer preserved by default.
+
+### Step dependency diagram
 
 ```mermaid
 flowchart TB
-    S1["Step 1 (#381)<br/>ConcurrencyLimiter replacement"]
-    S2["Step 2 (#373)<br/>SubagentState extraction"]
-    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
+    S1["1 — Fold metrics + activity onto record (#420)"]
+    S2["2 — Migrate readers to record getters (#421)"]
+    S3["3 — Delete tracker + ui-observer, drop activity map (#422)"]
+    S4["4 — Widget self-drives on events (#423)"]
+    S5["5 — Drop widget dep from subagent tool (#424)"]
+    S6["6 — Reconcile public event contract (#425)"]
+    S7["7 — Consolidate test clone families (#426)"]
+    S8["8 — Reconsider UI direction, ADR (#427)"]
+
+    S1 --> S2 --> S3 --> S4 --> S5 --> S8
+    S6
+    S7
 ```
 
-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                                                       |
+### Parallel tracks
 
-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.
+- **Track A — Disentangle the activity tier (spine):** Steps 1, 2, 3.
+  Strictly ordered; each is a safe lift-and-shift over the previous.
+- **Track B — Decouple widget and tool wiring:** Steps 4, 5.
+  Begins once the activity map is gone (Step 3).
+- **Track C — Public-contract hygiene:** Step 6.
+  Independent; can land any time.
+- **Track D — Test consolidation:** Step 7.
+  Independent; can land any time.
+- **Track E — UI reconsideration:** Step 8.
+  Gated on the spine and Track B (the UI must be a clean consumer first).
 
 ## Refactoring history
 
-Phases 1–5, 7–16 are complete.
+Phases 1–5, 7–17 are complete.
 Phase 6 (UI extraction to a separate package) is deferred → Phase 18.
 Detailed records are preserved in per-phase history files:
 
@@ -1083,29 +1057,31 @@ 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    | Core consolidation                                  | Planned             | —                                                                                    |
-| 18    | Reconsider UI (first principles)                    | Planned             | —                                                                                    |
+| 17    | Core consolidation                                  | Complete            | [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md)             |
+| 18    | Reconsider UI (first principles)                    | Proposed            | this document, [Phase 18](#phase-18-reconsider-ui-from-first-principles)             |
 
 ### Structural refactoring issues
 
-| Phase                | Issue                                                      | Summary                                                                                                                                                    |
-| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Foundation           | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                                                       |
-| Core decomposition   | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                                                      |
-| Interface polish     | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                                                |
-| Features             | #61                                                        | JSONL session transcripts                                                                                                                                  |
-| AgentManager         | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                                              |
-| Encapsulation        | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping                             |
-| Testability          | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                          |
-| Observation/ctx      | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                              |
-| 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                                                   |
-| Phase 14             | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                                 |
-| Phase 15             | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                                 |
-| Phase 16             | #261, #262, #263, #264, #265                               | Lifecycle events (retire permission-bridge), WorkspaceProvider seam, extract worktrees package, remove isolated, born-complete execution / dissolve runner |
-| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above ([ADR-0002])                                                                    |
+| Phase                | Issue                                                      | Summary                                                                                                                                                                                        |
+| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foundation           | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                                                                                           |
+| Core decomposition   | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                                                                                          |
+| Interface polish     | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                                                                                    |
+| Features             | #61                                                        | JSONL session transcripts                                                                                                                                                                      |
+| AgentManager         | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                                                                                  |
+| Encapsulation        | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping                                                                 |
+| Testability          | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                                                              |
+| Observation/ctx      | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                                                                  |
+| 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                                                                                       |
+| Phase 14             | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                                                                     |
+| Phase 15             | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                                                                     |
+| Phase 16             | #261, #262, #263, #264, #265                               | Lifecycle events (retire permission-bridge), WorkspaceProvider seam, extract worktrees package, remove isolated, born-complete execution / dissolve runner                                     |
+| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above ([ADR-0002])                                                                                                        |
+| Phase 17             | #381, #373, #374, #375, #376, #377, #378, #379, #380       | ConcurrencyLimiter, SubagentState, run-start encapsulation, run collaborators, events observer, widget decoupling, lifecycle test fixtures, UI/tools test fixtures, settings-loader extraction |
+| Phase 17 (follow-on) | #412, #415                                                 | Session-mock builder unification, worktrees settings-helper migration                                                                                                                          |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -1159,4 +1135,14 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#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
+[#412]: https://github.com/gotgenes/pi-packages/issues/412
+[#415]: https://github.com/gotgenes/pi-packages/issues/415
+[#420]: https://github.com/gotgenes/pi-packages/issues/420
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424
+[#425]: https://github.com/gotgenes/pi-packages/issues/425
+[#426]: https://github.com/gotgenes/pi-packages/issues/426
+[#427]: https://github.com/gotgenes/pi-packages/issues/427
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md