@gotgenes/pi-subagents 6.16.0 → 6.16.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [6.16.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.16.0...pi-subagents-v6.16.1) (2026-05-23)
+
+
+### Bug Fixes
+
+* **pi-subagents:** theme parentheses and separator in formatSessionTokens ([33b67f6](https://github.com/gotgenes/pi-packages/commit/33b67f63915563c41605addb885af52b47844e96))
+
+
+### Documentation
+
+* plan split AgentWidget rendering from lifecycle ([#148](https://github.com/gotgenes/pi-packages/issues/148)) ([24c11d5](https://github.com/gotgenes/pi-packages/commit/24c11d51f2b6c9d2712815fbe46ede72084ffcbb))
+* **retro:** add retro notes for issue [#144](https://github.com/gotgenes/pi-packages/issues/144) ([f3cdfd4](https://github.com/gotgenes/pi-packages/commit/f3cdfd46fe223d6cecb5dad0d739f053e7468433))
+* update architecture for widget rendering extraction ([#148](https://github.com/gotgenes/pi-packages/issues/148)) ([450707e](https://github.com/gotgenes/pi-packages/commit/450707e1d0f41ae78f1a655ab350fd8f4fd64125))
+
 ## [6.16.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.15.0...pi-subagents-v6.16.0) (2026-05-23)
 
 

package/docs/architecture/architecture.md

@@ -69,7 +69,8 @@ renderer.ts               - notification TUI component
 record-observer.ts        - session-event observer for record statistics
 
 ui/display.ts             - pure formatters, display helpers, and shared types (Theme, AgentDetails)
-ui/agent-widget.ts        - above-editor live status widget
+ui/agent-widget.ts        - above-editor live status widget (thin lifecycle wrapper)
+ui/widget-renderer.ts     - pure rendering functions for agent widget
 ui/agent-menu.ts          - /agents slash command menu
 ui/conversation-viewer.ts - scrollable session overlay
 ui/ui-observer.ts         - session-event observer for UI streaming
@@ -615,13 +616,13 @@ Phase 9 targets the next layer: observation model consolidation, `ExtensionConte
 
 ### Current smells
 
-| Smell                                            | Location                                                              | Evidence                                                                                                                                                       | Severity |
-| ------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| `execute` does config resolution for its callees | `agent-tool.ts` (145-line `execute`)                                  | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep                                 | Medium   |
-| Wide `ctx` in menu handlers                      | `agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts` | Functions declare `ctx: ExtensionContext` but only call `ctx.ui.select/confirm/input/notify/editor`; 43 `ctx as any` casts across 3 test files                 | Medium   |
-| Direct SDK import in `conversation-viewer.ts`    | `conversation-viewer.test.ts`                                         | Hoisted `vi.mock("@earendil-works/pi-tui")` to intercept `wrapTextWithAnsi`                                                                                    | Low      |
-| Widget mixes rendering, lifecycle, and state     | `agent-widget.ts` (370 lines)                                         | `renderWidget` is ~109 lines mixing data collection, formatting, and overflow layout; constructor takes 3 concrete collaborators                               | Low      |
-| `deps.` prefix noise in function bodies          | remaining modules across tools, UI, service-adapter                   | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line                                      | Low      |
+| Smell                                            | Location                                                              | Evidence                                                                                                                                       | Severity |
+| ------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `execute` does config resolution for its callees | `agent-tool.ts` (145-line `execute`)                                  | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep                 | Medium   |
+| Wide `ctx` in menu handlers                      | `agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts` | Functions declare `ctx: ExtensionContext` but only call `ctx.ui.select/confirm/input/notify/editor`; 43 `ctx as any` casts across 3 test files | Medium   |
+| Direct SDK import in `conversation-viewer.ts`    | `conversation-viewer.test.ts`                                         | Hoisted `vi.mock("@earendil-works/pi-tui")` to intercept `wrapTextWithAnsi`                                                                    | Low      |
+| ~~Widget mixes rendering, lifecycle, and state~~ | ~~`agent-widget.ts` (370 lines)~~                                     | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                                         | Done     |
+| `deps.` prefix noise in function bodies          | remaining modules across tools, UI, service-adapter                   | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line                      | Low      |
 
 ### Dependency bag convention
 
@@ -688,13 +689,11 @@ Apply the dependency bag convention: `ConversationViewerOptions` is destructured
 
 Impact: eliminates the hoisted `vi.mock("@earendil-works/pi-tui")` in `conversation-viewer.test.ts`.
 
-### Step P: Split AgentWidget rendering (#148)
+### Step P: Split AgentWidget rendering (#148) ✓
 
-Extract pure rendering functions from `AgentWidget` into `ui/widget-renderer.ts`.
-The widget becomes a thin lifecycle/polling wrapper that calls pure render functions.
-Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle.
-
-Depends on Step L: once the tracker drops stats fields, the renderer reads from `AgentRecord` for tool uses and usage, and from `AgentActivityTracker` only for live UI state (active tools, response text, turn count).
+Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
+The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
+Rendering functions receive data (agent list, activity map, registry) and return formatted strings — testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
 
 ### Step dependencies
 

package/docs/plans/0148-split-agent-widget-rendering.md

@@ -0,0 +1,255 @@
+---
+issue: 148
+issue_title: "Split AgentWidget rendering from lifecycle (Phase 9, Step P)"
+---
+
+# Split AgentWidget rendering from lifecycle
+
+## Problem Statement
+
+`AgentWidget` (374 lines) mixes rendering, lifecycle management, spinner animation, state filtering, and status bar management in a single class.
+`renderWidget` alone is ~109 lines, and `renderFinishedLine` adds another ~40.
+The constructor takes 3 concrete collaborators (`AgentManager`, `Map<string, AgentActivityTracker>`, `AgentTypeRegistry`) with no interface extraction.
+Rendering logic cannot be unit-tested without instantiating the full widget with its lifecycle machinery.
+
+## Goals
+
+- Extract pure rendering functions from `AgentWidget` into `ui/widget-renderer.ts`.
+- Make `AgentWidget` a thin lifecycle/polling wrapper that delegates to pure render functions.
+- Enable direct unit testing of rendering logic with plain data — no widget lifecycle, no mocks for `setInterval`/`setWidget`/`requestRender`.
+
+## Non-Goals
+
+- Changing the visual output of the widget (this is a pure refactor).
+- Extracting the status bar logic into a separate module (could follow up).
+- Narrowing the `AgentManager` dependency to an interface (tracked separately in the architecture doc).
+- Injecting `truncateToWidth` (tracked as #147, Step O — an independent track).
+
+## Background
+
+### Dependency: #144 (Step L) — Consolidate observation model
+
+Issue #144 is **closed/implemented**.
+The renderer now reads stats (`toolUses`, `lifetimeUsage`, `compactionCount`) from `AgentRecord` and live UI state (`activeTools`, `responseText`, `turnCount`, `maxTurns`) from `AgentActivityTracker`.
+No dual-counting fallback exists.
+
+### Existing pure helpers
+
+`ui/display.ts` already contains stateless formatting functions (`formatMs`, `formatTurns`, `formatSessionTokens`, `describeActivity`, `getDisplayName`, `getPromptModeLabel`, `SPINNER`, `ERROR_STATUSES`, `Theme`).
+The new `widget-renderer.ts` will consume these — it does not duplicate them.
+
+### Rendering data flow
+
+The widget's `renderWidget` currently:
+
+1. Calls `this.manager.listAgents()` to get `AgentRecord[]`.
+2. Categorizes into running/queued/finished.
+3. Filters finished agents via `this.shouldShowFinished()`.
+4. Looks up `this.agentActivity.get(a.id)` for live stats.
+5. Calls `this.registry` for display names.
+6. Reads `this.widgetFrame` for spinner animation.
+7. Assembles tree-style lines with overflow logic.
+
+Steps 3–7 are pure given the right inputs.
+Steps 1–2 are also pure categorization.
+
+## Design Overview
+
+### Separation of concerns
+
+The rendering extraction splits the widget into two layers:
+
+1. **`widget-renderer.ts`** — Pure functions that accept data and return `string[]`.
+   No `this`, no timers, no SDK types, no side effects.
+2. **`agent-widget.ts`** — Thin lifecycle wrapper that owns timers, UICtx, finished-turn aging, and calls the renderer with live data.
+
+### Renderer input shape
+
+Rather than passing the full `AgentRecord` class (which carries mutation methods and phase collaborators), the renderer receives a plain data slice:
+
+```typescript
+/** Minimal agent snapshot for rendering — no class methods, no mutation surface. */
+export interface WidgetAgent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly status: string;
+  readonly description: string;
+  readonly toolUses: number;
+  readonly startedAt: number;
+  readonly completedAt?: number;
+  readonly error?: string;
+  readonly lifetimeUsage?: Readonly<LifetimeUsage>;
+  readonly compactionCount: number;
+}
+```
+
+This is structurally compatible with `AgentRecord` (the class satisfies it), so no mapping code is needed at the call site — `listAgents()` returns `AgentRecord[]` which satisfies `WidgetAgent[]`.
+
+### Renderer input for activity
+
+Activity state is read from `AgentActivityTracker`.
+The renderer needs a read-only view per agent:
+
+```typescript
+/** Read-only activity snapshot for widget rendering. */
+export interface WidgetActivity {
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+  readonly turnCount: number;
+  readonly maxTurns?: number;
+  readonly session?: SessionLike;
+}
+```
+
+`AgentActivityTracker` already satisfies this structurally (it exposes these as getters).
+
+### Agent config lookup
+
+The renderer needs `getDisplayName` and `getPromptModeLabel`, which take a `SubagentType` and an `AgentConfigLookup`.
+The renderer accepts `AgentConfigLookup` (the existing interface from `agent-types.ts`) — not the concrete `AgentTypeRegistry` class.
+
+### Renderer API
+
+```typescript
+/** Pure rendering of the widget body. Returns lines to display. */
+export function renderWidgetLines(params: {
+  agents: readonly WidgetAgent[];
+  activityMap: ReadonlyMap<string, WidgetActivity>;
+  registry: AgentConfigLookup;
+  spinnerFrame: number;
+  terminalWidth: number;
+  shouldShowFinished: (agentId: string, status: string) => boolean;
+}): string[];
+
+/** Pure rendering of a single finished agent line (no tree connector prefix). */
+export function renderFinishedLine(
+  agent: WidgetAgent,
+  activity: WidgetActivity | undefined,
+  registry: AgentConfigLookup,
+  theme: Theme,
+): string;
+
+/** Pure rendering of a single running agent (header + activity lines, no tree connector prefix). */
+export function renderRunningLines(
+  agent: WidgetAgent,
+  activity: WidgetActivity | undefined,
+  registry: AgentConfigLookup,
+  spinnerFrame: number,
+  theme: Theme,
+): [header: string, activity: string];
+```
+
+The top-level `renderWidgetLines` encapsulates the full categorization, overflow logic, and tree-connector fixup.
+The per-agent functions are exported for fine-grained testing.
+
+The `shouldShowFinished` callback is injected rather than re-implementing the aging logic inside the renderer, keeping the renderer pure and the aging state in the widget.
+
+### Call site in AgentWidget
+
+```typescript
+// Inside renderWidget(tui, theme):
+const w = tui.terminal.columns;
+return renderWidgetLines({
+  agents: this.manager.listAgents(),
+  activityMap: this.agentActivity,
+  registry: this.registry,
+  spinnerFrame: this.widgetFrame,
+  terminalWidth: w,
+  shouldShowFinished: (id, status) => this.shouldShowFinished(id, status),
+});
+```
+
+The widget's `renderWidget` method shrinks to ~5 lines.
+
+### Tell-Don't-Ask verification
+
+The renderer receives pre-collected data and returns formatted strings.
+It does not reach through collaborators — it reads flat fields from `WidgetAgent` and `WidgetActivity`.
+The widget tells the renderer "render this data"; the renderer returns lines.
+No Law of Demeter violations.
+
+## Module-Level Changes
+
+### New file: `src/ui/widget-renderer.ts`
+
+- `WidgetAgent` interface (structural subset of `AgentRecord`).
+- `WidgetActivity` interface (structural subset of `AgentActivityTracker`).
+- `renderWidgetLines()` — top-level rendering with categorization, overflow, tree connectors.
+- `renderFinishedLine()` — single finished-agent line.
+- `renderRunningLines()` — single running-agent header + activity pair.
+- Imports from `display.ts` (`SPINNER`, `ERROR_STATUSES`, `formatMs`, `formatTurns`, `formatSessionTokens`, `describeActivity`, `getDisplayName`, `getPromptModeLabel`, `Theme`), from `usage.ts` (`getLifetimeTotal`, `getSessionContextPercent`, `LifetimeUsage`, `SessionLike`), and from `@earendil-works/pi-tui` (`truncateToWidth`).
+
+### Modified: `src/ui/agent-widget.ts`
+
+- Remove `renderWidget()` method body — replace with call to `renderWidgetLines()`.
+- Remove `renderFinishedLine()` method entirely.
+- Remove direct imports of display helpers and usage helpers that are now only consumed by `widget-renderer.ts`.
+- Keep: constructor, `setUICtx`, `onTurnStart`, `ensureTimer`, `shouldShowFinished`, `markFinished`, `update`, `dispose`, `UICtx` type, `MAX_WIDGET_LINES`.
+- The inline type on `renderFinishedLine`'s parameter `a` is replaced by the `WidgetAgent` import.
+
+### New file: `test/widget-renderer.test.ts`
+
+- Unit tests for `renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`.
+- Uses plain data objects (no mocks for `AgentManager`, `setInterval`, or SDK).
+- Stub `Theme` matching the pattern in `test/renderer.test.ts`.
+
+### No changes to
+
+- `src/index.ts` — the widget is constructed the same way; renderer is internal to the widget module.
+- `src/ui/display.ts` — unchanged; consumed by the new renderer.
+- `src/usage.ts` — unchanged.
+
+## Test Impact Analysis
+
+1. The extraction enables direct unit testing of widget rendering that was previously impossible — testing `renderWidget` required constructing a full `AgentWidget` with mocked `AgentManager`, fake timers, and a stubbed UICtx.
+   The new tests cover: finished-agent line formatting (all status variants), running-agent header/activity rendering, overflow logic, tree-connector fixup, empty-state handling, and `shouldShowFinished` filtering.
+2. No existing tests become redundant — there are currently **no** unit tests for `AgentWidget` rendering.
+   The existing `display.test.ts` tests lower-level formatters and remains as-is.
+3. `renderer.test.ts` tests the notification renderer — unrelated, stays as-is.
+
+## TDD Order
+
+1. **Red → Green:** Test `renderFinishedLine` for a completed agent (success icon, stats, duration).
+   Commit: `test: add renderFinishedLine tests for completed status`
+
+2. **Red → Green:** Test `renderFinishedLine` for error/aborted/steered/stopped statuses (icon and status text variations).
+   Commit: `test: renderFinishedLine error and terminal status variants`
+
+3. **Red → Green:** Test `renderRunningLines` (spinner frame, stats, activity description, token display).
+   Commit: `test: add renderRunningLines tests`
+
+4. **Red → Green:** Test `renderWidgetLines` — basic case with one running agent (heading, tree connectors).
+   Commit: `test: renderWidgetLines single running agent`
+
+5. **Red → Green:** Test `renderWidgetLines` — mixed running + finished + queued, verifying categorization and ordering.
+   Commit: `test: renderWidgetLines mixed agent states`
+
+6. **Red → Green:** Test `renderWidgetLines` — overflow cap with many agents, verifying the priority (running > queued > finished) and overflow summary line.
+   Commit: `test: renderWidgetLines overflow behavior`
+
+7. **Red → Green:** Test `renderWidgetLines` — empty state returns `[]`; finished-only state uses dim heading.
+   Commit: `test: renderWidgetLines empty and finished-only states`
+
+8. **Green → Refactor:** Extract `renderFinishedLine`, `renderRunningLines`, and `renderWidgetLines` into `src/ui/widget-renderer.ts`.
+   All tests pass against the extracted module.
+   Commit: `refactor: extract widget rendering into widget-renderer`
+
+9. **Green → Refactor:** Wire `AgentWidget.renderWidget()` to delegate to `renderWidgetLines()`.
+   Remove the inlined rendering logic from `agent-widget.ts`.
+   Remove unused imports.
+   Commit: `refactor: AgentWidget delegates rendering to widget-renderer`
+
+10. **Verify:** Run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
+    Commit: none (verification only).
+
+## Risks and Mitigations
+
+| Risk                                                                                                           | Mitigation                                                                                                                                                                |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Structural compatibility between `AgentRecord` and `WidgetAgent` could drift if `AgentRecord` renames a field. | TypeScript's structural checking catches this at the call site in `agent-widget.ts` — `listAgents()` returns `AgentRecord[]` which must satisfy `readonly WidgetAgent[]`. |
+| `truncateToWidth` is an external dependency (`@earendil-works/pi-tui`) in the renderer.                        | Step O (#147) will inject it; for now, the renderer imports it directly, matching the current widget behavior.                                                            |
+| Overflow logic is complex and hand-tested — extraction could introduce subtle line-count bugs.                 | TDD steps 4–7 exercise overflow edge cases before the extraction step. The extraction is a mechanical move with tests already passing.                                    |
+
+## Open Questions
+
+- None — the design follows the architecture doc's Step P specification and the dependency (#144) is already implemented.

package/docs/retro/0144-consolidate-observation-model.md

@@ -0,0 +1,39 @@
+---
+issue: 144
+issue_title: "Consolidate observation model (Phase 9, Step L)"
+---
+
+# Retro: #144 — Consolidate observation model
+
+## Final Retrospective (2026-05-23)
+
+### Session summary
+
+Planned and implemented the Phase 9 Step L observation model consolidation.
+Removed dual `_toolUses`/`_lifetimeUsage` counting from `AgentActivityTracker`, added `session`/`outputFile` convenience getters to `AgentRecord`, migrated 14 callsites, and dissolved `NotificationDeps` into plain constructor parameters.
+Released as `pi-subagents-v6.16.0`.
+
+### Observations
+
+#### What went well
+
+- The plan correctly anticipated that TDD steps 4 (remove tracker stats) and 5 (migrate UI consumers) would be type-coupled and need merging.
+  This played out exactly as predicted — no surprise rework.
+- Step 2's grep sweep during `execution?.` migration found two callsites (`agent-tool.ts:315`, `agent-manager.ts:353`) that the plan's file list missed.
+  Systematic grep at migration time caught them before commit.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` — Did not load the `colgrep` skill during the planning phase despite two explicit instructions: AGENTS.md ("Use `colgrep` for intent-based codebase exploration") and the `/plan-issue` prompt ("load the `code-design` skill and the `colgrep` skill for convention discovery").
+  Loaded 4 other skills but skipped colgrep.
+  User-caught ("I noticed you didn't load or use `colgrep`").
+  Impact: one extra round-trip with the user; no rework since the plan hadn't been committed yet.
+  The colgrep searches proved useful once run — highest-scoring hit for "dependency bag converted to plain constructor parameters" was `notification.ts`, directly confirming the target.
+- `wrong-abstraction` — When editing `src/ui/ui-observer.ts` to remove the `message_end` accumulation block, the replacement text closed the `session.subscribe(...)` callback but also added the function's closing brace, producing a duplicate `}`.
+  Autoformat caught the parse error immediately.
+  Impact: one follow-up edit, no downstream rework.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's intervention on colgrep was timely — caught before plan commit, not after.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.16.0",
+  "version": "6.16.1",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/ui/agent-widget.ts

@@ -5,28 +5,11 @@
  * Uses the callback form of setWidget for themed rendering.
  */
 
-import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
 import { AgentTypeRegistry } from "../agent-types.js";
-import type { SubagentType } from "../types.js";
-import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
-import {
-  describeActivity,
-  ERROR_STATUSES,
-  formatMs,
-  formatSessionTokens,
-  formatTurns,
-  getDisplayName,
-  getPromptModeLabel,
-  SPINNER,
-  type Theme,
-} from "./display.js";
-
-// ---- Constants ----
-
-/** Maximum number of rendered lines before overflow collapse kicks in. */
-const MAX_WIDGET_LINES = 12;
+import { ERROR_STATUSES, type Theme } from "./display.js";
+import { renderWidgetLines } from "./widget-renderer.js";
 
 // ---- Types ----
 
@@ -113,176 +96,17 @@ export class AgentWidget {
     }
   }
 
-  /** Render a finished agent line. */
-  private renderFinishedLine(a: { id: string; type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string }, theme: Theme): string {
-    const name = getDisplayName(a.type, this.registry);
-    const modeLabel = getPromptModeLabel(a.type, this.registry);
-    const duration = formatMs((a.completedAt ?? Date.now()) - a.startedAt);
-
-    let icon: string;
-    let statusText: string;
-    if (a.status === "completed") {
-      icon = theme.fg("success", "✓");
-      statusText = "";
-    } else if (a.status === "steered") {
-      icon = theme.fg("warning", "✓");
-      statusText = theme.fg("warning", " (turn limit)");
-    } else if (a.status === "stopped") {
-      icon = theme.fg("dim", "■");
-      statusText = theme.fg("dim", " stopped");
-    } else if (a.status === "error") {
-      icon = theme.fg("error", "✗");
-      const errMsg = a.error ? `: ${a.error.slice(0, 60)}` : "";
-      statusText = theme.fg("error", ` error${errMsg}`);
-    } else {
-      // aborted
-      icon = theme.fg("error", "✗");
-      statusText = theme.fg("warning", " aborted");
-    }
-
-    const parts: string[] = [];
-    const activity = this.agentActivity.get(a.id);
-    if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
-    if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
-    parts.push(duration);
-
-    const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-    return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
-  }
-
-  /**
-   * Render the widget content. Called from the registered widget's render() callback,
-   * reading live state each time instead of capturing it in a closure.
-   */
+  /** Delegate rendering to the pure widget-renderer module. */
   private renderWidget(tui: any, theme: Theme): string[] {
-    const allAgents = this.manager.listAgents();
-    const running = allAgents.filter(a => a.status === "running");
-    const queued = allAgents.filter(a => a.status === "queued");
-    const finished = allAgents.filter(a =>
-      a.status !== "running" && a.status !== "queued" && a.completedAt
-      && this.shouldShowFinished(a.id, a.status),
-    );
-
-    const hasActive = running.length > 0 || queued.length > 0;
-    const hasFinished = finished.length > 0;
-
-    // Nothing to show — return empty (widget will be unregistered by update())
-    if (!hasActive && !hasFinished) return [];
-
-    const w = tui.terminal.columns;
-    const truncate = (line: string) => truncateToWidth(line, w);
-    const headingColor = hasActive ? "accent" : "dim";
-    const headingIcon = hasActive ? "●" : "○";
-    const frame = SPINNER[this.widgetFrame % SPINNER.length];
-
-    // Build sections separately for overflow-aware assembly.
-    // Each running agent = 2 lines (header + activity), finished = 1 line, queued = 1 line.
-
-    const finishedLines: string[] = [];
-    for (const a of finished) {
-      finishedLines.push(truncate(theme.fg("dim", "├─") + " " + this.renderFinishedLine(a, theme)));
-    }
-
-    const runningLines: string[][] = []; // each entry is [header, activity]
-    for (const a of running) {
-      const name = getDisplayName(a.type, this.registry);
-      const modeLabel = getPromptModeLabel(a.type, this.registry);
-      const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-      const elapsed = formatMs(Date.now() - a.startedAt);
-
-      const bg = this.agentActivity.get(a.id);
-      const tokens = getLifetimeTotal(a.lifetimeUsage);
-      const contextPercent = getSessionContextPercent(a.session);
-      const tokenText = tokens > 0 ? formatSessionTokens(tokens, contextPercent, theme, a.compactionCount) : "";
-
-      const parts: string[] = [];
-      if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns));
-      if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
-      if (tokenText) parts.push(tokenText);
-      parts.push(elapsed);
-      const statsText = parts.join(" · ");
-
-      const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
-
-      runningLines.push([
-        truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`),
-        truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
-      ]);
-    }
-
-    const queuedLine = queued.length > 0
-      ? truncate(theme.fg("dim", "├─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)
-      : undefined;
-
-    // Assemble with overflow cap (heading + overflow indicator = 2 reserved lines).
-    const maxBody = MAX_WIDGET_LINES - 1; // heading takes 1 line
-    const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
-
-    const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
-
-    if (totalBody <= maxBody) {
-      // Everything fits — add all lines and fix up connectors for the last item.
-      lines.push(...finishedLines);
-      for (const pair of runningLines) lines.push(...pair);
-      if (queuedLine) lines.push(queuedLine);
-
-      // Fix last connector: swap ├─ → └─ and │ → space for activity lines.
-      if (lines.length > 1) {
-        const last = lines.length - 1;
-        lines[last] = lines[last].replace("├─", "└─");
-        // If last item is a running agent activity line, fix indent of that line
-        // and fix the header line above it.
-        if (runningLines.length > 0 && !queuedLine) {
-          // The last two lines are the last running agent's header + activity.
-          if (last >= 2) {
-            lines[last - 1] = lines[last - 1].replace("├─", "└─");
-            lines[last] = lines[last].replace("│  ", "   ");
-          }
-        }
-      }
-    } else {
-      // Overflow — prioritize: running > queued > finished.
-      // Reserve 1 line for overflow indicator.
-      let budget = maxBody - 1;
-      let hiddenRunning = 0;
-      let hiddenFinished = 0;
-
-      // 1. Running agents (2 lines each)
-      for (const pair of runningLines) {
-        if (budget >= 2) {
-          lines.push(...pair);
-          budget -= 2;
-        } else {
-          hiddenRunning++;
-        }
-      }
-
-      // 2. Queued line
-      if (queuedLine && budget >= 1) {
-        lines.push(queuedLine);
-        budget--;
-      }
-
-      // 3. Finished agents
-      for (const fl of finishedLines) {
-        if (budget >= 1) {
-          lines.push(fl);
-          budget--;
-        } else {
-          hiddenFinished++;
-        }
-      }
-
-      // Overflow summary
-      const overflowParts: string[] = [];
-      if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
-      if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
-      const overflowText = overflowParts.join(", ");
-      lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`)
-      );
-    }
-
-    return lines;
+    return renderWidgetLines({
+      agents: this.manager.listAgents(),
+      activityMap: this.agentActivity,
+      registry: this.registry,
+      spinnerFrame: this.widgetFrame,
+      terminalWidth: tui.terminal.columns,
+      theme,
+      shouldShowFinished: (id, status) => this.shouldShowFinished(id, status),
+    });
   }
 
   /** Force an immediate widget update. */

package/src/ui/display.ts

@@ -94,7 +94,8 @@ export function formatSessionTokens(
     annot.push(theme.fg("dim", `↻${compactions}`));
   }
   if (annot.length === 0) return tokenStr;
-  return `${tokenStr} (${annot.join(" · ")})`;
+  const sep = theme.fg("dim", " · ");
+  return `${tokenStr} ${theme.fg("dim", "(")}${annot.join(sep)}${theme.fg("dim", ")")}`;
 }
 
 /** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */

package/src/ui/widget-renderer.ts

@@ -0,0 +1,236 @@
+/**
+ * widget-renderer.ts — Pure rendering functions for the agent widget.
+ *
+ * All functions are stateless: they receive data and return formatted strings.
+ * No timers, no SDK types, no side effects. Consumed by AgentWidget.
+ */
+
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "../agent-types.js";
+import type { SubagentType } from "../types.js";
+import type { LifetimeUsage, SessionLike } from "../usage.js";
+import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
+import {
+	describeActivity,
+	formatMs,
+	formatSessionTokens,
+	formatTurns,
+	getDisplayName,
+	getPromptModeLabel,
+	SPINNER,
+	type Theme,
+} from "./display.js";
+
+// ── Data interfaces ──────────────────────────────────────────────────────────
+
+/** Minimal agent snapshot for rendering — no class methods, no mutation surface. */
+export interface WidgetAgent {
+	readonly id: string;
+	readonly type: SubagentType;
+	readonly status: string;
+	readonly description: string;
+	readonly toolUses: number;
+	readonly startedAt: number;
+	readonly completedAt?: number;
+	readonly error?: string;
+	readonly lifetimeUsage?: Readonly<LifetimeUsage>;
+	readonly compactionCount: number;
+}
+
+/** Read-only activity snapshot for widget rendering. */
+export interface WidgetActivity {
+	readonly activeTools: ReadonlyMap<string, string>;
+	readonly responseText: string;
+	readonly turnCount: number;
+	readonly maxTurns?: number;
+	readonly session?: SessionLike;
+}
+
+// ── Per-agent rendering ──────────────────────────────────────────────────────
+
+/** Render a single finished agent line (no tree connector prefix). */
+export function renderFinishedLine(
+	agent: WidgetAgent,
+	activity: WidgetActivity | undefined,
+	registry: AgentConfigLookup,
+	theme: Theme,
+): string {
+	const name = getDisplayName(agent.type, registry);
+	const modeLabel = getPromptModeLabel(agent.type, registry);
+	const duration = formatMs((agent.completedAt ?? Date.now()) - agent.startedAt);
+
+	let icon: string;
+	let statusText: string;
+	if (agent.status === "completed") {
+		icon = theme.fg("success", "✓");
+		statusText = "";
+	} else if (agent.status === "steered") {
+		icon = theme.fg("warning", "✓");
+		statusText = theme.fg("warning", " (turn limit)");
+	} else if (agent.status === "stopped") {
+		icon = theme.fg("dim", "■");
+		statusText = theme.fg("dim", " stopped");
+	} else if (agent.status === "error") {
+		icon = theme.fg("error", "✗");
+		const errMsg = agent.error ? `: ${agent.error.slice(0, 60)}` : "";
+		statusText = theme.fg("error", ` error${errMsg}`);
+	} else {
+		// aborted
+		icon = theme.fg("error", "✗");
+		statusText = theme.fg("warning", " aborted");
+	}
+
+	const parts: string[] = [];
+	if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
+	if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool use${agent.toolUses === 1 ? "" : "s"}`);
+	parts.push(duration);
+
+	const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+	return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", agent.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+}
+
+/** Render a single running agent as header + activity line pair (no tree connector prefix). */
+export function renderRunningLines(
+	agent: WidgetAgent,
+	activity: WidgetActivity | undefined,
+	registry: AgentConfigLookup,
+	spinnerFrame: number,
+	theme: Theme,
+): [header: string, activity: string] {
+	const name = getDisplayName(agent.type, registry);
+	const modeLabel = getPromptModeLabel(agent.type, registry);
+	const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+	const elapsed = formatMs(Date.now() - agent.startedAt);
+
+	const tokens = getLifetimeTotal(agent.lifetimeUsage);
+	const contextPercent = activity?.session ? getSessionContextPercent(activity.session) : null;
+	const tokenText = tokens > 0 ? formatSessionTokens(tokens, contextPercent, theme, agent.compactionCount) : "";
+
+	const parts: string[] = [];
+	if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns));
+	if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool use${agent.toolUses === 1 ? "" : "s"}`);
+	if (tokenText) parts.push(tokenText);
+	parts.push(elapsed);
+	const statsText = parts.join(" · ");
+
+	const frame = SPINNER[spinnerFrame % SPINNER.length];
+	const activityText = activity ? describeActivity(activity.activeTools, activity.responseText) : "thinking\u2026";
+
+	const header = `${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", agent.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`;
+	const activityLine = theme.fg("dim", `  \u23BF  ${activityText}`);
+
+	return [header, activityLine];
+}
+
+// ── Full widget rendering ────────────────────────────────────────────────────
+
+/** Maximum number of rendered lines before overflow collapse kicks in. */
+const MAX_WIDGET_LINES = 12;
+
+/** Pure rendering of the widget body. Returns lines to display. */
+export function renderWidgetLines(params: {
+	agents: readonly WidgetAgent[];
+	activityMap: ReadonlyMap<string, WidgetActivity>;
+	registry: AgentConfigLookup;
+	spinnerFrame: number;
+	terminalWidth: number;
+	theme: Theme;
+	shouldShowFinished: (agentId: string, status: string) => boolean;
+}): string[] {
+	const { agents, activityMap, registry, spinnerFrame, terminalWidth, theme, shouldShowFinished } = params;
+
+	const running = agents.filter(a => a.status === "running");
+	const queued = agents.filter(a => a.status === "queued");
+	const finished = agents.filter(a =>
+		a.status !== "running" && a.status !== "queued" && a.completedAt
+		&& shouldShowFinished(a.id, a.status),
+	);
+
+	const hasActive = running.length > 0 || queued.length > 0;
+	const hasFinished = finished.length > 0;
+
+	if (!hasActive && !hasFinished) return [];
+
+	const truncate = (line: string) => truncateToWidth(line, terminalWidth);
+	const headingColor = hasActive ? "accent" : "dim";
+	const headingIcon = hasActive ? "\u25CF" : "\u25CB";
+
+	// Build sections separately for overflow-aware assembly.
+	const finishedLines: string[] = [];
+	for (const a of finished) {
+		finishedLines.push(truncate(theme.fg("dim", "\u251C\u2500") + " " + renderFinishedLine(a, activityMap.get(a.id), registry, theme)));
+	}
+
+	const runningLines: [string, string][] = [];
+	for (const a of running) {
+		const [header, act] = renderRunningLines(a, activityMap.get(a.id), registry, spinnerFrame, theme);
+		runningLines.push([
+			truncate(theme.fg("dim", "\u251C\u2500") + ` ${header}`),
+			truncate(theme.fg("dim", "\u2502  ") + act),
+		]);
+	}
+
+	const queuedLine = queued.length > 0
+		? truncate(theme.fg("dim", "\u251C\u2500") + ` ${theme.fg("muted", "\u25E6")} ${theme.fg("dim", `${queued.length} queued`)}`)
+		: undefined;
+
+	// Assemble with overflow cap (heading takes 1 line).
+	const maxBody = MAX_WIDGET_LINES - 1;
+	const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
+
+	const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
+
+	if (totalBody <= maxBody) {
+		lines.push(...finishedLines);
+		for (const pair of runningLines) lines.push(...pair);
+		if (queuedLine) lines.push(queuedLine);
+
+		// Fix last connector: swap \u251C\u2500 \u2192 \u2514\u2500 and \u2502 \u2192 space for activity lines.
+		if (lines.length > 1) {
+			const last = lines.length - 1;
+			lines[last] = lines[last].replace("\u251C\u2500", "\u2514\u2500");
+			if (runningLines.length > 0 && !queuedLine) {
+				if (last >= 2) {
+					lines[last - 1] = lines[last - 1].replace("\u251C\u2500", "\u2514\u2500");
+					lines[last] = lines[last].replace("\u2502  ", "   ");
+				}
+			}
+		}
+	} else {
+		// Overflow — prioritize: running > queued > finished.
+		let budget = maxBody - 1;
+		let hiddenRunning = 0;
+		let hiddenFinished = 0;
+
+		for (const pair of runningLines) {
+			if (budget >= 2) {
+				lines.push(...pair);
+				budget -= 2;
+			} else {
+				hiddenRunning++;
+			}
+		}
+
+		if (queuedLine && budget >= 1) {
+			lines.push(queuedLine);
+			budget--;
+		}
+
+		for (const fl of finishedLines) {
+			if (budget >= 1) {
+				lines.push(fl);
+				budget--;
+			} else {
+				hiddenFinished++;
+			}
+		}
+
+		const overflowParts: string[] = [];
+		if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
+		if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
+		const overflowText = overflowParts.join(", ");
+		lines.push(truncate(theme.fg("dim", "\u2514\u2500") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`));
+	}
+
+	return lines;
+}