@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/architecture/architecture.md

@@ -114,13 +114,13 @@ classDiagram
         +toolUses: number
         +lifetimeUsage: LifetimeUsage
         +subagentSession?: SubagentSession
-        +notification?: NotificationState
+        +toolCallId?: string
         +markRunning() delegates
         +markCompleted() delegates
         +run()
         +resume(prompt, signal)
         +abort(): boolean
-        +steer(message): Promise~boolean~
+        +steer(message): Promise~SteerOutcome~
         +isSessionReady(): boolean
         +getConversation(): string | undefined
         +getContextPercent(): number | null
@@ -318,8 +318,7 @@ src/
 │
 ├── observation/                    progress tracking and notification
 │   ├── record-observer.ts          session-event stats observer
-│   ├── notification.ts             completion nudges
-│   ├── notification-state.ts       per-agent notification tracking
+│   ├── notification.ts             completion nudges + per-agent consumed-result tracking
 │   ├── renderer.ts                 notification TUI component
 │   ├── composite-subagent-observer.ts fans manager notifications out to multiple observers
 │   └── subagent-events-observer.ts manager lifecycle observer (event emission + persistence + notification)
@@ -335,6 +334,7 @@ src/
 │   ├── foreground-runner.ts        foreground execution loop
 │   ├── background-spawner.ts       background spawn setup
 │   ├── get-result-tool.ts          get_subagent_result tool
+│   ├── get-result-report.ts        pure get_subagent_result report formatter
 │   ├── steer-tool.ts               steer_subagent tool
 │   └── helpers.ts                  shared tool utilities
 │
@@ -645,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                  | 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                                            |
+| Metric                     | Value                       |
+| -------------------------- | --------------------------- |
+| Health score               | 78/100 (B), end of Phase 19 |
+| Total LOC                  | 7,068 (57 files)            |
+| Dead code                  | 0 files, 0 exports          |
+| Maintainability index      | 91.0 (good)                 |
+| Avg cyclomatic complexity  | 1.4                         |
+| P90 cyclomatic complexity  | 2                           |
+| Production duplication     | 0 lines                     |
+| Test duplication           | 9 clone groups, 81 lines    |
+| Fallow refactoring targets | 0                           |
 
 ### Dependency bag inventory
 
@@ -674,8 +674,6 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `SubagentSessionIO`           | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1)       | create-subagent-session                           | ✓ done    |
 | `CreateSessionOptions`        | 9                                                            | create-subagent-session (SDK bridge)              | Low (SDK) |
 | `AgentToolDeps`               | 8                                                            | agent-tool                                        | ✓ done    |
-| `AgentMenuDeps`               | 8                                                            | agent-menu                                        | ✓ done    |
-| `ConversationViewerOptions`   | 8                                                            | conversation-viewer                               | Low       |
 | `SubagentInit`                | 5 (id, type, description, invocation, execution, state)      | subagent (one production site)                    | ✓ done    |
 | `SubagentExecution`           | 12 (4 mandatory: factory, snapshot, prompt, baseCwd)         | subagent (mandatory collaborator)                 | ✓ done    |
 
@@ -689,23 +687,22 @@ No functions remain above the critical threshold — all hotspots resolved in Ph
 
 Files with highest commit frequency × complexity:
 
-| Score | File                        | Commits | Trend          |
-| ----- | --------------------------- | ------- | -------------- |
-| 65.0  | `index.ts`                  | 128     | ▲ accelerating |
-| 9.1   | `ui/agent-widget.ts`        | 13      | ▼ cooling      |
-| 8.4   | `ui/conversation-viewer.ts` | 11      | ─ stable       |
-| 6.4   | `runtime.ts`                | 12      | ─ stable       |
-| 3.3   | `settings.ts`               | 4       | ─ stable       |
-| 2.9   | `handlers/lifecycle.ts`     | 11      | ─ stable       |
+| Score | File                          | Commits | Trend          |
+| ----- | ----------------------------- | ------- | -------------- |
+| 27.1  | `index.ts`                    | 109     | ▼ cooling      |
+| 9.6   | `tools/agent-tool.ts`         | 56      | ▼ cooling      |
+| 8.8   | `ui/agent-widget.ts`          | 22      | ▼ cooling      |
+| 7.3   | `tools/foreground-runner.ts`  | 22      | ▼ cooling      |
+| 6.6   | `service/service-adapter.ts`  | 15      | ▲ accelerating |
+| 6.3   | `config/custom-agents.ts`     | 13      | ▼ cooling      |
 
-Most files have cooled to stable after 13 phases of structural work.
-`index.ts` remains the sole accelerating hotspot — expected as the wiring entry point for each refactoring phase.
+`index.ts` remains the top churn hotspot but has cooled after the Phase 19 terminal cut removed its four `/agents`-wiring blocks; `service-adapter.ts` is now the sole accelerating file.
 
 ### Production duplication
 
 The prior clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
 The 20-line clone group between `agent-config-editor.ts` and `agent-creation-wizard.ts` was resolved in #217 — extracted into `ui/agent-file-writer.ts` (`writeAgentFile`).
