@gotgenes/pi-subagents 16.2.2 → 16.3.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [16.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.3.0...pi-subagents-v16.3.1) (2026-06-16)
+
+
+### Documentation
+
+* reframe pi-subagents positioning away from "Claude Code-style" ([c8d380d](https://github.com/gotgenes/pi-packages/commit/c8d380d440a4ae29f9173673523337cf667fb3da))
+
+## [16.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.2...pi-subagents-v16.3.0) (2026-06-16)
+
+
+### Features
+
+* self-seed finished agents in AgentWidget.update ([#377](https://github.com/gotgenes/pi-packages/issues/377)) ([fd99a29](https://github.com/gotgenes/pi-packages/commit/fd99a297f70ce4c1c078fd486be042f691fe5a79))
+
+
+### Documentation
+
+* **pi-subagents:** drop removed memory, skills, isolation surfaces ([7cf20ee](https://github.com/gotgenes/pi-packages/commit/7cf20eebf109c979a864000cd8b9d84a13d0df90))
+
 ## [16.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.1...pi-subagents-v16.2.2) (2026-06-15)
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@gotgenes/pi-subagents?style=flat&logo=npm&logoColor=white)](https://www.npmjs.com/package/@gotgenes/pi-subagents) [![CI](https://img.shields.io/github/actions/workflow/status/gotgenes/pi-packages/ci.yml?style=flat&logo=github&label=CI)](https://github.com/gotgenes/pi-packages/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![pnpm](https://img.shields.io/badge/pnpm-%3E%3D11-F69220?style=flat&logo=pnpm&logoColor=white)](https://pnpm.io/) [![Pi Package](https://img.shields.io/badge/Pi-Package-6366F1?style=flat)](https://pi.mariozechner.at/)
 
-A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-agents** to pi.
+A [pi](https://pi.dev) extension that gives pi **a focused, in-process sub-agent core** — autonomous agents that run inside the same pi runtime (no spawned subprocesses), plus a typed API and lifecycle events other extensions build on.
 Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level.
 Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.
 
@@ -15,7 +15,7 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
 
 ## Features
 
-- **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
+- **In-process & native** — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
@@ -27,9 +27,6 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
   Unknown types fall back to general-purpose with a note
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
-- **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
-- **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
-- **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML.
   Expandable to show full output
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
@@ -84,7 +81,7 @@ The token field is annotated with two optional signals inside parens:
 - **`↻N`** — number of times the session has compacted, when > 0.
   Stays dim; the percent's color carries urgency.
 
-Individual agent results render Claude Code-style in the conversation:
+Individual agent results render inline in the conversation:
 
 | State          | Example                                                                                  |
 | -------------- | ---------------------------------------------------------------------------------------- |
@@ -174,21 +171,16 @@ All fields are optional — sensible defaults for everything.
 | `description`       | filename       | Agent description shown in tool listings                                                                                                                                                                                                                                                                                |
 | `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                                                                                                                                           |
 | `tools`             | all 7          | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools                                                                                                                                                                                                                            |
-| `extensions`        | `true`         | `true` to inherit all MCP/extension tools, `false` to disable                                                                                                                                                                                                                                                           |
-| `skills`            | `true`         | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations)                                                                                                                                                                 |
-| `memory`            | —              | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents                                                                                                                                                                                                                             |
-| `isolation`         | —              | Set to `worktree` to run in an isolated git worktree                                                                                                                                                                                                                                                                    |
 | `model`             | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`)                                                                                                                                                                                                                                                        |
 | `thinking`          | inherit        | off, minimal, low, medium, high, xhigh                                                                                                                                                                                                                                                                                  |
 | `max_turns`         | unlimited      | Max agentic turns before graceful shutdown. `0` or omit for unlimited                                                                                                                                                                                                                                                   |
 | `prompt_mode`       | `append`       | `replace`: parent prompt is the cacheable base; body is appended last with full control (no `<sub_agent_context>` bridge, no `<agent_instructions>` wrapper). `append`: parent prompt is the base; body is wrapped in `<agent_instructions>` and a sub-agent context bridge is injected (agent acts as a "parent twin") |
 | `inherit_context`   | `false`        | Fork parent conversation into agent                                                                                                                                                                                                                                                                                     |
 | `run_in_background` | `false`        | Run in background by default                                                                                                                                                                                                                                                                                            |
-| `isolated`          | `false`        | No extension/MCP tools, only built-in                                                                                                                                                                                                                                                                                   |
 | `enabled`           | `true`         | Set to `false` to disable an agent (useful for hiding a default agent per-project)                                                                                                                                                                                                                                      |
 
 Frontmatter is authoritative.
-If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent.
+If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, or `run_in_background`, those values are locked for that agent.
 `subagent` tool parameters only fill fields the agent config leaves unspecified.
 
 ## Tools
@@ -207,8 +199,6 @@ Launch a sub-agent.
 | `max_turns`         | number       | no       | Max agentic turns. Omit for unlimited (default)                  |
 | `run_in_background` | boolean      | no       | Run without blocking                                             |
 | `resume`            | string       | no       | Agent ID to resume a previous session                            |
-| `isolated`          | boolean      | no       | No extension/MCP tools                                           |
-| `isolation`         | `"worktree"` | no       | Run in an isolated git worktree                                  |
 | `inherit_context`   | boolean      | no       | Fork parent conversation into agent                              |
 
 ### `get_subagent_result`
@@ -331,77 +321,16 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 `cacheRead` is excluded — each turn's `cacheRead` is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it.
 Use `contextUsage.percent` (surfaced as `(NN%)` in the widget) for current context size.
 
-## Persistent Agent Memory
-
-Agents can have persistent memory across sessions.
-Set `memory` in frontmatter to enable:
-
-```yaml
----
-memory: project   # project | local | user
----
-```
-
-| Scope     | Location                         | Use case                           |
-| --------- | -------------------------------- | ---------------------------------- |
-| `project` | `.pi/agent-memory/<name>/`       | Shared across the team (committed) |
-| `local`   | `.pi/agent-memory-local/<name>/` | Machine-specific (gitignored)      |
-| `user`    | `~/.pi/agent-memory/<name>/`     | Global personal memory             |
-
-Memory uses a `MEMORY.md` index file and individual memory files with frontmatter.
-Agents with write tools get full read-write access.
-**Read-only agents** (no `write`/`edit` tools) automatically get read-only memory — they can consume memories written by other agents but cannot modify them.
-This prevents unintended tool escalation.
-
 ## Worktree Isolation
 
-Set `isolation: worktree` to run an agent in a temporary git worktree:
-
-```text
-subagent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
-```
-
-The agent gets a full, isolated copy of the repository.
-On completion:
-
-- **No changes:** worktree is cleaned up automatically
-- **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
-
-If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `subagent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint.
-Initialize git and commit at least once, or omit `isolation`.
-
-## Skill Preloading
-
-Skills can be preloaded by name and injected into the agent's system prompt:
-
-```yaml
----
-skills: api-conventions, error-handling
----
-```
-
-**Discovery roots** (checked in this order, first match wins):
-
-| Scope   | Path                                                           | Source                                                       |
-| ------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
-| Project | `<cwd>/.pi/skills/`                                            | Pi-standard                                                  |
-| Project | `<cwd>/.agents/skills/`                                        | [Agent Skills spec](https://agentskills.io/integrate-skills) |
-| User    | `$PI_CODING_AGENT_DIR/skills/` (default `~/.pi/agent/skills/`) | Pi-standard                                                  |
-| User    | `~/.agents/skills/`                                            | [Agent Skills spec](https://agentskills.io/integrate-skills) |
-| User    | `~/.pi/skills/`                                                | Legacy (pre-Pi)                                              |
-
-**Per root, a skill named `foo` resolves to the first of:**
-
-- `<root>/foo.md` — flat file at the top level
-- `<root>/foo/SKILL.md` — directory skill (top-level)
-- `<root>/*/.../foo/SKILL.md` — directory skill, found by recursive descent
+Worktree isolation lives in a companion package, not this core.
+Install [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees) and list the agent types you want isolated in its `worktreeAgents` config — opted-in agents run in a temporary git worktree, and their changes are saved to a branch on completion.
+The earlier `isolation: "worktree"` spawn flag and `isolation:` frontmatter key were removed from the core.
 
-Recursion skips dotfile directories and `node_modules`.
-A directory that itself contains a `SKILL.md` is treated as a single skill — we don't descend into it.
-Traversal is byte-order sorted for deterministic resolution across filesystems.
+## Removed: agent memory and skill preloading
 
-**Security:** symlinks are rejected at every layer (root, flat file, skill directory, `SKILL.md` inside a skill directory) — intentional deviation from Pi, which follows symlinks.
-Skill names with path-traversal characters (`..`, `/`, `\`, spaces, leading dot, >128 chars) are rejected.
+Persistent agent memory (the `memory:` frontmatter key) and skill preloading (the `skills:` frontmatter key) were removed when the core was slimmed down.
+Children now always inherit the parent's skills and extensions, so the `isolated`, `extensions`, and `skills` frontmatter keys no longer exist.
 
 ## Migrating from `disallowed_tools`
 

package/docs/architecture/architecture.md

@@ -989,12 +989,18 @@ Priority = Impact × (6 − Risk).
 - 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])
+#### Step 6 — Split widget delegation out of SubagentRuntime ([#377]) ✅ Complete
 
-- Targets: `src/runtime.ts`, `src/tools/agent-tool.ts` (`AgentToolRuntime`), `src/tools/foreground-runner.ts`, `src/tools/background-spawner.ts`, `src/observation/notification.ts` (`NotificationManager` constructor), `src/index.ts`.
+- 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.
-- Change: pass the existing `WidgetLike` handle directly to the consumers that need it (tool deps, `NotificationManager`) and construct the widget before them; remove the `widget` field and the five relay methods from `SubagentRuntime`.
-- Outcome: `SubagentRuntime` has zero widget knowledge; no post-construction field writes in `index.ts`; tool fixtures stub a 5-method `WidgetLike` instead of widget methods on the runtime mock.
+- 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])
 

package/docs/comparison-with-upstream.md

@@ -1,7 +1,7 @@
 # Comparison with upstream
 
 `@gotgenes/pi-subagents` began as a fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
-The original design — Claude Code-style subagent dispatch, the live widget, the conversation viewer, custom agent types — is the foundation everything here builds on.
+The original design — autonomous subagent dispatch, the live widget, the conversation viewer, custom agent types — is the foundation everything here builds on.
 
 It has since become an independently maintained hard fork.
 It follows its own architecture, does not track upstream as a merge target, and cherry-picks upstream fixes only when they fit its scope.
@@ -26,10 +26,9 @@ The peer-dep migration that prompted the original fork has since landed upstream
 
 Both extensions provide the same core experience:
 
-- Claude Code-style foreground/background subagents with a live above-editor widget and a conversation viewer.
+- Foreground/background subagents with a live above-editor widget and a conversation viewer.
 - Custom agent types defined in `.pi/agents/<name>.md` with YAML frontmatter (system prompt, model, thinking, tools).
-- Persistent agent memory (project / local / user scopes) with read-only fallback.
-- Skill preloading, fuzzy model selection, context inheritance, mid-run steering, session resume, and graceful turn limits.
+- Fuzzy model selection, context inheritance, mid-run steering, session resume, and graceful turn limits.
 - A `pi.events` lifecycle bus (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`).
 
 ## What upstream has that this fork does not
@@ -41,6 +40,8 @@ It keeps several subsystems built in that this fork deliberately removed or dele
 | ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Tool restrictions       | `disallowed_tools` frontmatter (denylist)         | Delegated — `permission:` via [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) |
 | Worktree isolation      | Built-in                                          | Delegated — [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees)               |
+| Persistent agent memory | `memory:` frontmatter (project / local / user)    | Removed                                                                                                                                           |
+| Skill preloading        | `skills:` frontmatter (preload named skills)      | Removed — children always inherit the parent's skills                                                                                             |
 | Scheduling              | Cron / interval / one-shot subagents (`schedule`) | Removed                                                                                                                                           |
 | Cross-extension control | `subagents:rpc:*` event RPC                       | Replaced by a typed service (below)                                                                                                               |
 | Model-scope enforcement | `enabledModels` allowlist validation              | Not included                                                                                                                                      |

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

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

package/docs/retro/0376-extract-manager-observer.md

@@ -38,3 +38,44 @@ Pre-completion reviewer: PASS.
 - The autoformatter (`pi-autoformat`) ran after writing `index.ts`, so the import block was reflowed; re-reading before further edits would be required in any follow-up session.
 - Architecture doc: Step 4's header was already missing its ✅ Complete marker (it had a Landed note); the reviewer noted this was corrected correctly, not a regression.
 - All five previously-untested observer-behavior invariants are now pinned by tests for the first time.
+
+## Stage: Final Retrospective (2026-06-15T22:55:15Z)
+
+### Session summary
+
+Phase 17 Step 5 ran cleanly end-to-end across planning, TDD, ship, and retro: one `refactor:` extraction commit plus a `docs:` roadmap update, +15 tests, `index.ts` 226 → 177 lines, released as `pi-subagents-v16.2.2`.
+The plan correctly anticipated the class/`index.ts` coupling (one commit) and the `unbound-method` trap (arrow callbacks), so implementation followed the plan with a single minor test-assertion adjustment.
+The pre-completion reviewer (on `claude-sonnet-4-6`) returned PASS and incidentally flagged a stale Step 4 checkmark that was corrected.
+
+### Observations
+
+#### What went well
+
+- The lint feedback loop caught the only defect before it was committed: typed `vi.fn` made `mock.calls[0]!` an unnecessary assertion, surfaced by `pnpm run lint` between green and commit, fixed by switching to `toHaveBeenCalledWith(...)`.
+  No follow-up commit was needed — verification ran incrementally (lint + test before each commit, `fallow dead-code` before push).
+- The `pre-completion-reviewer` subagent earned its dispatch: beyond confirming the deterministic gates, it caught that Phase 17 Step 4's header was missing its `✅ Complete` marker (a prior-session oversight) and validated all six Mermaid diagrams.
+- The plan's pre-work paid off — the coupling note (class + consumer + import removal in one commit to satisfy `fallow`) and the arrow-callback note for `emit`/`appendEntry` meant zero rework at those two known-risk points.
+
+#### What caused friction (agent side)
+
+- `missing-context` (self-identified) — the TDD test was written with `mock.calls[0]!` non-null assertions; typed `vi.fn<(channel: string, data: unknown) => void>()` makes the call tuple non-optional, so `@typescript-eslint/no-unnecessary-type-assertion` fired on every `!`.
+  Impact: ~5 tool calls (turns 1–6) to diagnose and rewrite four assertions to `toHaveBeenCalledWith(...)`; caught by lint before commit, no rework.
+- `missing-context` (self-identified) — the ship stage used `grep -oP` (Perl regex) to extract issue numbers; macOS BSD `grep` has no `-P`.
+  Impact: one wasted tool call (turn 38), self-recovered with `sed` on turn 39.
+
+#### What caused friction (user side)
+
+- None.
+  The single `ask_user` gate (release batching) was the appropriate strategic checkpoint and the user answered "close now"; no mechanical oversight was required.
+
+### Diagnostic details
+
+- **Model-performance correlation** — TDD ran on `claude-sonnet-4-6` (appropriate for judgment + code authoring); the `pre-completion-reviewer` subagent ran on `claude-sonnet-4-6` per its agent frontmatter (appropriate for review).
+  The ship stage ran on `opencode-go/deepseek-v4-flash` — a cheaper model on a mostly-mechanical workflow (git, CI watch, issue close).
+  It handled the one judgment call (release batching) correctly by asking the user and read the release-PR body for sibling bumps, but the `grep -oP` slip is the kind of environment mistake a weaker model is likelier to make; net match was acceptable.
+- **Escalation-delay tracking** — no `rabbit-hole`; the longest single-issue run was the ~5-call `mock.calls[0]!` diagnosis, which was methodical (read → read → edit → lint → test), not thrashing.
+- **Feedback-loop gap analysis** — no gap: `pnpm run lint` and `vitest run` ran before each commit and `fallow dead-code` ran from the repo root before push, exactly as the templates prescribe.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added a § Test assertions bullet: assert mock calls with `toHaveBeenCalledWith(...)` rather than `fn.mock.calls[0]![0]`, since a typed `vi.fn` makes the call tuple non-optional and the `!` trips `@typescript-eslint/no-unnecessary-type-assertion`.

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

@@ -0,0 +1,105 @@
+---
+issue: 377
+issue_title: "Split widget delegation out of SubagentRuntime"
+---
+
+# Retro: #377 — Split widget delegation out of SubagentRuntime
+
+## Stage: Planning (2026-06-15T23:16:29Z)
+
+### Session summary
+
+Produced the implementation plan for removing the `widget` field and five relay methods from `SubagentRuntime`.
+Investigation surfaced that the issue's stated approach ("construct the widget before its consumers, pass the handle to `NotificationManager`") is infeasible as written — `NotificationManager` is a transitive *dependency* of the widget, forming a genuine construction cycle (`NotificationManager → widget → manager → observer → NotificationManager`).
+The plan dissolves the cycle instead of relocating its late seam.
+
+### Observations
+
+- **Operator steer #1 (seam placement):** rejected both a setter on the observer and a forward-referenced `let widget` closure, citing "no setters, instantiate ready-to-work, constructor DI" (principle 8).
+  The forward-ref option would also have trip `prefer-const` and reintroduced the exact eslint-disable smell Phase 17 Step 1 deleted.
+- **Operator steer #2 (tidy-first, Kent Beck):** prompted the prep/easy decomposition.
+  The hard, cycle-breaking work (dissolve `NotificationManager`'s widget dependency by giving `AgentWidget` self-seeding of `finishedTurnAge`) lands first as a behavior-preserving commit; the relay-method removal then becomes a mechanical "easy change."
+- **Behavior-preservation argument:** the widget's 80ms timer is always running at a background completion (the agent was active), and linger expiry is turn-based, so seeding ≤80ms later lands in the same turn — rendered outcome is identical.
+  This is the load-bearing claim; the new `agent-widget.test.ts` self-seed test pins it.
+- **Three seam options recorded** in the plan's Design Overview for traceability: late-observer setter (rejected), forward-ref closure (rejected), dissolve (chosen).
+- **Scope guard:** kept foreground-runner's explicit `markFinished` (idempotent) rather than removing it, and deferred the event-subscription widget model to Phase 18.
+  Two open questions logged (single `AgentToolWidget` vs. split deps; redundancy of foreground `markFinished`).
+- **Not breaking / not public:** `runtime.ts` is internal (not in the rolled `service.ts` type bundle), so `verify:public-types` is not required.
+- **Invariants at risk** flagged against Phase 17 Steps 1 and 5 (forward-ref dance, `index.ts` line budget); grep acceptance checks fold into the final implementation step.
+
+## Stage: Implementation — TDD (2026-06-15T20:19:00Z)
+
+### Session summary
+
+Executed all four planned steps in order: widget self-seeding (`feat`), `NotificationManager` widget-dependency dissolve (`refactor`), direct widget injection + relay-method removal (`refactor`), and the architecture-roadmap update (`docs`).
+Test count went 1009 → 1005 (+3 widget self-seed tests, −7 removed relay/field tests).
+All deterministic checks green; pre-completion reviewer returned WARN (non-blocking).
+
+### Observations
+
+- The tidy-first sequencing held up exactly as planned: Step 2 broke the cycle while the runtime relay methods were still in place (repo stayed green), making Step 3's export/field removal a clean atomic change.
+- The cycle dissolve produced two **stale fallow suppressions** on `AgentWidget.setUICtx`/`onTurnStart` — they were `unused-class-member`-suppressed because the methods were previously reached only through the runtime relay; direct injection made them visibly used.
+  Removed both; amended into the Step 3 refactor commit.
+- Widget-class testing required constructing `AgentWidget` with a cast manager stub (`as unknown as SubagentManager`) and a recording `UICtx`; observability of the private `finishedTurnAge` is via the `setWidget` clear-vs-register signal, which cleanly distinguishes seeded-then-aged-out from never-seeded.
+- `sed` was needed for the runner/spawner test files because the widget arg appeared both inline and as standalone multiline-call lines; a `^\s*runtime,$` line match safely retargeted only the widget positional arg (never `runtime.agentActivity`).
+- Two commit-hygiene corrections: an `index.ts` comment-trim fixup was first amended into the `docs` commit by mistake, then moved into the Step 3 `refactor` commit via `reset --soft` + selective re-stage (fixups must not land in `docs:` commits).
+- **Reviewer verdict: WARN.**
+  Sole finding: `index.ts` is 177 lines (Step 5's aspirational "<170" was already overshot at its own landing, 177); the comment trim kept Step 6 net-neutral.
+  Cosmetic, prose-pinned only, non-blocking.
+- Cross-step invariants verified by grep: no `let widget` / `prefer-const` forward-ref (Step 1), no `runtime.widget` / `.widget =` / `WidgetLike` anywhere (the issue's core outcome).
+
+## Stage: Final Retrospective (2026-06-16T00:30:08Z)
+
+### Session summary
+
+The issue shipped cleanly across plan → TDD → ship as `pi-subagents-v16.3.0`, closing #377 and resolving Phase 17 Step 6.
+The design arc was the highlight: an operator-driven pivot from the issue's stated approach (relocate the late seam) to dissolving the construction cycle entirely, sequenced tidy-first so the hard cycle-break landed before the mechanical relay removal.
+The friction was concentrated in mechanical `Edit`-tool execution, not in design or verification.
+
+### Observations
+
+#### What went well
+
+- **Operator design steers compounded into the right architecture.**
+  The planning `ask_user` surfaced the construction cycle; the operator's "no setters, instantiate ready-to-work" steer eliminated two of three seam options, and the Kent Beck "make the change easy" prompt (turn 21) produced the tidy-first decomposition.
+  This is the pattern working as intended: the agent finds the constraint, the operator picks the principle, the agent verifies feasibility before committing.
+- **Behavior-preservation was argued before it was coded.**
+  The ≤80ms-within-same-turn linger argument was established in planning and pinned by three new `agent-widget.test.ts` tests in TDD — no trial-and-error on the load-bearing claim.
+- **Tidy-first sequencing kept the repo green at every commit.**
+  Step 2 broke the cycle while the relay methods still existed, making Step 3's export removal a clean atomic change.
+- **Cheap model handled ship correctly.**
+  Ship ran on `opencode-go/deepseek-v4-flash` and executed the full mechanical sequence (push, CI watch, release-now `ask_user`, the `UNSTABLE` merge-state edge case via `gh pr merge`) with zero errors — an appropriate model-task match, not a mismatch.
+
+#### What caused friction (agent side)
+
+- `other` (tool friction) — `Edit` on `runtime.ts` failed twice (turns 45, 47) trying to delete the widget-delegation block bounded by a decorative `// ── Widget delegation methods ────` comment rule; the long run of `─` could not be reproduced exactly.
+  Fell back to `sed -i '' '75,104d'`, which over-deleted the class-closing brace and the next doc-comment opener (turn 51), needing a repair edit (turn 52).
+  Impact: ~5 extra tool calls and a near-miss structural breakage on a single block deletion.
+- `instruction-violation` (user-caught) — the operator interjected "Use unicode literal characters, not escapes, per system prompt" (turn 49).
+  The system prompt already carries an "Edit Tool and Unicode Characters" section; the box-drawing match failures read to the operator as escape misuse.
+  Impact: one user correction; reinforced the same `Edit`-matching friction above.
+- `other` (malformed payload) — the first `architecture.md` Step 6 edit was rejected for an invalid `oldText_unused` property I invented (turn 87), followed by empty assistant turns and two operator "Try again" nudges (turns 89, 94) before a clean single edit landed (turn 95).
+  Impact: ~4 turns + 2 user nudges on one prose edit.
+- `other` (commit hygiene) — the `index.ts` comment-trim fixup was first amended into the `docs` commit (turn 108), then moved into the `refactor` commit via `reset --soft` (turn 109); separately, the stale-suppression fixup required the same maneuver during TDD.
+  Both self-identified and corrected.
+  Impact: two extra `reset --soft` + re-stage cycles; no rework to shipped code.
+
+#### What caused friction (user side)
+
+- The "no setters, instantiate ready-to-work" principle that drove the entire design only surfaced when the planning `ask_user` forced it.
+  Stated in the issue body or a standing design note, it would have let planning reach the dissolve approach without the round-trip — though the round-trip was cheap and the outcome correct.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Planning and TDD ran on `anthropic/claude-opus-4-8` (judgment-heavy design + implementation; appropriate).
+  The pre-completion-reviewer subagent ran on `anthropic/claude-sonnet-4-6` per its frontmatter (appropriate for review).
+  Ship ran on `opencode-go/deepseek-v4-flash` — a cheap model on mechanical orchestration, completed without error.
+  No mismatch found.
+- **Escalation-delay tracking** — no `rabbit-hole` exceeded the 5-consecutive-call threshold; the `Edit`/`sed` friction was 2–3 calls per location and self-resolved.
+- **Unused-tool detection** — nothing notable; the friction points were mechanical edits, not missing context, so no Explore/`colgrep` dispatch would have helped.
+- **Feedback-loop gap analysis** — verification was incremental and exemplary: `pnpm run check` after the shared-interface change in Step 2 (turn 43) and again mid-Step-3 (turns 69, 75, 78, 81); per-file `vitest run` after each Red and Green; `fallow dead-code` from repo root before ship.
+  No end-only verification anti-pattern.
+
+### Changes made
+
+1. `AGENTS.md` — appended two sentences to the "Edit tool batches" subsection: anchor edits on adjacent unique code lines rather than decorative `─`/`═` comment rules, and re-read after a `sed` line-number deletion to confirm an enclosing brace survived.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.2.2",
+  "version": "16.3.1",
   "type": "module",
   "exports": {
     ".": {
@@ -21,7 +21,7 @@
     "#src/*": "./src/*",
     "#test/*": "./test/*"
   },
-  "description": "A pi extension that brings Claude Code-style autonomous sub-agents to pi. Friendly fork of @tintinweb/pi-subagents.",
+  "description": "A focused, in-process sub-agent core for pi — autonomous agents plus a typed API and lifecycle events other extensions build on. Friendly fork of @tintinweb/pi-subagents.",
   "author": {
     "name": "Chris Lasher"
   },

package/src/handlers/tool-start.ts

@@ -5,8 +5,8 @@
  * with a mocked narrow runtime interface.
  */
 
-/** Narrow runtime interface — only the widget-delegation methods the handler calls. */
-export interface ToolStartRuntime {
+/** Narrow widget interface — only the methods the handler calls. */
+export interface ToolStartWidget {
   setUICtx(ctx: unknown): void;
   onTurnStart(): void;
 }
@@ -23,10 +23,10 @@ interface ToolStartCtx {
  * and signals the widget to clear lingering state.
  */
 export class ToolStartHandler {
-  constructor(private readonly runtime: ToolStartRuntime) {}
+  constructor(private readonly widget: ToolStartWidget) {}
 
   handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void {
-    this.runtime.setUICtx(ctx.ui);
-    this.runtime.onTurnStart();
+    this.widget.setUICtx(ctx.ui);
+    this.widget.onTurnStart();
   }
 }

package/src/index.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
- * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
+ * pi-agents — A pi extension providing focused, in-process autonomous sub-agents.
  *
  * Tools:
  *   Agent             — LLM-callable: spawn a sub-agent
@@ -57,13 +57,12 @@ export default function (pi: ExtensionAPI) {
   const runtime = createSubagentRuntime();
 
   // ---- Notification system ----
-  // runtime.widget is assigned after SubagentManager construction; arrow closures
-  // capture `runtime` by reference so they always read the current value.
+  // Owns completion nudges and live-activity cleanup. The widget detects finished
+  // agents itself (AgentWidget.update self-seeds), so NotificationManager has no
+  // widget dependency — keeping the construction graph a cycle-free DAG.
   const notifications = new NotificationManager(
     (msg, opts) => pi.sendMessage(msg, opts),
     runtime.agentActivity,
-    (id) => runtime.markFinished(id),
-    () => runtime.update(),
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -129,11 +128,12 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
   pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
 
-  // Live widget: show running agents above editor
-  runtime.widget = new AgentWidget(manager, runtime.agentActivity, registry);
+  // Live widget: constructed after the manager (it polls listAgents()) and
+  // injected directly into its consumers — no post-construction field write.
+  const widget = new AgentWidget(manager, runtime.agentActivity, registry);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
-  const toolStart = new ToolStartHandler(runtime);
+  const toolStart = new ToolStartHandler(widget);
   pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
   // Abort all subagents when the parent agent loop is interrupted (ESC).
@@ -142,7 +142,7 @@ export default function (pi: ExtensionAPI) {
 
   // ---- Agent tool ----
 
-  pi.registerTool(new AgentTool(manager, runtime, settings, registry, getAgentDir()).toToolDefinition());
+  pi.registerTool(new AgentTool(manager, runtime, widget, settings, registry, getAgentDir()).toToolDefinition());
 
   // ---- get_subagent_result tool ----
 

package/src/observation/notification.ts

@@ -41,7 +41,7 @@ export function getStatusLabel(status: string, error?: string): string {
   }
 }
 
-/** Format a structured task notification matching Claude Code's <task-notification> XML. */
+/** Format a structured <task-notification> XML block for the parent agent to parse. */
 export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
@@ -142,8 +142,6 @@ export class NotificationManager implements NotificationSystem {
       opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
     ) => void,
     private agentActivity: Map<string, AgentActivityTracker>,
-    private markFinished: (id: string) => void,
-    private updateWidget: () => void,
   ) {}
 
   cancelNudge(key: string): void {
@@ -156,15 +154,11 @@ export class NotificationManager implements NotificationSystem {
 
   sendCompletion(record: Subagent): void {
     this.agentActivity.delete(record.id);
-    this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
-    this.updateWidget();
   }
 
   cleanupCompleted(id: string): void {
     this.agentActivity.delete(id);
-    this.markFinished(id);
-    this.updateWidget();
   }
 
   dispose(): void {

package/src/runtime.ts

@@ -10,19 +10,6 @@ import { buildParentSnapshot, type ParentSnapshot } from "#src/lifecycle/parent-
 import type { ModelInfo } from "#src/tools/spawn-config";
 import type { SessionContext } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
-import type { UICtx } from "#src/ui/agent-widget";
-
-/**
- * Narrow widget interface consumed by SubagentRuntime delegation methods.
- * AgentWidget satisfies this structurally; tests use plain stubs.
- */
-export interface WidgetLike {
-  setUICtx(ctx: UICtx): void;
-  onTurnStart(): void;
-  markFinished(id: string): void;
-  update(): void;
-  ensureTimer(): void;
-}
 
 /**
  * Narrow config subset read by Agent when driving the turn loop (defaultMaxTurns, graceTurns).
@@ -48,11 +35,6 @@ export class SubagentRuntime {
    * widget, and tool handlers. The Map itself is never replaced.
    */
   readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
-  /**
-   * Persistent widget reference. Null until constructed after SubagentManager.
-   * Delegation methods use optional chaining so callers never need `widget!`.
-   */
-  widget: WidgetLike | null = null;
 
   // ── Session-context methods ──────────────────────────────────────────────
 
@@ -90,33 +72,6 @@ export class SubagentRuntime {
       parentSessionId: this.currentCtx?.sessionManager.getSessionId() ?? "",
     };
   }
-
-  // ── Widget delegation methods ─────────────────────────────────────────────
-
-  /** Delegate to widget.setUICtx — no-op when widget is null. */
-  setUICtx(ctx: UICtx): void {
-    this.widget?.setUICtx(ctx);
-  }
-
-  /** Delegate to widget.onTurnStart — no-op when widget is null. */
-  onTurnStart(): void {
-    this.widget?.onTurnStart();
-  }
-
-  /** Delegate to widget.markFinished — no-op when widget is null. */
-  markFinished(id: string): void {
-    this.widget?.markFinished(id);
-  }
-
-  /** Delegate to widget.update — no-op when widget is null. */
-  update(): void {
-    this.widget?.update();
-  }
-
-  /** Delegate to widget.ensureTimer — no-op when widget is null. */
-  ensureTimer(): void {
-    this.widget?.ensureTimer();
-  }
 }
 
 /**

package/src/tools/agent-tool.ts

@@ -41,13 +41,21 @@ export interface AgentToolManager {
 /** Narrow runtime interface — the Agent tool's slice of SubagentRuntime. */
 export interface AgentToolRuntime {
 	readonly agentActivity: AgentActivityAccess;
+	buildSnapshot(inheritContext: boolean): ParentSnapshot;
+	getModelInfo(): ModelInfo;
+	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
+}
+
+/**
+ * Narrow widget interface the Agent tool drives directly.
+ * Superset of the runner/spawner widget deps plus `setUICtx`.
+ * AgentWidget satisfies it structurally.
+ */
+export interface AgentToolWidget {
 	setUICtx(ctx: UICtx): void;
 	ensureTimer(): void;
 	update(): void;
 	markFinished(id: string): void;
-	buildSnapshot(inheritContext: boolean): ParentSnapshot;
-	getModelInfo(): ModelInfo;
-	getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
 }
 
 /** Narrow settings accessor — only the fields the Agent tool reads. */
@@ -65,6 +73,7 @@ export class AgentTool {
 	constructor(
 		private readonly manager: AgentToolManager,
 		private readonly runtime: AgentToolRuntime,
+		private readonly widget: AgentToolWidget,
 		private readonly settings: AgentToolSettings,
 		private readonly registry: AgentTypeRegistry,
 		private readonly agentDir: string,
@@ -81,7 +90,7 @@ export class AgentTool {
 		ctx: any,
 	) {
 		// Ensure we have UI context for widget rendering
-		this.runtime.setUICtx(ctx.ui as UICtx);
+		this.widget.setUICtx(ctx.ui as UICtx);
 
 		// Reload custom agents so new .pi/agents/*.md files are picked up without restart
 		this.registry.reload();
@@ -131,7 +140,7 @@ export class AgentTool {
 		if (config.execution.runInBackground) {
 			return spawnBackground(
 				this.manager,
-				this.runtime,
+				this.widget,
 				this.runtime.agentActivity,
 				{ config, snapshot, parentSession, settings: this.settings },
 			);
@@ -140,7 +149,7 @@ export class AgentTool {
 		// ---- Foreground execution — stream progress via onUpdate ----
 		return runForeground(
 			this.manager,
-			this.runtime,
+			this.widget,
 			this.runtime.agentActivity,
 			{ config, snapshot, parentSession },
 			signal,
@@ -227,7 +236,7 @@ Guidelines:
 				),
 			}),
 
-			// ---- Custom rendering: Claude Code style ----
+			// ---- Custom rendering: inline subagent results ----
 
 			renderCall(args: Record<string, unknown>, theme: any) {
 				const displayName = args.subagent_type

package/src/ui/agent-widget.ts

@@ -84,7 +84,6 @@ export class AgentWidget {
   ) {}
 
   /** Set the UI context (grabbed from first tool execution). */
-  // fallow-ignore-next-line unused-class-member
   setUICtx(ctx: UICtx) {
     if (ctx !== this.uiCtx) {
       // UICtx changed — the widget registered on the old context is gone.
@@ -100,7 +99,6 @@ export class AgentWidget {
    * Called on each new turn (tool_execution_start).
    * Ages finished agents and clears those that have lingered long enough.
    */
-  // fallow-ignore-next-line unused-class-member
   onTurnStart() {
     // Age all finished agents
     for (const [id, age] of this.finishedTurnAge) {
@@ -184,11 +182,27 @@ export class AgentWidget {
     }
   }
 
+  /**
+   * Seed linger tracking for any newly-observed finished agent.
+   * Replaces the external `markFinished` call NotificationManager used to make:
+   * the widget owns detection of completions it sees via `listAgents()`.
+   * Idempotent — only seeds when an entry is absent, so repeated updates within
+   * a turn neither reset nor advance the age.
+   */
+  private seedFinishedAgents(agents: readonly AgentSummary[]): void {
+    for (const a of agents) {
+      if (a.completedAt && !this.finishedTurnAge.has(a.id)) {
+        this.finishedTurnAge.set(a.id, 0);
+      }
+    }
+  }
+
   /** Force an immediate widget update. */
   update() {
     if (!this.uiCtx) return;
 
     const allAgents = this.manager.listAgents();
+    this.seedFinishedAgents(allAgents);
     const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
 
     if (!state.hasActive && !state.hasFinished) {