@gotgenes/pi-subagents 17.1.0 → 17.3.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [17.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.2.0...pi-subagents-v17.3.0) (2026-06-22)
+
+
+### Features
+
+* add /subagent-sessions read-only navigation command ([#445](https://github.com/gotgenes/pi-packages/issues/445)) ([341385c](https://github.com/gotgenes/pi-packages/commit/341385cf1f0c9f5ae1d3035c5b3b34bc3e636c92))
+* add subagent session selection and live transcript source ([#445](https://github.com/gotgenes/pi-packages/issues/445)) ([7173647](https://github.com/gotgenes/pi-packages/commit/71736478c37af2c6ceaebc3ce0ee5a85e75ab1cb))
+* add typed agentMessages accessor on subagent record ([#445](https://github.com/gotgenes/pi-packages/issues/445)) ([3bd49e3](https://github.com/gotgenes/pi-packages/commit/3bd49e37feea2cca52c706f7e765b8ae934ab9fe))
+
+## [17.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.1.0...pi-subagents-v17.2.0) (2026-06-20)
+
+
+### Features
+
+* shrink agent widget to background runs only ([#444](https://github.com/gotgenes/pi-packages/issues/444)) ([76463b4](https://github.com/gotgenes/pi-packages/commit/76463b47227961226dbce5efb70a71d596fe092e))
+
+
+### Documentation
+
+* note background-only widget in README and roadmap ([#444](https://github.com/gotgenes/pi-packages/issues/444)) ([437332f](https://github.com/gotgenes/pi-packages/commit/437332fa4a1fbb2f0a0358495454847bc597ae13))
+
 ## [17.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.0.1...pi-subagents-v17.1.0) (2026-06-20)
 
 

package/README.md

@@ -61,7 +61,7 @@ Background agents return an ID immediately and notify you on completion.
 
 ## UI
 
-The extension renders a persistent widget above the editor showing all active agents:
+The extension renders a persistent widget above the editor showing active background agents (foreground runs are rendered inline by the `subagent` tool's progress stream):
 
 ```text
 ● Agents

package/docs/architecture/architecture.md

@@ -500,6 +500,9 @@ Everything else — permissions, worktree/workspace isolation, UI, telemetry —
 
 The rationale and the full reasoning chain that led here are recorded in [`docs/decisions/0002-extensions-on-a-minimal-core.md`](../decisions/0002-extensions-on-a-minimal-core.md).
 
+A separate, longer-horizon note — [`client-server-opportunities.md`](./client-server-opportunities.md) — records what Pi's eventual client-server split (Mario Zechner's session-sync unification) would unlock for pi-subagents: viewing live subagent sessions, viewing suspended ones, and operators interacting with a subagent through an editor.
+That architecture is not on the near-term roadmap; the note captures the opportunity so it is on record.
+
 ### Two extension surfaces
 
 Extensions attach through exactly two surfaces, distinguished by the direction of information flow.
@@ -966,7 +969,7 @@ Outcome: new `subagents-settings.ts` (~80 LOC) and focused command registered; `
 
 `Release: independent`
 
-### Step 3 — Shrink widget to background agents only ([#444])
+### ✅ Step 3 — Shrink widget to background agents only ([#444])
 
 Smell: Category C (coupling) — the widget shows all agents including foreground ones, duplicating the `subagent` tool's inline `onUpdate` stream for foreground runs.
 Target files:
@@ -990,16 +993,28 @@ Smell: Category C (coupling) — the bespoke `ConversationViewer` re-implements
 This step adds the new surface alongside the existing viewer; it does not touch `agent-menu.ts`.
 Target files:
 
-- New `src/ui/session-navigator.ts` (or a widget gesture, per Step 1's answer to parallel-agent navigation) — operator picks one of N background agents and views its persisted session via the spike-chosen mechanism, keyed on `record.outputFile`.
-- `src/index.ts` — register the new navigation surface (command and/or widget gesture, per the spike).
+- 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.
 
 ADR-0004 Decision B: "Tell-Don't-Ask — hand Pi the session path; Pi owns the viewer."
-Mechanism (confirmed by the Step 1 spike, [ADR-0004] addendum): a **read-only** transcript rendered from `parseSessionEntries(readFileSync(record.outputFile, "utf8"))`, surfaced through a flat command — **not** `switchSession` (a full takeover that invalidates the root's in-flight turn) and **not** `loadEntriesFromFile` (a test-only export of the SDK's `core/session-manager` module that the package's public barrel does not re-export, in both `0.79.1` and `0.79.8`).
+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).
+
+- **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`.
+
+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.
-Rendering uses Pi's own public APIs (no bespoke renderer): `parseSessionEntries` → drop the `SessionHeader` → `buildSessionContext(...).messages` → Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …) or `serializeConversation` (see the [ADR-0004] addendum, Findings 0 and 1).
 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 a child agent's persisted session through Pi's native machinery; the new surface coexists with the old viewer until 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.
+Two follow-ups complete the step behind the same seam: (a) upgrade the renderer from `serializeConversation` text to Pi's per-entry TUI components; (b) broaden the candidate set to evicted agents and add the file-snapshot source (`parseSessionEntries` → `buildSessionContext`).
+The step heading stays unchecked until both land.
 
 `Release: independent` (spike-gated)
 
@@ -1063,7 +1078,7 @@ Outcome: test clone groups ≤ 10 (from 16); `subagent-manager.test.ts` uses sha
 flowchart LR
     S1["✅ Step 1 - Spike (#446)"]
     S2["✅ Step 2 - Settings command (#447)"]
-    S3["Step 3 - Background widget (#444)"]
+    S3["✅ Step 3 - Background widget (#444)"]
     S4["Step 4 - Native session nav (#445)"]
     S5["Step 5 - Dissolve /agents + viewer (#442)"]
     S6["Step 6 - Remove definition mgmt (#441)"]

package/docs/architecture/client-server-opportunities.md

@@ -0,0 +1,127 @@
+# Client-server architecture: opportunities for pi-subagents
+
+This note is forward-looking.
+Pi's client-server split is **not on the near-term roadmap** — it is a long-term vision recorded in Mario Zechner's [pi session sync unification][session-sync] plan.
+This document captures what that architecture would let pi-subagents do, so the opportunity is on record alongside the existing [Target architecture](./architecture.md#target-architecture) section.
+
+It assumes the session-sync plan's shape:
+
+- `AgentSession` owns all authoritative intra-session state and emits all sync events.
+- `AgentSessionServer` owns multiple `AgentSession` runtimes, session lifecycle, client subscriptions, snapshots, and deltas.
+- `AgentSessionClient` is the only thing a renderer (interactive mode, web mode) talks to.
+- The sync model is **snapshot plus delta**: a client joins a session, receives one canonical snapshot, then a stream of deltas.
+- Commands go up; state deltas come down.
+- A client can `watch` (read-only) or `join` (interactive) a session, and can hold synchronized caches for many sessions at once.
+- Session lifecycle (`new`, `resume`, `fork`, `import`, `join`, `leave`, `watch`, `unwatch`) is normal server API, not hidden local runtime replacement.
+
+## The key realization
+
+A subagent **is** a child `AgentSession`. pi-subagents already creates one via `createSubagentSession`, drives its turn loop through `SubagentSession`, and disposes it.
+
+Today that child session is an in-process object visible only through machinery pi-subagents had to invent because Pi has no session-sync client:
+
+- `record-observer` re-derives live activity from raw session events.
+- the 80 ms `SubagentManager.listAgents()` widget poll.
+- the [#277] Law-of-Demeter accessors (`Subagent.getConversation()`, `.messages`, `.subscribeToUpdates()`, `.getContextPercent()`) that re-expose session internals.
+- the bespoke `ConversationViewer`, and [ADR-0004]'s replacement, native session navigation.
+- [ADR-0004]'s dual-source-by-liveness split (tracked agent → in-memory record; evicted → file snapshot).
+
+Every one of those is pi-subagents reinventing an `AgentSessionClient`.
+The session-sync plan supplies the real one.
+If subagent child sessions are registered as first-class sessions in the `AgentSessionServer`, all three target capabilities reduce to the same primitive the operator's own session already uses: `watch`/`join` a session id, receive a snapshot, then a delta stream.
+
+## Capability 1 — viewing live subagent sessions
+
+`watchSession(subagentSessionId)` gives the operator's client a canonical `SessionSnapshot` (current streaming message, pending tool executions with partial results, queue contents, context usage, active tools) followed by the live delta stream (`message_update`, `tool_execution_start/update/end`, `turn_start/end`).
+
+What changes versus today:
+
+1. **Late-join correctness.**
+   The snapshot carries in-flight state, so an operator attaching to an already-running subagent immediately sees its current streaming message and pending tools — not just future events.
+   Today the conversation viewer only catches future deltas plus whatever happens to be in the in-memory record.
+2. **The widget and viewer become thin renderers** of synchronized session state.
+   The 80 ms poll, `record-observer`, and the [#277] accessors disappear — they were all substitutes for `subscribeSession`.
+3. **A unified, reconnect-safe live session list.**
+   The global event scope (`session_created`, `session_status_changed` idle/busy) means the operator sees every subagent the instant it spawns, with a live status badge per agent — replacing both `listAgents()` polling and the hand-rolled `subagents:*` broadcast tier.
+4. **Multi-session client state** lets one operator client hold synchronized caches for N subagents at once.
+   This is the clean foundation for the parallel-agent navigation gesture that [ADR-0004]'s spike (entry-criterion #3) struggled to design — tabbed or split views of multiple live subagents fall out of the model with no redesign.
+
+## Capability 2 — viewing suspended subagent sessions
+
+Today "suspended" is a dead end: once a background subagent completes and `disposeSession()` fires, the live `AgentSession` is gone, and the only artifact is the persisted JSONL read one-shot via `parseSessionEntries`.
+That is a static file dump with no liveness and no path back to interaction.
+
+Under the server model, the live/suspended distinction collapses at the client.
+Session lifecycle is normal server API (`resume_session`, `join_session`, `import_session`), so a suspended subagent is just a session the server can rehydrate from `SessionManager` on demand:
+
+1. The operator calls `joinSession(id)` (or the server lazily reloads the `AgentSession` from JSONL when a client joins a dormant session), gets a snapshot, and renders it through the same components as a live session.
+   [ADR-0004]'s two-code-path split (in-memory record vs file snapshot) stops being the client's problem — whether the session is resident or rehydrated is the server's private concern.
+2. A genuinely paused subagent (one parked by the `ConcurrencyLimiter` awaiting capacity, or deliberately held) becomes representable: the server holds the runtime idle, the operator can `watch` its frozen state, and then sees it transition to `busy` via `session_status_changed` when capacity frees up.
+3. Subagents can outlive the operator's TUI.
+   Because the server is a separate process, if the operator's interactive client restarts it reconnects and re-lists or re-joins subagent sessions that survived — impossible in today's single-process model.
+
+## Capability 3 — operators interacting via an editor and submitting messages
+
+Today the only inbound channel to a running subagent is `steer_subagent` — a single buffer-or-deliver message through `Subagent.steer`.
+No editor, no takeover, no real conversation.
+
+The plan's `join` versus `watch` split is the right primitive:
+
+1. **`watch` is read-only** (Capability 1).
+   **`join` is interactive participation**: the operator's client sends session commands scoped to the subagent's session id — `prompt`, `abort`, `set model`, `set thinking level`, `set active tools`, `navigate tree`, `compact`, `run bash`.
+2. **Editor flow.**
+   The operator opens the subagent session in their client, types in the editor (editor text, focus, and overlays are explicitly client-local UI state, never synchronized), and submits a `prompt` command targeting the subagent's session id.
+   The command goes up; the server applies it to the subagent's `AgentSession` (which already owns prompt submission, queued steering, and follow-up messages); canonical deltas flow back down to all subscribers.
+   This is precisely "commands go up, state deltas come down," applied to a subagent session instead of the operator's own.
+3. **`steer` generalizes into the full command surface.**
+   pi-subagents' bespoke buffer-or-deliver logic (`Subagent.steer` rejecting when not running) is subsumed by `AgentSession`'s queued-steering machinery, and the custom buffering becomes redundant.
+4. **Multiple clients on one session.**
+   The plan supports this explicitly, with deltas broadcast to all subscribers including the initiator, so an operator can jump into a subagent the parent agent spawned, inject guidance, and the parent's view stays consistent.
+5. **Fork and rewind, not just append.**
+   `navigate tree` plus `fork_session` let an operator rewind a subagent or fork it at an entry — full session editing, far beyond appending a steer message.
+
+## What pi-subagents itself becomes
+
+This validates and sharpens the direction the architecture doc is already heading. pi-subagents' stated core job — spawn a child session derived from the parent, run the turn loop, track and stream and collect the result, gate concurrency, support resume, and publish its lifecycle — is almost exactly the `AgentSessionServer`'s job for child sessions.
+
+- **The observation tier dissolves.**
+  This confirms [Phase 18]'s own finding that "the activity/metrics push tier is provisional" — under the server it genuinely does not need to exist in pi-subagents.
+- **The recursion principle gets its real substrate.**
+  The architecture doc's "a subagent is a recursive Pi" framing maps directly onto the plan's session model: a subagent session is just another session in the server, with the same snapshot, delta, and command surface.
+- **pi-subagents keeps only its semantic layer** — agent type, description, result text, token totals, concurrency admission, and the recursion guard — the things a generic session server does not know.
+  The liveness and activity channel rides on session sync instead of a hand-rolled broadcast.
+
+### Bespoke machinery the server would retire
+
+| Today (pi-subagents reinvents it)                                        | Under the server architecture                              |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `record-observer` re-deriving live activity                              | `subscribeSession` delta stream                            |
+| 80 ms `listAgents()` widget poll                                         | `session_created` / `session_status_changed` global events |
+| [#277] accessors (`messages`, `subscribeToUpdates`, `getContextPercent`) | `SessionSnapshot` + deltas                                 |
+| `ConversationViewer` / native session navigation                         | client renders the snapshot through Pi's own components    |
+| dual-source-by-liveness split                                            | server rehydrates; client sees one session shape           |
+| `steer_subagent` buffer-or-deliver                                       | `join` + `prompt` / queued-steering commands               |
+| `subagents:*` activity broadcasts                                        | session sync (semantic events stay; liveness moves)        |
+
+## Prerequisites and open questions
+
+Being honest about the constraints the plan itself raises:
+
+1. **Registry-local provider state is a hard prerequisite** (the plan states this explicitly).
+   Subagents run in-process under a multi-session server — exactly the scenario where process-global provider registration would corrupt one session's model view from another's extension load. pi-subagents is well-positioned (it already snapshots model and registry into `ParentSnapshot`), but the underlying Pi change must land first.
+2. **The recursion guard stays pi-subagents' invariant.**
+   A subagent session created through the server must still have pi-subagents' three tools stripped, and an operator-joined subagent must not be able to spawn observers of itself in a loop.
+3. **Workspace context must travel in the snapshot.**
+   Subagents can run in a different cwd or git worktree (`pi-subagents-worktrees`).
+   The plan's `SessionSnapshot.cwd` field already accounts for this, so an operator's client renders and interacts in the correct workspace.
+4. **Operator-submitted versus parent-submitted command permissions.**
+   Commands an operator joins and submits flow through the subagent's `AgentSession`, so pi-permission-system's in-child gating still applies — but whether an operator's `run bash` or `prompt` should carry a different permission posture than the parent agent's is a genuine open design question, not something to assume.
+
+## Net assessment
+
+This architecture turns all three capabilities from bespoke, fragile features pi-subagents must build and maintain into thin clients of one uniform session-sync surface — and in doing so lets pi-subagents shed most of the observation infrastructure it only built because that surface did not exist yet.
+
+[session-sync]: https://jot.mariozechner.at/s/zgzbq9n4f4mfck
+[ADR-0004]: ../decisions/0004-reconsider-ui-direction.md
+[Phase 18]: ./architecture.md#phase-18-complete
+[#277]: https://github.com/gotgenes/pi-packages/issues/277

package/docs/decisions/0004-reconsider-ui-direction.md

@@ -214,6 +214,40 @@ Reject the tentative `/subagents:settings` and the `/agents-settings` alternativ
 
 This keeps bespoke transcript rendering out of the package (rendering is Pi's own public components), adds no inbound call from the UI to the core, and preserves the Phase 18 spine invariants (#422–#425).
 
+## Addendum 2 (2026-06-20): Step 4 sourcing — live record plus file snapshot ([#445])
+
+This addendum revises the first addendum's Criterion 2 answer for Step 4 ([#445]).
+The "strictly read-only, file-only" sourcing and the "not a live overlay" framing are superseded by the dual-source decision below; everything else from the spike stands.
+
+**Why revise.**
+The spike's mechanism — `parseSessionEntries(readFileSync(record.outputFile))` read once — serves a _completed_ subagent well but is a frozen snapshot for a _running_ one: it shows only what was flushed to disk at open time and does not stream.
+The clarified desired behavior is to see the **live** activity of any subagent _and_ the activity of a completed subagent.
+The bespoke `ConversationViewer` being removed in Step 5 already delivers both — it subscribes to the live in-memory record (`record.subscribeToUpdates()`) and renders `record.messages` plus a streaming indicator built from `record.activeTools` / `record.responseText`.
+That liveness comes from the in-memory record, not the persisted file, so a file-only viewer drops it.
+
+**Decision — dual-source, one renderer.**
+Step 4 sources the transcript by liveness and renders both sources through the same Pi public entry components (Finding 1 holds — no bespoke renderer):
+
+- **Tracked agent (still in `manager.listAgents()`)** — render from the live 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.
+  This is live.
+- **Evicted / untracked agent** — render from the file snapshot: `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` (Findings 0 and 1).
+
+Both sources yield `AgentMessage[]`, so a single Pi-component renderer serves both.
+
+**Type-boundary note.**
+`SubagentSession.messages` is deliberately widened to `readonly unknown[]` at the core boundary (`src/lifecycle/subagent-session.ts`), even though the underlying `_session.messages` is the SDK's `AgentMessage[]`.
+Step 4 should add a typed accessor that returns `AgentMessage[]` (or narrow at the boundary) rather than feeding `unknown[]` into Pi's components.
+This is a read accessor on the existing record — it adds no inbound call from the UI to the core and does not regress the Phase 18 spine invariants.
+
+**Still read-only (non-interactive).**
+The viewer remains strictly non-interactive: Criterion 2's anti-redundant-steering rationale stands (steering lives in the `steer_subagent` tool and the widget), and Criterion 1's rejection of `switchSession` is unchanged — "live" here means the in-memory subscription, not an active-session takeover.
+
+**Candidate set (revises Criterion 3).**
+The selection command lists **any subagent with a live record or a persisted session file** — foreground agents included, not only running background agents.
+This matches the bespoke viewer's current reach (gated on `record.isSessionReady()`, never background-filtered) and avoids an interim regression.
+A foreground agent is navigable only _after_ it completes — while it runs, the root turn is blocked on it — whereas a background agent is navigable live.
+The background widget ([#444]) remains the optional secondary selection gesture for background agents; the command is the primary, unit-testable surface.
+
 [#444]: https://github.com/gotgenes/pi-packages/issues/444
 [#445]: https://github.com/gotgenes/pi-packages/issues/445
 [#446]: https://github.com/gotgenes/pi-packages/issues/446

package/docs/plans/0444-shrink-widget-to-background-agents.md

@@ -0,0 +1,156 @@
+---
+issue: 444
+issue_title: "pi-subagents: shrink the agent widget to background runs only"
+---
+
+# Shrink the agent widget to background runs only
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 3 ([architecture roadmap][arch]) is tagged `Release: independent` — it is not a member of any release batch.
+The change is self-contained to `agent-widget.ts` and its tests, touches no public surface, and ADR-0004 explicitly notes it is "independent of the spike."
+
+## Problem Statement
+
+The above-editor agent widget currently renders every agent — foreground and background alike.
+For foreground runs the `subagent` tool's inline `onUpdate` stream already renders live progress, so the widget duplicates that display (ADR-0004 Decision A).
+The widget should survive only as the **background-agent status surface**: the one place with no inline tool-call display, which must represent N parallel background agents at once.
+
+There is also a latent inconsistency to fix.
+`AgentWidget` calls `manager.listAgents()` at two sites — `update()` (which feeds `seedFinishedAgents`, `assembleWidgetState`, and `clearWidget`) and `renderWidget()` (the tree map).
+Filtering at only one site would leave the other rendering foreground agents.
+
+## Goals
+
+- The widget shows only background agents (`record.invocation?.runInBackground === true`); foreground agents never appear.
+- Both `listAgents()` call sites are funneled through a single private accessor that applies the background predicate once at the source.
+- The foreground/widget duplication called out by ADR-0004 Decision A is eliminated.
+- This is a UI behavior refinement, not a public-API or config change — it is **non-breaking** (no exported surface, default, or config shape changes on upgrade).
+
+## Non-Goals
+
+- Relabeling the widget heading from `Agents` to `Background agents` (see Open Questions) — not requested; keep scope tight.
+- Any change to `widget-renderer.ts` rendering logic — it has no foreground-specific path; the fix lives entirely at the data source in `agent-widget.ts`.
+- Other `listAgents()` consumers (`agent-menu.ts`) — those are removed wholesale by Phase 19 Step 5 ([#442]), out of scope here.
+- Native session navigation ([#445], Step 4) and the `/subagents-settings` extraction ([#447], Step 2).
+
+## Background
+
+Relevant modules:
+
+- `src/ui/agent-widget.ts` — `AgentWidget implements SubagentManagerObserver`; self-drives an 80 ms render loop from lifecycle events (Step 4 self-drive, [#423]).
+  `update()` reads `manager.listAgents()` into a local `allAgents`, then passes it to `seedFinishedAgents()`, `assembleWidgetState()`, and (on the idle path) `clearWidget()`.
+  `renderWidget(tui, theme)` independently calls `manager.listAgents().map(r => this.toWidgetAgent(r))` to build the tree.
+- `src/ui/widget-renderer.ts` — pure rendering; `renderWidgetLines()` categorizes agents into running/queued/finished and emits tree lines.
+  It has no knowledge of foreground vs. background — it renders whatever list it receives.
+- `Subagent.invocation` (`src/lifecycle/subagent.ts`) — a readonly `AgentInvocation | undefined` set once at construction.
+  `AgentInvocation.runInBackground` (`src/types.ts`) is the reliable signal: set by `spawn-config.ts` → `AgentInvocation.runInBackground` → stored on `Subagent.invocation`.
+- `AgentSummary` (in `agent-widget.ts`) — the minimal `{ id, status, completedAt }` shape consumed by `assembleWidgetState`/`clearWidget`.
+  `Subagent` is structurally assignable to it, so the accessor can return `Subagent[]` without an interface change.
+
+Constraint from AGENTS.md / package skill: pi-subagents is a minimal core; this is a consumer-side UI behavior change with no policy or core impact.
+
+## Design Overview
+
+Introduce one private accessor on `AgentWidget` and route both existing call sites through it:
+
+```typescript
+/** Background agents only — the widget's sole audience (ADR-0004 Decision A). */
+private listBackgroundAgents(): Subagent[] {
+  return this.manager
+    .listAgents()
+    .filter(record => record.invocation?.runInBackground === true);
+}
+```
+
+Call-site changes:
+
+- `update()` — replace `const allAgents = this.manager.listAgents();` with `const backgroundAgents = this.listBackgroundAgents();` and rename the downstream references (`seedFinishedAgents`, `assembleWidgetState`, `clearWidget`).
+- `renderWidget()` — replace `this.manager.listAgents().map(...)` with `this.listBackgroundAgents().map(...)`.
+
+The predicate `record.invocation?.runInBackground === true` is applied exactly once, at the funnel.
+`undefined` invocation (or `runInBackground` absent/false) is treated as foreground and excluded.
+
+Edge cases verified:
+
+- **`clearWidget` stale-purge:** it deletes `finishedTurnAge` entries for IDs "no longer in the list."
+  Because `seedFinishedAgents` only ever seeds from the background-filtered list, no foreground agent is ever tracked, so purging against the background-only list cannot drop a still-relevant entry — no behavior regression.
+- **Queued agents:** the concurrency limiter queues only background agents (foreground bypasses the queue), so they carry `runInBackground === true` and remain visible; the queued-count display stays accurate.
+- **All-foreground case:** `update()` sees an empty background list → `assembleWidgetState` reports no active/finished → `clearWidget` → widget never registers. `renderWidget()` is consequently never invoked.
+- **Mixed case (the latent bug):** one background running + one foreground running → `update()` registers the widget (1 background active); `renderWidget()` must also filter, or it renders both.
+  Routing both sites through the accessor closes this.
+
+## Module-Level Changes
+
+- `src/ui/agent-widget.ts` — add private `listBackgroundAgents()`; route `update()` and `renderWidget()` through it; rename the `update()` local `allAgents` → `backgroundAgents`.
+- `src/ui/widget-renderer.ts` — **no change.**
+  Verified there is no foreground-specific rendering path; filtering at the data source is sufficient.
+  Listed only to record the verification.
+- `test/ui/agent-widget.test.ts` — migrate existing widget fixtures to set `invocation: { runInBackground: true }` (otherwise the new filter excludes them); add background-only filtering tests.
+- `packages/pi-subagents/README.md` — line ~64, change "showing all active agents" → "showing active background agents" (stale prose once foreground is excluded).
+- `packages/pi-subagents/docs/architecture/architecture.md` — mark Step 3 ✅ with a `Landed`/`Outcome` note; the `src/ui/agent-widget.ts` tree caption at line ~342 stays accurate (generic "live status widget").
+
+Grep sweep performed for stale references to "all agents" / "showing all active agents" across `src/`, `test/`, `.pi/skills/package-pi-subagents/SKILL.md`, and `docs/`:
+
+- `README.md:64` — stale, updated above.
+- `.pi/skills/package-pi-subagents/SKILL.md:57` ("widget ─polls─→ Subagent records (listAgents)") — still accurate (it does poll `listAgents`, now filtered); no edit.
+- `docs/comparison-with-upstream.md:29`, `architecture.md:342` — generic "live above-editor widget"; remain accurate.
+
+## Test Impact Analysis
+
+1. **New tests enabled by the change:**
+   - `update()` excludes foreground agents — an all-foreground agent list leaves the widget unregistered (`lastContent()` undefined).
+   - `renderWidget()` excludes foreground agents — a mixed background+foreground list renders only the background agent's description in the tree (the foreground description is absent).
+     This pins the previously-latent two-site inconsistency.
+2. **Tests that become redundant:** none are removed.
+   The existing widget-behavior fixtures (`makeWidget` in the two `describe` blocks, plus the projection test's `createTestSubagent`) are migrated to set `invocation: { runInBackground: true }` so they continue to exercise the same lifecycle/seeding/self-drive behavior under the new filter.
+3. **Tests that must stay as-is:** the `assembleWidgetState` pure-function suite — it calls the pure function directly with `AgentSummary[]`, not through the accessor, so it is unaffected by the filter and continues to pin the counting logic.
+
+## Invariants at risk
+
+This step touches `agent-widget.ts`, which prior phases already refactored.
+The fixture migration must keep these invariants pinned (the tests stay, only their `invocation` field is added):
+
+- **Self-drive from lifecycle ([#423]):** `onSubagentStarted`/`onSubagentCreated` start the 80 ms timer and render; `onSubagentCompleted`/`onSubagentCompacted` render.
+  Pinned by the "self-drives from lifecycle notifications" describe block — fixtures migrated to background invocation so the manager stub's agents survive the filter.
+- **`seedFinishedAgents` idempotency / linger aging ([#374]):** finished agents seed once, age out after 1 turn (errors after 2), and `update()` never advances the age without a turn.
+  Pinned by the "update self-seeds finished agents" describe block — fixtures migrated to background invocation.
+
+A later step must not regress these with a green suite; the migration preserves the assertions verbatim apart from the `invocation` field.
+
+## TDD Order
+
+1. **`test:` migrate widget fixtures to background invocation (preparatory / tidy-first).**
+   Surface: `test/ui/agent-widget.test.ts`.
+   Add `invocation: { runInBackground: true }` to the `makeWidget` agent stubs (both `describe` blocks) and to the projection test's `createTestSubagent` call.
+   No production change — the filter does not exist yet, so the field is inert and the suite stays green.
+   This makes the next step a clean addition rather than a mass fixture rewrite.
+   Commit: `test: set background invocation on agent-widget fixtures (#444)`.
+2. **`feat:` filter the widget to background agents only.**
+   Red: add (a) an all-foreground list leaves the widget unregistered, and (b) a mixed background+foreground list renders only the background agent in `renderWidget()`.
+   Green: add the private `listBackgroundAgents()` accessor; route both `update()` and `renderWidget()` through it; rename the `update()` local to `backgroundAgents`.
+   Commit: `feat: shrink agent widget to background runs only (#444)`.
+3. **`docs:` update widget docs for background-only behavior.**
+   Update `README.md` ("all active agents" → "active background agents") and mark Phase 19 Step 3 ✅ with a `Landed`/`Outcome` note in `docs/architecture/architecture.md`.
+   Commit: `docs: note background-only widget in README and roadmap (#444)`.
+
+## Risks and Mitigations
+
+- **Mass test breakage when the filter lands** — every `update()`-driven fixture would be filtered out and assertions would fail.
+  Mitigation: TDD step 1 migrates all fixtures first (inert until the filter exists), so step 2 only adds new tests.
+- **A foreground agent the operator expected to see disappears** — intended per ADR-0004 Decision A; the inline `onUpdate` stream is authoritative for foreground runs.
+- **`clearWidget` stale-purge dropping a relevant entry** — analyzed in Design Overview; foreground agents are never seeded, so purging against the background-only list is correct.
+
+## Open Questions
+
+- Should the widget heading read `Background agents` instead of `Agents`?
+  Deferred — not in the issue scope; revisit if the bare label reads as ambiguous in practice.
+
+[arch]: ../architecture/architecture.md
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#374]: https://github.com/gotgenes/pi-packages/issues/374