-One 11-line internal clone group remains within `agent-config-editor.ts` (lines 135–145 / 173–183).
+The final 11-line internal clone group within `agent-config-editor.ts` was eliminated in Phase 19 Step 6 ([#441]) when the file itself was deleted; production duplication is 0 lines.
 
 ### Session encapsulation debt (Law of Demeter) — resolved by [#277] ✔️
 
@@ -905,262 +902,214 @@ Source LOC decreased from 7,751 (62 files) to 7,650 (61 files); tests grew from
 All eight steps are closed: [#420], [#421], [#422], [#423], [#424], [#425], [#426], [#427].
 See [phase-18-reconsider-ui.md](history/phase-18-reconsider-ui.md) for the full findings, step outcomes, dependency diagram, and tracks.
 
-## Phase 19 (proposed)
+## Phase 19 (complete)
 
-Phase 19 implements the per-component UI decisions recorded in [ADR-0004]: shrink the widget to background-only, replace the bespoke conversation viewer with native session navigation, dissolve the monolithic `/agents` menu, and keep the surviving UI in-core.
+Phase 19 implemented the per-component UI decisions recorded in [ADR-0004]: it shrank the widget to background-only agents, replaced the bespoke conversation viewer with native session navigation dual-sourced by liveness (live record or persisted-file snapshot) and rendered through Pi's own per-entry TUI components, extracted subagent settings to a focused `/subagents-settings` command, and dissolved the monolithic `/agents` menu in a two-commit terminal cut (hub first, then the orphaned agent-definition-management subtree).
+Production duplication dropped to 0 lines; test clone groups dropped from 16 to 9 (target: ≤ 10); source shrank from 7,650 LOC (61 files) to 7,068 LOC (57 files).
+All nine steps are closed: [#446], [#447], [#444], [#445], [#462], [#463], [#442], [#441], [#443].
+A follow-on issue, [#470] (README staleness after the terminal cut), was filed and closed independently.
+See [phase-19-implement-ui-decisions.md](history/phase-19-implement-ui-decisions.md) for the full findings, step outcomes, dependency diagram, and tracks.
 
-The sequencing follows Kent Beck's "make the change easy, then make the easy change."
-The end state deletes `agent-menu.ts` — the god-command that bundles four unrelated jobs — and everything reachable only from it.
-Rather than surgically mutate that doomed module (and the #1 churn hotspot `index.ts`) once per option, Phase 19 first stands up the replacement surfaces additively, then removes the now-orphaned subtree in a single terminal cut.
-This keeps every responsibility's old surface live until its replacement exists (ADR-0004's no-interim-regression invariant), turns the three replacement steps into genuinely parallel work (none touch `agent-menu.ts`), and reduces `index.ts` edits from four surgical removals to one deregistration.
+## Phase 20 improvement roadmap
 
-Seven numbered steps in three phases, plus two follow-ups (Steps 4a–4b) carved from the #445 slice:
+Phase 20 realizes the last un-extracted domain from the [first-principles refinement](#first-principles-refinement-and-the-deeper-target) — **result delivery** — and clears the residual boundary and complexity debt discovery surfaced around it.
 
-- **Phase A — stand up replacements (additive):** spike, settings command, background widget, native session navigation and its renderer/source follow-ups (Steps 1–4, 4a–4b).
-- **Phase B — dissolve `/agents` (terminal cut):** delete the orphaned subtree in two deletion commits, one per subtree (Steps 5–6).
-- **Phase C — test health:** consolidate the test clones that survive the cut (Step 7).
+Discovery findings (fallow + entry-point trace + test-constructibility audit, 2026-07-03):
 
-### Health metrics (Phase 18 → Phase 19 target)
+1. `NotificationState` (`toolCallId`, `resultConsumed`) still lives on `Subagent`; `get-result-tool` reaches through `record.notification?.markConsumed()` twice, always paired with `notifications.cancelNudge(id)` — the doc's own "homeless field" (result-delivery domain) plus a scattered two-step reset.
+2. Both `steer-tool` and `service-adapter` pre-check `status !== "running"` before calling `record.steer()` — ask-then-tell, contradicting the target's "tell by id, with outcomes" rule.
+3. Five file-level eslint-disable headers (`agent-tool` disables 6 rules; `spawn-config` and `agent-widget` 4 each; `model-resolver` 2; `index` 1) and `model: unknown`/`Model<any>`/`any` threading through 8 files mark the SDK type boundary as the largest remaining `any` surface.
+4. Three src functions carry HIGH CRAP scores (notification renderer arrow 79.4, `service-adapter.spawn` 71.3, `get-result-tool.execute` 63.6 — resolved by Step 2); `subagents-settings.handle` (13 cyclomatic, 24 cognitive) is three copy-pasted select→input→validate→apply branches; `service-adapter.ts` is the sole accelerating churn file.
+5. `createTestSubagent` is the most complex function in the workspace (19 cyclomatic, 25 cognitive) because `SubagentStateInit` accepts only transition fields, forcing mutation loops to seed metrics — a Category D "shared factory complexity" signal pointing at the production init surface.
+6. Test duplication sits at 9 in-package clone groups (81 lines), at the ≤ 10 target but with two consolidatable clone families.
 
-| Metric                 | Phase 18 (current)       | Phase 19 target      |
-| ---------------------- | ------------------------ | -------------------- |
-| Health score           | 78/100 (B)               | 83/100 (B+)          |
-| Source LOC             | 7,650 (61 files)         | ~6,780 (~55 files)   |
-| Production duplication | 11 lines (1 group)       | 0 lines              |
-| Test clone groups      | 16                       | ≤ 10                 |
-| Top churn hotspot      | `index.ts` (103 commits) | `index.ts` (cooling) |
+No finding scores ≥ 20 on the priority scale (Impact × (6 − Risk)); the phase is a should-fix band (10–15) consolidation.
+Directory organization is healthy (seven domain directories, six root files) — no reorg this phase.
 
-### ✅ Step 1 — Spike: resolve ADR-0004 entry criteria ([#446])
+### Health metrics (Phase 20)
 
-Smell: Category C (coupling boundary) — four open decisions block the session-navigation implementation.
-Target: `docs/decisions/0004-reconsider-ui-direction.md` addendum.
+| Metric                                           | Phase 19 (end)   | Phase 20 target        |
+| ------------------------------------------------ | ---------------- | ---------------------- |
+| Health score                                     | 78/100 (B)       | ≥ 78 (B)               |
+| Source LOC                                       | 7,068 (57 files) | ~7,050 (no net growth) |
+| `record.notification?.` reach-throughs           | 4 sites          | 0                      |
+| Steer status pre-checks outside `Subagent.steer` | 2 sites          | 0                      |
+| src functions with CRAP ≥ 60                     | 3                | 0                      |
+| File-level eslint-disable headers                | 5                | ≤ 2                    |
+| `createTestSubagent` cyclomatic                  | 19               | ≤ 8                    |
+| Test clone groups (in-package)                   | 9 (81 lines)     | ≤ 5 (≤ 40 lines)       |
 
-The four entry criteria from ADR-0004:
+### Steps
 
-1. **Root-continuity:** Does the root's in-flight turn survive `ctx.switchSession()` and a return gesture?
-2. **View-only vs interactive:** `switchSession` (full interactive takeover) or `loadEntriesFromFile` (read-only transcript built from JSONL)?
-3. **Parallel-agent navigation:** Operator gesture to select which of N background agents to view (from the widget, a command, or both).
-4. **Settings command name:** `/subagents-settings`, `/agents-settings`, or another form consistent with sibling packages?
+#### ✅ Step 1 — Extract result delivery from `Subagent` ([#535])
 
-Produce a minimal spike (observed test or PoC against a real session) that answers each question, then record the answers as an addendum to ADR-0004.
-No production source files change; the spike closes when the ADR addendum is merged.
+Smell: Category C (anemic domain / misplaced state, Law of Demeter, scattered resets) — the result-delivery domain named in the first-principles refinement is still fused into the execution record.
+Target files:
 
-Outcome: ADR-0004 updated with all four entry-criteria answers; Step 4 unblocked.
+- `src/lifecycle/subagent.ts` — drop `_notification` / `notification`; stop constructing `NotificationState` from `parentSession.toolCallId`.
+- `src/observation/notification.ts` — `NotificationManager` owns consumed-state keyed by agent id behind a single tell operation (e.g. `consume(id)`) that also cancels the pending nudge.
+- `src/observation/notification-state.ts` — dissolve into the manager or move wholly into the observation domain.
+- `src/observation/subagent-events-observer.ts`, `src/tools/get-result-tool.ts` — call the new delivery interface instead of reaching through the record.
 
-`Release: independent`
+The `toolCallId` needed by `formatTaskNotification` already travels on `execution.parentSession`; expose it without routing through a notification object.
+The pre-await consumption ordering (the "Bug 1" race tests in `test/lifecycle/subagent-manager.test.ts`) is a preserved invariant — consuming before awaiting must still suppress the completion nudge.
+
+Outcome: zero `record.notification?.` reach-throughs in `src/`; `Subagent` carries no notification field; delivery state lives in the observation domain.
 
-### ✅ Step 2 — Extract settings to a focused `/subagents-settings` command ([#447])
+Landed: `notification-state.ts` deleted; `Subagent.toolCallId` getter added over `execution.parentSession`; `NotificationManager` owns `consumed: Set<string>` behind one `consume(id)` tell that adds to the set and cancels the pending nudge atomically.
+Collapsing the old two-step reset (`markConsumed()` + `cancelNudge()`) into one atomic operation structurally eliminates the historical "Bug 1" race rather than just reordering it — `consume()` now suppresses the nudge regardless of whether it runs before or after the completion promise resolves, as long as it runs within the 200 ms hold window.
 
-Smell: Category E (naming/organization) — settings are buried inside the monolithic `/agents` command per ADR-0004 Decision C. This step is purely additive: it stands up the new surface without touching `agent-menu.ts`.
+`Release: batch "result-delivery"`
+
+#### ✅ Step 2 — Decompose `get-result-tool.execute` ([#536])
+
+Smell: Category B (oversized function) — 61 lines, 15 cyclomatic, CRAP 63.6; mixes wait/consume policy, stats formatting, and output assembly.
 Target files:
 
-- New `src/ui/subagents-settings.ts` — `SubagentsSettingsHandler` lifted from `AgentsMenuHandler.showSettings`, carrying its own narrow `SubagentsSettingsManager` interface (the three `apply*` methods and three readonly accessors only).
-- `src/index.ts` — register the new command (name confirmed by Step 1); pass `settings` directly.
-- New `test/ui/subagents-settings.test.ts` — unit tests for the extracted handler.
+- `src/tools/get-result-tool.ts` — extract a pure report formatter (status line, stats parts, body selection) alongside the existing `result-renderer.ts` pattern; consume via the Step 1 delivery interface.
+- `test/tools/get-result-tool.test.ts` — unit-test the pure formatter directly.
 
-`showSettings` depends only on `this.settings` (the self-contained `AgentMenuSettings` shape), so the extraction copies that logic into a new file with zero coupling to the wizard, editor, or viewer.
-The old in-menu Settings option keeps working until the terminal cut deletes `agent-menu.ts` wholesale — there is no surgical removal of `showSettings` or `AgentMenuSettings` from the doomed file.
+Outcome: `execute` ≤ 30 lines with cyclomatic < 10; off the fallow high-complexity list.
 
-Outcome: new `subagents-settings.ts` (~80 LOC) and focused command registered; `agent-menu.ts` untouched.
+Landed: `src/tools/get-result-report.ts` added — `AgentReport` value object plus `renderStatsParts` / `renderReportBody` / `formatAgentReport` pure functions, unit-tested directly in `test/tools/get-result-report.test.ts`.
+`GetResultTool.execute` now owns only record lookup and the wait/consume policy (13 lines), delegating report assembly to a private `buildReport` + `formatAgentReport`; output is byte-identical.
+`get-result-tool.execute` is off the HIGH-CRAP list (3 → 2 remaining: `service-adapter.spawn`, the notification renderer arrow).
 
-`Release: independent`
+`Release: batch "result-delivery"`
 
-### ✅ Step 3 — Shrink widget to background agents only ([#444])
+#### ✅ Step 3 — `Subagent.steer` returns an outcome ([#537])
 
-Smell: Category C (coupling) — the widget shows all agents including foreground ones, duplicating the `subagent` tool's inline `onUpdate` stream for foreground runs.
+Smell: Category C (ask-then-tell) — coordinators pre-check status before telling.
 Target files:
 
-- `src/ui/agent-widget.ts` — funnel both `manager.listAgents()` call sites (`update()` and `renderWidget()`) through a single private accessor, then flip that accessor to background-only via `record.invocation?.runInBackground === true`.
-- `src/ui/widget-renderer.ts` — verify no foreground-specific rendering path survives.
-- `test/ui/agent-widget.test.ts` — add background-only filtering tests; update assertions.
+- `src/lifecycle/subagent.ts` — `steer` owns the non-running rejection and returns a discriminated outcome (`delivered` / `buffered` / `rejected` with the observed status).
+- `src/tools/steer-tool.ts`, `src/service/service-adapter.ts` — drop the status pre-checks and switch on the outcome; the adapter maps the outcome to the public `SubagentsService.steer` boolean, so the published contract is unchanged.
 
-The widget calls `listAgents()` at two sites today — `update()` (feeding `seedFinishedAgents`, `assembleWidgetState`, and `clearWidget`) and `renderWidget()` (the tree map).
-Filtering at only one site leaves the other rendering foreground agents, so the enabling move is to route both through one accessor and apply the predicate once at the source.
-`Subagent.invocation.runInBackground` is the reliable signal: set by `spawn-config.ts` → `AgentInvocation.runInBackground` → stored on `Subagent.invocation`.
-ADR-0004 Decision A: foreground runs suppress the widget; the inline `onUpdate` stream is authoritative there.
+Outcome: zero steer status pre-checks outside `Subagent.steer`; `steer-tool.execute` cyclomatic drops below 10.
 
-Outcome: widget shows only background agents; foreground/widget duplication eliminated; the background predicate lives at a single funnel.
+Landed: `Subagent.steer` returns a discriminated `SteerOutcome` (`delivered` / `buffered` / `rejected` with the observed status) and owns the non-running rejection as its first guard; `SteerOutcome` is exported from `subagent.ts` and re-exported via `types.ts`.
+`SteerTool.execute` and `SubagentsServiceAdapter.steer` dropped their `status !== "running"` pre-checks and switch on the outcome — the adapter maps `outcome.kind !== "rejected"` to the unchanged public boolean, and the tool's delivered-path stats moved into a private `renderDelivered` helper.
+Zero steer status pre-checks remain outside `Subagent.steer`.
 
 `Release: independent`
 
-### ✅ Step 4 — Implement native session navigation ([#445])
+#### ✅ Step 4 — Type the model boundary ([#538])
 
-Smell: Category C (coupling) — the bespoke `ConversationViewer` re-implements session-transcript rendering when Pi's own machinery targets the already-persisted child session JSONL.
-This step adds the new surface alongside the existing viewer; it does not touch `agent-menu.ts`.
+Smell: Category C (platform type threading) — `ModelRegistry.find/getAll/getAvailable` return `any`, forcing `any`/`unknown` model threading through `model-resolver`, `spawn-config`, `service-adapter`, and `parent-snapshot`.
 Target files:
 
-- New `src/ui/session-navigator.ts` — a flat command that lists any subagent with a live record or a persisted session file (foreground included, never background-filtered), lets the operator pick one, and renders that child's transcript read-only.
-- New typed accessor on `Subagent`/`SubagentSession` returning `record.messages` as `AgentMessage[]` (the boundary currently widens it to `readonly unknown[]`).
-- `src/index.ts` — register the new command; the background widget ([#444]) is an optional secondary selection gesture, not a dependency.
+- `src/session/model-resolver.ts` — type the registry against `Model<any>` from `@earendil-works/pi-ai` (already imported elsewhere); remove the file-level eslint-disable; extract the fuzzy-scoring loop as a named helper if `resolveModel` (17 cyclomatic, 60 lines) still trips the threshold.
+- `src/service/service-adapter.ts` — type the resolved model in `spawn` (16 cyclomatic, CRAP 71.3, sole accelerating churn file) and extract the model-resolution branch.
+- `src/tools/spawn-config.ts` — shrink the 4-rule file-level disable to line-level or remove it.
 
-ADR-0004 Decision B: "Tell-Don't-Ask — hand Pi the session path; Pi owns the viewer."
-Mechanism (confirmed by the Step 1 spike and revised by [ADR-0004] Addendum 2): a **read-only** (non-interactive) transcript **dual-sourced by liveness**, rendered through Pi's own public entry components (no bespoke renderer).
+Outcome: `model-resolver.ts` file-level eslint-disable removed; `service-adapter.spawn` off the HIGH CRAP list; `any` model returns eliminated from the resolver.
 
-- **Tracked agent** (still in `manager.listAgents()`) — render live from the in-memory record: `record.messages` for history, `record.subscribeToUpdates()` to re-render on streaming updates, and `record.activeTools` / `record.responseText` for the running-agent streaming indicator.
-- **Evicted / untracked agent** — render from the file snapshot: `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages`.
+Landed: `ModelRegistry.find/getAll/getAvailable` and `resolveModel`'s return are typed against `Model<any>` from `@earendil-works/pi-ai`; the file-level eslint-disable headers on `model-resolver.ts` (2 rules) and `spawn-config.ts` (4 rules) are both removed — running disable-header tally 5 → 3 (`agent-tool` 6, `agent-widget` 4, `index` 1 remain, all Step 5 scope).
+`resolveModel`'s fuzzy-scoring loop was extracted to a private `findBestFuzzyMatch` helper, dropping `resolveModel` off the complexity list entirely.
+`service-adapter.spawn`'s model-resolution branch was extracted to a private `resolveModelOption`, dropping `spawn` from 16 cyclomatic / CRAP 71.3 (HIGH) to 13 cyclomatic / CRAP 49.5 (moderate) — off the HIGH-CRAP list; running HIGH-CRAP tally 2 → 1 remaining (the notification renderer arrow, untouched — Step 7 scope).
+`resolveInvocationModel` gained a `registry: ModelRegistry | undefined` guard (typed error instead of a crash when a model override is requested with no registry present); the residual `unknown` thread through `ParentSnapshot.model` / `SessionContext.model` is a separate SDK-boundary gap, deferred.
 
-Both sources yield `AgentMessage[]`, so one Pi-component renderer serves both: Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …) or `serializeConversation` (see the [ADR-0004] addendum, Findings 0 and 1).
-Neither `switchSession` (a full takeover that invalidates the root's in-flight turn) nor `loadEntriesFromFile` (a test-only export the package's public barrel does not re-export, in both `0.79.1` and `0.79.8`) is used.
-`Subagent.outputFile` already exposes the persisted child session JSONL path via `subagentSession?.outputFile` — no new SDK dependency.
-The new surface stands up while the old `viewAgentConversation`/`ConversationViewer` path still works; the bespoke viewer is removed only by the terminal cut (Step 5).
-
-Outcome: operator views any subagent's session through Pi's native machinery — live for a running agent, a file snapshot for an evicted one; the new surface coexists with the old viewer until Step 5.
-
-Landed ([#445], sliced): #445 shipped the first releasable vertical slice — the `/subagent-sessions` command (`src/ui/session-navigator.ts`), the pure selection/sourcing/text-render core (`src/ui/session-navigation.ts`), and the typed `agentMessages` accessor (`SessionMessage` on `SubagentSession`/`Subagent`).
-It is **live-source only** behind a renderer-agnostic `TranscriptSource` seam, rendered via Pi's `serializeConversation` text.
-With the `manager.listAgents()`-only candidate set, no listed record is ever session-disposed (dispose-and-delete are atomic), so the file-snapshot branch has no reachable caller and was deferred to keep `fallow dead-code` clean.
-Step 4 (#445, the slice) is complete and released (`pi-subagents` v17.3.0); the remaining work is now tracked as two follow-up steps behind the same seam: Step 4a ([#462]) upgrades the renderer from `serializeConversation` text to Pi's per-entry TUI components (gates Step 5 for rendering parity); Step 4b ([#463]) broadens the candidate set to evicted agents and adds the file-snapshot source (`parseSessionEntries` → `buildSessionContext`, independent).
-
-`Release: independent` (spike-gated)
+`Release: independent`
 
-### ✅ Step 4a — Upgrade native-navigation renderer to Pi TUI components ([#462])
+#### Step 5 — Narrow `tui`/`theme` render interfaces ([#539])
 
-Smell: Category C (coupling) — the #445 slice renders the transcript as `serializeConversation` plain text, while the bespoke `ConversationViewer` it replaces renders richer per-message formatting.
-Until the native renderer reaches parity, the terminal cut (Step 5) cannot delete the bespoke viewer without a fidelity regression.
-This step swaps the renderer behind the existing `TranscriptSource` seam (`src/ui/session-navigation.ts` / `session-navigator.ts`) for Pi's per-entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …); selection and sourcing are untouched.
+Smell: Category C/D (platform type threading; wide `any` params in render callbacks).
+Target files:
 
-Gates Step 5: per [ADR-0004]'s no-interim-regression invariant, the native navigator must reach rendering parity with the bespoke viewer before Step 5 deletes it.
+- `src/ui/agent-widget.ts` — replace `tui: any` with a lean local interface (`terminal.columns`, `requestRender()`); shrink the 4-rule file-level disable.
+- `src/tools/agent-tool.ts` — type `renderCall`/`renderResult` params (`theme`, `result`) with lean local interfaces; shrink the 6-rule file-level disable to the genuinely SDK-gapped lines.
+- `src/tools/foreground-runner.ts` — retire the line-level `details as any` cast if the SDK surface allows.
 
-Outcome: native session navigation renders at parity with the removed `ConversationViewer`; Step 5 can delete the bespoke viewer with no fidelity regression.
+Some disables are irreducible SDK export gaps; the goal is line-level precision, not zero.
 
-Landed ([#462]): the renderer now mounts Pi's per-entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / `BashExecutionComponent` / `UserMessageComponent` / `CompactionSummaryMessageComponent` / `BranchSummaryMessageComponent` / `SkillInvocationMessageComponent`) into a `Container`, mirroring Pi's own `renderSessionContext` mapping.
-The `TranscriptOverlay` caches that `Container` and rebuilds it on source change only (Pi's `rebuildChatFromMessages` path), keeping the lightweight `◍` streaming indicator.
-Tool calls render with their real `ToolDefinition`, resolved through a dependency-safe `getToolDefinition` read accessor on the record (mirroring `agentMessages`) surfaced on the `TranscriptSource` seam — no inbound call into the core.
-The pure `session-navigation.ts` sheds `renderTranscriptLines`/`serializeConversation`; rendering now lives in the SDK/TUI `session-navigator.ts`, which threads `cwd` from the command context.
-`custom`-role messages are skipped (the bespoke viewer never rendered them either).
-Selection and sourcing are untouched; native navigation now renders at parity, unblocking Step 5 for rendering fidelity.
+Outcome: file-level eslint-disable headers 5 → ≤ 2; remaining suppressions are line-level with named rules.
 
 `Release: independent`
 
-### ✅ Step 4b — File-snapshot source for evicted agents ([#463])
+#### Step 6 — Table-driven settings handler ([#540])
 
-Smell: Category C (coupling) — the #445 slice sources transcripts live from `manager.listAgents()` only; an agent evicted by the 10-minute cleanup sweep has a persisted session JSONL but no live record, so it is unreachable.
-This step adds the file-snapshot `TranscriptSource` branch (`parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages`) and broadens the candidate set to evicted agents, behind the same seam; the renderer is untouched.
-
-Independent: this is a new capability the bespoke viewer never had, so it gates nothing and is not a Step 5 prerequisite.
-Best sequenced after Step 4a (shared renderer), but carries no hard dependency.
+Smell: Category B (function duplication inside one function) — `subagents-settings.handle` (13 cyclomatic, 24 cognitive, 52 lines) repeats the select→input→parse→validate→apply→notify flow three times.
+Target files:
 
-Outcome: the operator can view a fully-evicted agent's transcript from its persisted session file; the dual-source design recorded in [ADR-0004] Addendum 2 is fully realized.
+- `src/ui/subagents-settings.ts` — describe each numeric setting as a descriptor (label, prompt, minimum, validation message, apply method) and drive one loop over the table.
+- `test/ui/subagents-settings.test.ts` — assert per-descriptor behavior.
 
-Landed ([#463]): `fileSnapshotSource(outputFile, readFile)` lands in the pure `session-navigation.ts` (`parseSessionEntries` → drop the `SessionHeader` → `buildSessionContext(...).messages`; a static no-subscribe, no-streaming source).
-The candidate set is broadened via **manager-retained descriptors**, not a directory scan: the persisted child session carries no subagent `type`/`description` (those live only on the in-memory record), so a scan would yield degraded labels and parse every file per open.
-Instead `SubagentManager.cleanup()` stashes a lightweight `EvictedSubagent` descriptor (label fields + `outputFile`, no messages) before disposing a record with a persisted file, exposed via `listEvicted()` and cleared by `clearCompleted()`/`dispose()`.
-`NavigationEntry` became a `live | evicted` discriminated union; the handler selects `liveSource` vs `fileSnapshotSource` by kind inside a `try/catch` (an unreadable file notifies and skips), and `index.ts` injects `readFileSync`.
-Evicted entries carry an `· evicted (snapshot)` label marker.
-Coverage is in-session evictions (the sweep's only targets); old-session orphan files — the ones a scan would surface with degraded labels — are out of scope.
+Outcome: `handle` cyclomatic ≤ 6 and cognitive ≤ 10; off the fallow high-complexity list.
 
 `Release: independent`
 
-### ✅ Step 5 — Dissolve `/agents` and remove the conversation-viewer subtree ([#442])
+#### Step 7 — Decompose the notification renderer ([#541])
 
-Smell: Category A (dead subsystem) plus Category B (oversized) — once Steps 2–4 re-home all four menu responsibilities, the `/agents` command and everything reachable only from `agent-menu.ts` is an unreferenced subtree.
-This is the first of two deletion commits (split by subtree).
-The hub `agent-menu.ts` is deleted here, not surgically narrowed, and deleting it is what orphans the leaf subtrees — so it must precede the definition-management deletion (Step 6), because `agent-menu.ts` statically imports the wizard, editor, and file-ops, and dynamically imports the viewer.
+Smell: Category B/D (oversized arrow, untested complexity) — the renderer arrow in `src/observation/renderer.ts` is fallow's top triage concern (17 cyclomatic, CRAP 79.4).
 Target files:
 
-- `src/index.ts` — remove the `registerCommand("agents", …)` block, the `AgentsMenuHandler` construction and import, and the `FsAgentFileOps` import/construction (its only use is wiring the menu).
-- Delete `src/ui/agent-menu.ts` (331 LOC) and `test/ui/agent-menu.test.ts` (185 LOC).
-- Delete `src/ui/conversation-viewer.ts` (241 LOC) and `test/conversation-viewer.test.ts` (239 LOC) — its only consumer is `agent-menu.ts`'s dynamic import, gone with the hub.
-- Delete `src/ui/message-formatters.ts` (195 LOC) and `test/message-formatters.test.ts` (388 LOC, the largest test function by LOC) — its only consumer is `ConversationViewer`.
-
-Running-agent visibility is now owned by the background widget (Step 3); session navigation replaces the bespoke overlay (Step 4); settings live in `/subagents-settings` (Step 2).
-Deleting the hub in one move avoids any surgical edit to the doomed file and leaves the definition-management leaves orphaned for Step 6.
+- `src/observation/renderer.ts` — extract pure line-assembly helpers (status→icon/label selection, stats-parts assembly, preview truncation) that are unit-testable without `Text` or a theme; the arrow becomes a thin wrapper.
+- `test/observation/renderer.test.ts` — test the pure helpers directly.
 
-Actual approach (vs. original plan): a tidy-first preparatory commit first extracted `MenuUI` from `agent-menu.ts` into a new `src/ui/menu-ui.ts` module, breaking the bidirectional type cycle — the hub imported the wizard/editor classes while the leaves imported back the `MenuUI` type.
-Without the prep commit, deleting either subtree first would have left the other half referencing a deleted module.
-`index.ts` also shed the now-dead `join` (node:path) and `buildParentSnapshot` imports in addition to the two module imports.
-The `menu-ui.ts` module is transient and is removed with the wizard/editor in Step 6.
+Soft ordering: land after Step 1 so the notification-domain files settle first.
 
-Outcome: ✅ `/agents` dissolved; −767 LOC source (menu hub + viewer + formatters); −812 LOC test; largest test function eliminated; `index.ts` dewired.
+Outcome: renderer arrow cyclomatic < 10; `renderer.ts` off the top of the fallow triage list.
 
-`Release: batch "dissolve-agents"`
+`Release: independent`
 
-### ✅ Step 6 — Remove the orphaned agent-definition management subtree ([#441])
+#### Step 8 — Full-value `SubagentStateInit` ([#542])
 
-Smell: Category A (dead subsystem) — the creation wizard and config editor are removed per ADR-0004 Decision C; after Step 5 deletes their only importer (`agent-menu.ts`), they and their file-ops helpers are pure orphans.
-This is the second deletion commit (split by subtree).
+Smell: Category D (shared factory complexity → narrow/complete the production init surface) — `createTestSubagent` (19 cyclomatic, 25 cognitive) seeds metrics via mutation loops because `SubagentStateInit` accepts only transition fields.
 Target files:
 
-- Delete `src/ui/agent-creation-wizard.ts` (233 LOC) and `test/ui/agent-creation-wizard.test.ts` (296 LOC).
-- Delete `src/ui/agent-config-editor.ts` (199 LOC) and `test/ui/agent-config-editor.test.ts` (392 LOC) — eliminates the 11-line internal production clone in `disableAgent`/`ejectAgent`, the package's only remaining production duplication.
-- Delete `src/ui/agent-file-ops.ts` (59 LOC) and `test/ui/agent-file-ops.test.ts` (112 LOC) — only consumers were wizard + editor.
-- Delete `src/ui/agent-file-writer.ts` (55 LOC) and `test/ui/agent-file-writer.test.ts` (148 LOC) — only consumers were wizard + editor.
-- `test/helpers/ui-stubs.ts` — delete `makeFileOps`, `createTestSubagentConfig`, and `spawnAndWait` from `makeMenuManager` if no surviving consumer remains; delete the file outright once all consumers are gone.
-
-An operator generates a new agent `.md` by asking a Pi session directly (more capable than a fixed wizard) or by writing the file in an editor; viewing and editing definitions is served by opening the `.md` files in an editor or IDE.
-These files are orphaned by Step 5, so this is a pure `git rm` with no surviving references and no edit to any doomed file.
-
-Outcome: −546 LOC source (wizard + editor + file-ops + file-writer); −948 LOC test; production duplication → 0 lines; 1 production and 1 test clone group eliminated.
+- `src/lifecycle/subagent-state.ts` — extend `SubagentStateInit` to optionally seed the full value (toolUses, lifetimeUsage, compactionCount, turnCount, activeTools, responseText); a value object is legitimately constructible at any point in its value space.
+- `test/helpers/make-subagent.ts` — collapse the mutation loops into direct init.
 
-Landed ([#441]): deleted `agent-creation-wizard.ts`, `agent-config-editor.ts`, `agent-file-ops.ts`, `agent-file-writer.ts`, and `menu-ui.ts` (orphaned transient) from `src/ui/`, plus their four test files.
-`test/helpers/ui-stubs.ts` pruned to `makeMenuUI` only (still consumed by `subagents-settings.test.ts`); `makeFileOps`, `makeMenuManager`, and `createTestSubagentConfig` removed with their `ui-stubs.test.ts` describe blocks.
-Production duplication: 0 lines (confirmed by `fallow dupes`); `fallow dead-code`: clean. 16 test clone groups remain — Step 7 consolidation target.
+Outcome: `createTestSubagent` cyclomatic ≤ 8; off the fallow complexity list; no production behavior change.
 
-`Release: batch "dissolve-agents"`
+`Release: independent`
 
-### Step 7 — Consolidate remaining test clone families ([#443])
+#### Step 9 — Consolidate remaining test clone families ([#543])
 
-Smell: Category D (testability) — 16 clone groups at Phase 18 end; the terminal cut (Steps 5–6) removes ~4 groups; remaining groups are extraction targets.
-Run after the cut so no helper is extracted into a file the cut then deletes.
-Target files:
+Smell: Category D (test duplication) — two clone families (`spawn-config.test.ts`: 2 groups / 21 lines; `subagent-manager.test.ts`: 2 groups / 15 lines) plus the `session-config.test.ts` pair (16 lines).
+Target files: the three test files and `test/helpers/` as needed.
 
-- `test/lifecycle/subagent-manager.test.ts` — extract a shared assertion helper for 3 clone families (23 lines across groups at :92/:109, :282/:330, and :323 shared with `subagent.test.ts`).
-- `test/ui/agent-widget.test.ts` — merge the duplicate `makeWidget` helper defined twice across two `describe` blocks (14-line clone at :225/:284).
-- `test/session/session-config.test.ts` — extract a shared fixture for the 16-line internal clone (lines 131–146 / 151–166).
-- `test/lifecycle/concurrency-limiter.test.ts` — extract shared setup for the 10-line clone (lines 21–30 / 148–155).
-- `test/tools/spawn-config.test.ts` — extract a shared fixture for the 9-line clone (lines 22–30 / 35–43).
+Runs last — Steps 1–3 and 8 rewrite portions of these suites, so consolidating first would churn twice.
 
-Outcome: test clone groups ≤ 10 (from 16); `subagent-manager.test.ts` uses shared factory helpers.
+Outcome: in-package clone groups 9 → ≤ 5; duplicated lines 81 → ≤ 40.
 
 `Release: independent`
 
-### Step dependency diagram
+### Step dependencies
 
 ```mermaid
 flowchart LR
-    S1["✅ Step 1 - Spike (#446)"]
-    S2["✅ Step 2 - Settings command (#447)"]
-    S3["✅ Step 3 - Background widget (#444)"]
-    S4["✅ Step 4 - Native session nav slice (#445)"]
-    S4a["✅ Step 4a - Renderer to TUI components (#462)"]
-    S4b["✅ Step 4b - File-snapshot source (#463)"]
-    S5["✅ Step 5 - Dissolve /agents + viewer (#442)"]
-    S6["✅ Step 6 - Remove definition mgmt (#441)"]
-    S7["Step 7 - Test clones (#443)"]
-
-    S1 --> S4
-    S4 --> S4a
-    S4 --> S4b
-    S2 --> S5
-    S3 --> S5
-    S4a --> S5
-    S5 --> S6
-    S6 --> S7
+    S1["✅ Step 1 (#535)<br/>Result delivery off Subagent"] --> S2["✅ Step 2 (#536)<br/>Decompose get-result-tool"]
+    S1 -.soft.-> S7["Step 7 (#541)<br/>Decompose notification renderer"]
+    S3["✅ Step 3 (#537)<br/>Steer returns an outcome"]
+    S4["✅ Step 4 (#538)<br/>Type the model boundary"]
+    S5["Step 5 (#539)<br/>Narrow tui/theme interfaces"]
+    S6["Step 6 (#540)<br/>Table-driven settings handler"]
+    S8["Step 8 (#542)<br/>Full-value SubagentStateInit"] --> S9["Step 9 (#543)<br/>Consolidate test clones"]
+    S2 --> S9
+    S3 --> S9
 ```
 
-The terminal cut (Step 5) depends on all three replacements — settings (Step 2), widget (Step 3), and session navigation **at rendering parity** (Step 4a, which completes the #445 slice) — because each of the four `/agents` options must have its responsibility re-homed, and the viewer replacement at parity, before its branch can die.
-Step 4b (file-snapshot source) is a new capability and gates nothing.
-The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes it explicit.
-
 ### Parallel tracks
 
-- **Track A — Replacements (Steps 1–4):** the spike gates session navigation (Step 1 → Step 4); settings (Step 2) and the background widget (Step 3) are independent of the spike and of each other.
-  None of these steps edits `agent-menu.ts`, so they carry no shared-file collision on the menu — genuinely parallelizable, unlike the prior plan's Steps 2/3/5, which all collided on `agent-menu.ts` and `index.ts`.
-  Steps 2 and 4 each append a command registration to `index.ts` (additive, low-conflict).
-  Steps 4a (renderer parity) and 4b (file-snapshot source) complete the #445 slice behind its `TranscriptSource` seam; Step 4a gates Step 5, Step 4b is independent.
-- **Track B — Dissolution (Steps 5 → 6):** the terminal cut, gated on all of Track A landing.
-  Hub-first ordering is forced: Step 5 deletes `agent-menu.ts` (orphaning the leaves), then Step 6 `git rm`s the now-orphaned definition-management subtree.
-- **Track C — Test health (Step 7):** clone consolidation, run after the cut so no surviving helper is extracted into a doomed file.
+- **Track A — Result delivery:** Steps 1 → 2, then 7 (soft).
+- **Track B — Tell-don't-ask:** Step 3.
+- **Track C — SDK boundary:** Steps 4, 5 (independent of each other).
+- **Track D — UI polish:** Step 6.
+- **Track E — Test health:** Step 8, then 9 (9 also waits on Tracks A/B test churn).
+
+Tracks A–D can proceed in parallel; only Step 9 serializes behind the rest.
 
 ### Release batches
 
-- **Batch "dissolve-agents":** Steps 5, 6 (ship together; tail = Step 6).
-  Depends on Steps 2, 3, 4 already merged.
-- Independently releasable: Steps 1, 2, 3, 4, 4a, 4b, 7.
+- **Batch "result-delivery":** Steps 1, 2 (ship together; tail = Step 2).
+- Independently releasable: Steps 3, 4, 5, 6, 7, 8, 9.
+
+Every step lands as a `refactor:`/`test:` commit — hidden changelog types that cut no release on their own; the work auto-batches into the next unhidden release.
 
 ## Refactoring history
 
-Phases 1–5, 7–18 are complete.
+Phases 1–5, 7–19 are complete.
 Phase 6 (UI extraction to a separate package) was deferred to Phase 18; its intent was resolved by [ADR-0004] (Phase 18 Step 8).
 Detailed records are preserved in per-phase history files:
 
@@ -1184,6 +1133,7 @@ Detailed records are preserved in per-phase history files:
 | 16    | Invert dependencies (extensions on a minimal core)  | Complete               | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
 | 17    | Core consolidation                                  | Complete               | [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md)             |
 | 18    | Reconsider UI (first principles)                    | Complete               | [phase-18-reconsider-ui.md](history/phase-18-reconsider-ui.md)                       |
+| 19    | Implement ADR-0004 UI decisions                     | Complete               | [phase-19-implement-ui-decisions.md](history/phase-19-implement-ui-decisions.md)     |
 
 ### Structural refactoring issues
 
@@ -1208,6 +1158,8 @@ Detailed records are preserved in per-phase history files:
 | 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                                                                                                                          |
 | Phase 18             | #420, #421, #422, #423, #424, #425, #426, #427             | Fold metrics onto record, migrate readers, delete activity tier, widget self-drives, drop widget from tool, reconcile event contract, consolidate test clones, UI-direction ADR                |
+| Phase 19             | #446, #447, #444, #445, #462, #463, #442, #441, #443       | ADR-0004 spike, settings command, background widget, native session nav slice, TUI renderer, file-snapshot source, dissolve /agents + viewer, remove definition mgmt, consolidate test clones  |
+| Phase 19 (follow-on) | #470                                                       | README refresh for the removed /agents command surface                                                                                                                                         |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -1280,5 +1232,15 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#447]: https://github.com/gotgenes/pi-packages/issues/447
 [#462]: https://github.com/gotgenes/pi-packages/issues/462
 [#463]: https://github.com/gotgenes/pi-packages/issues/463
+[#470]: https://github.com/gotgenes/pi-packages/issues/470
+[#535]: https://github.com/gotgenes/pi-packages/issues/535
+[#536]: https://github.com/gotgenes/pi-packages/issues/536
+[#537]: https://github.com/gotgenes/pi-packages/issues/537
+[#538]: https://github.com/gotgenes/pi-packages/issues/538
+[#539]: https://github.com/gotgenes/pi-packages/issues/539
+[#540]: https://github.com/gotgenes/pi-packages/issues/540
+[#541]: https://github.com/gotgenes/pi-packages/issues/541
+[#542]: https://github.com/gotgenes/pi-packages/issues/542
+[#543]: https://github.com/gotgenes/pi-packages/issues/543
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md
 [ADR-0004]: ../decisions/0004-reconsider-ui-direction.md