@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0423-widget-self-drive-from-lifecycle.md

@@ -1,264 +0,0 @@
----
-issue: 423
-issue_title: "pi-subagents: make the agent widget self-drive from lifecycle events"
----
-
-# Make the agent widget self-drive from lifecycle events
-
-## Problem Statement
-
-Today the dependency arrow points the wrong way: the core spawn tools reach into the widget to drive it.
-`foreground-runner.ts` calls `widget.ensureTimer()` (inside its `onSessionCreated` callback) and `widget.markFinished(fgId)` after completion; `background-spawner.ts` calls `widget.ensureTimer()` and `widget.update()` after spawn.
-For the widget to be a clean reactive consumer of the core — and for the spawn tools to shed their widget dependency — the widget must subscribe to lifecycle signals and manage its own update timer.
-This is the fourth step of the Phase 18 spine (widget/tool decoupling track), enabled by Step 3 ([#422]) removing the activity map and the second session subscription.
-
-## Goals
-
-- Make `AgentWidget` a `SubagentManagerObserver`: start its 80 ms update timer in response to `onSubagentStarted` / `onSubagentCreated`, and re-render on `onSubagentCompleted` / `onSubagentCompacted`.
-- Wire the widget as a second lifecycle consumer alongside `SubagentEventsObserver` via a new `CompositeSubagentObserver` that fans out manager notifications — keeping `SubagentManager`'s single-observer contract closed for modification.
-- Remove all inbound widget calls from the spawn tools (`ensureTimer` / `update` / `markFinished`) and drop the `ForegroundWidgetDeps` / `BackgroundWidgetDeps` parameters from both spawners.
-- Narrow `AgentToolWidget` to the single method the tool still uses (`setUICtx`); UICtx capture stays in `ToolStartHandler` and `AgentTool`.
-- Delete the now-redundant `AgentWidget.markFinished` (its bookkeeping is already covered by `seedFinishedAgents`) and make `ensureTimer` private.
-
-This is **not** a breaking change.
-The widget, the spawn tools, the observer interface, and `AgentToolWidget` are all internal symbols — none appear in the public service surface (`src/service/service.ts`) or the settings entry (`src/layered-settings.ts`).
-Observable widget behavior is unchanged (the timer starts when an agent appears, renders, and self-clears when idle); commits use `refactor:` / `docs:`.
-
-## Non-Goals
-
-- Dropping the `widget` constructor param from `AgentTool` entirely and the widget/map stubs from `createToolDeps` — that is Phase 18 Step 5 ([#424]).
-  This step only narrows `AgentToolWidget` to `setUICtx`; the param stays.
-- Migrating the widget to subscribe to the public `pi.events` (`subagents:*`) broadcast channels instead of the internal observer.
-  The event-bus surface is the substitutable-UI direction, but it depends on the public event-contract reconciliation in Step 6 ([#425]) and the UI-distribution decision in Step 8 ([#427]); using it now would front-run an unreconciled contract.
-  Option A (the composite observer) keeps a later `pi.events` migration to a localized `index.ts` swap.
-- Touching `record-observer.ts`, `SubagentState`, the record getters, or the `SubagentEventsObserver` event/notification dispatch.
-- Changing the foreground streaming path: `runForeground`'s `onSessionCreated` keeps binding `recordRef` for the `onUpdate` stream.
-
-## Background
-
-Relevant modules and their current relationships:
-
-- `src/ui/agent-widget.ts` — `AgentWidget` polls `manager.listAgents()` every 80 ms via a `setInterval` started by `ensureTimer()`.
-  `update()` is idempotent: it self-seeds any finished agent into `finishedTurnAge` via `seedFinishedAgents()` (added in [#421] / [#422]), renders, and self-clears the timer through `clearWidget()` when no agents are active or lingering.
-  `markFinished(id)` and `ensureTimer()` carry `fallow-ignore-next-line unused-class-member` because their only callers are the spawn tools (via narrow interfaces).
-- `src/lifecycle/subagent-manager.ts` — exposes a single `observer?: SubagentManagerObserver` slot (four methods: `onSubagentStarted`, `onSubagentCreated`, `onSubagentCompleted`, `onSubagentCompacted`).
-  `buildObserver()` adapts it into a per-agent `SubagentLifecycleObserver`.
-  `onSubagentStarted` fires for both foreground and background (on `record.start()`); `onSubagentCreated` fires only for background (in `spawn()`); `onSubagentCompleted` fires **only for background** (`onRunFinished` guards on `options.isBackground`).
-- `src/observation/subagent-events-observer.ts` — the sole current observer; dispatches `pi.events` lifecycle events, session-entry persistence, and completion notifications.
-- `src/tools/foreground-runner.ts` / `src/tools/background-spawner.ts` — drive the widget via `ForegroundWidgetDeps` / `BackgroundWidgetDeps`.
-- `src/tools/agent-tool.ts` — holds a 4-method `AgentToolWidget` (`setUICtx`, `ensureTimer`, `update`, `markFinished`), passes the widget into both spawners, and calls `this.widget.setUICtx(ctx.ui)`.
-- `src/index.ts` — constructs `observer` (the events observer), passes it to the manager, then constructs `widget` after the manager (the widget needs `manager.listAgents()`).
-
-Key behavioral facts that shape the design:
-
-- **Foreground completion is not observed.**
-  The manager never calls `onSubagentCompleted` for foreground agents, so the widget cannot learn of foreground completion through the observer.
-  It does not need to: `seedFinishedAgents()` already seeds any agent with `completedAt` on the next poll tick, so `markFinished` is fully redundant and is removed.
-- **The widget keeps its `manager` reference.**
-  Rendering still reads `manager.listAgents()`; the observer only changes the *trigger* that starts the timer, not the data source.
-  Full broadcast-plus-query decoupling is the Step 8 concern, deliberately out of scope here.
-
-AGENTS.md / package constraints that apply:
-
-- pi-subagents is a narrow core that is open for extension, closed for modification — dependency arrows point inward.
-  A composite observer in the composition root (`index.ts`) keeps `SubagentManager` untouched, rather than teaching the core to fan out to N consumers.
-- Run `pnpm fallow dead-code` before pushing — privatizing `ensureTimer` and deleting `markFinished` change the dead-code surface.
-
-## Design Overview
-
-### CompositeSubagentObserver (new collaborator)
-
-A small fan-out observer lets the manager keep its single-observer contract while several independent consumers subscribe.
-It lives next to the existing observer in `src/observation/`.
-
-```typescript
-// src/observation/composite-subagent-observer.ts
-export class CompositeSubagentObserver implements SubagentManagerObserver {
-  private readonly delegates: SubagentManagerObserver[];
-  constructor(delegates: SubagentManagerObserver[]) {
-    this.delegates = [...delegates];
-  }
-  /** Register an additional observer (breaks the widget↔manager construction cycle). */
-  add(observer: SubagentManagerObserver): void {
-    this.delegates.push(observer);
-  }
-  onSubagentStarted(record: Subagent): void {
-    this.forEach((o) => o.onSubagentStarted(record), "onSubagentStarted");
-  }
-  // …onSubagentCreated / onSubagentCompleted / onSubagentCompacted follow the same shape…
-  private forEach(call: (o: SubagentManagerObserver) => void, label: string): void {
-    for (const o of this.delegates) {
-      try { call(o); } catch (err) { debugLog(`CompositeSubagentObserver.${label}`, err); }
-    }
-  }
-}
-```
-
-Each delegate is isolated in a `try`/`catch` so a widget render throw cannot suppress event emission, and vice versa.
-The `add` method exists to break the construction cycle (see wiring below), not as speculative flexibility — `index.ts` is its only caller.
-
-### Consumer call site (index.ts wiring)
-
-The widget needs the manager (for `listAgents()`) and the manager needs the observer, so the composite is constructed first, the widget is registered after construction:
-
-```typescript
-const eventsObserver = new SubagentEventsObserver({ /* emit, appendEntry, notifications */ });
-const observer = new CompositeSubagentObserver([eventsObserver]);
-const manager = new SubagentManager({ /* …, */ observer /* , … */ });
-// …
-const widget = new AgentWidget(manager, registry);
-observer.add(widget); // the manager consults `observer` only at spawn time, after this runs
-```
-
-The manager reads `this.observer` lazily (only at `spawn` / `spawnAndWait`), so registering the widget after construction is safe — no notification can fire before `observer.add(widget)` executes.
-
-### AgentWidget as a reactive observer
-
-`AgentWidget implements SubagentManagerObserver`.
-It ignores the `record` argument (it re-reads `listAgents()`), reacting by intent rather than by payload:
-
-```typescript
-// react to lifecycle, self-drive the timer
-onSubagentStarted(_record: Subagent): void { this.startLoop(); }
-onSubagentCreated(_record: Subagent): void { this.startLoop(); }
-onSubagentCompleted(_record: Subagent): void { this.update(); }
-onSubagentCompacted(_record: Subagent, _info: CompactionInfo): void { this.update(); }
-
-private startLoop(): void { this.ensureTimer(); this.update(); }
-```
-
-`startLoop` (started / created) starts the timer and renders; completed / compacted only `update()` because the timer is already running by then (started fires at spawn, created fires before the queued run).
-`update()` self-seeds the finished agent and keeps the timer alive for the linger window, then `clearWidget()` stops it once idle — unchanged from today.
-`ensureTimer()` becomes `private` (now called from `startLoop`, so it loses its `fallow-ignore`); `markFinished` is deleted.
-
-This follows the `SubagentEventsObserver` precedent: a class that implements `SubagentManagerObserver` and is invoked polymorphically by the manager counts as used, so the new methods need no `fallow-ignore`.
-
-### Extracted-from / upstream check
-
-This extraction introduces no Tell-Don't-Ask or output-argument violations: the widget reads `listAgents()` (a query it already owns) and mutates only its own `finishedTurnAge` / timer state.
-The composite only forwards calls; it holds no state beyond its delegate list and never reaches through a delegate.
-
-## Module-Level Changes
-
-Source:
-
-- `src/observation/composite-subagent-observer.ts` — **new.**
-  `CompositeSubagentObserver implements SubagentManagerObserver`; constructor takes a delegate array; `add()` appends; each method fans out through a private `forEach` with per-delegate `try`/`catch` + `debugLog`.
-- `src/ui/agent-widget.ts` — add `implements SubagentManagerObserver`; add `onSubagentStarted` / `onSubagentCreated` / `onSubagentCompleted` / `onSubagentCompacted` and the private `startLoop`; make `ensureTimer` `private` and drop its `fallow-ignore`; delete `markFinished` and its `fallow-ignore`; import `SubagentManagerObserver` and `CompactionInfo` types; reword the `seedFinishedAgents` doc comment so it no longer references the removed `markFinished` method.
-- `src/index.ts` — rename the events-observer local to `eventsObserver`; construct `const observer = new CompositeSubagentObserver([eventsObserver])` and pass it to the manager; add `observer.add(widget)` after widget construction; import `CompositeSubagentObserver`; update the widget-construction comment to note the post-construction observer registration.
-- `src/tools/foreground-runner.ts` — remove the `ForegroundWidgetDeps` interface and the `widget` parameter; remove `widget.ensureTimer()` from `onSessionCreated` (keep the `recordRef` binding) and the `fgId` variable + the post-completion `widget.markFinished(fgId)` block.
-- `src/tools/background-spawner.ts` — remove the `BackgroundWidgetDeps` interface and the `widget` parameter; remove the `widget.ensureTimer()` / `widget.update()` calls; trim the doc comment ("Owns: widget update and launch message formatting" → "Owns: launch message formatting").
-- `src/tools/agent-tool.ts` — narrow `AgentToolWidget` to `{ setUICtx(ctx: UICtx): void }`; reword its doc comment; drop the `this.widget` argument from the `spawnBackground` / `runForeground` calls; keep `this.widget.setUICtx(ctx.ui)` and the constructor param.
-
-Tests:
-
-- `test/observation/composite-subagent-observer.test.ts` — **new.**
-  Fan-out to all delegates in registration order for each of the four methods; `add()` registers a late delegate; a throwing delegate does not suppress the others.
-- `test/ui/agent-widget.test.ts` — new `describe` for the observer methods: `onSubagentStarted` / `onSubagentCreated` start the timer and render (advancing fake timers keeps re-rendering); `onSubagentCompleted` / `onSubagentCompacted` trigger a render; the widget self-clears once idle.
-- `test/tools/foreground-runner.test.ts` — drop the `widget` arg from every `runForeground(...)` call; remove the "calls runtime.ensureTimer and runtime.markFinished after completion" test and the `spawnAndWaitRegistering` widget-binding framing (keep the streaming-`onUpdate` test).
-- `test/tools/background-spawner.test.ts` — drop the `widget` arg from every `spawnBackground(...)` call; remove the "calls runtime.ensureTimer and runtime.update after spawn" test.
-- `test/helpers/make-deps.ts` — narrow the `widget` fixture to `{ setUICtx: vi.fn() }`; reword the `AgentToolFixture.widget` doc comment (drop the `BackgroundWidgetDeps` / `ForegroundWidgetDeps` mention).
-- `test/helpers/make-deps.test.ts` — rewrite the "all widget methods are vi.fn stubs" test to assert only `setUICtx`; remove the `BackgroundWidgetDeps` / `ForegroundWidgetDeps` structural-compatibility tests and their imports.
-
-Docs:
-
-- `docs/architecture/architecture.md`:
-  - File tree (around line 318) — add `composite-subagent-observer.ts` under `observation/` with a one-line description.
-  - System diagram (around line 64) — add a `SubagentManager -.->|notifies| Widget` edge (the inverted, reactive direction) alongside the existing `Widget -.->|polls| SubagentManager`.
-  - Widget prose (around line 363) — note the 80 ms poll loop is now *started by lifecycle notifications* rather than by spawn-tool calls.
-  - Phase 18 roadmap Step 4 entry — mark ✅ with a `Landed:` bullet matching the Steps 1–3 format.
-  - Step-dependency Mermaid — `S4` node gets the ✅ marker.
-- `.pi/skills/package-pi-subagents/SKILL.md`:
-  - Domain table — Observation `5 → 6` modules (add `composite-subagent-observer.ts` to the list); header "seven domains (57 files)" → "(58 files)".
-  - Module-dependency-flow block — note the widget is now a lifecycle observer fanned out through the composite alongside `subagent-events-observer`.
-
-Verify the exact current counts with `grep` before editing (the Step 3 sweep set Observation to 5 and the total to 57); the architecture health-metrics snapshot table (`7,751 (62 files)`) is the Phase 18 *findings* snapshot and is left as-is, per the Step 3 precedent.
-
-Historical docs under `docs/plans/`, `docs/retro/`, and `docs/architecture/history/` are records of past work and are **not** edited.
-
-## Test Impact Analysis
-
-1. **New tests enabled.**
-   The composite observer becomes unit-testable in isolation (fan-out order, `add`, per-delegate fault isolation) — impossible before, since there was no fan-out unit.
-   The widget's timer-start logic becomes directly testable through its observer methods, rather than only indirectly through the spawn tools.
-2. **Tests that become redundant.**
-   The spawner widget-driving assertions (`foreground-runner.test.ts` "calls … ensureTimer and … markFinished", `background-spawner.test.ts` "calls … ensureTimer and … update") test inbound calls that no longer exist — removed.
-   `make-deps.test.ts`'s "all widget methods are vi.fn stubs" shrinks to `setUICtx`; the `BackgroundWidgetDeps` / `ForegroundWidgetDeps` structural-compat tests are removed with their interfaces.
-3. **Tests that must stay.**
-   The spawner result-text tests (launch message, queued/started, output-file, error), the foreground "calls onUpdate with streaming details while running" test (pins the surviving `recordRef` binding), the `AgentWidget.update` self-seed tests (the mechanism that replaces `markFinished`), and the `agent-tool` `setUICtx` test all exercise behavior that survives this step.
-
-## Invariants at risk
-
-This step touches surfaces refactored by Phase 18 Steps 1–3.
-Relevant prior `Landed:` invariants and the tests that pin them:
-
-- "The foreground `observer.onSessionCreated` keeps `recordRef`/`fgId` binding" (Step 3 outcome).
-  This step removes `fgId` (only ever used by the deleted `markFinished` call) but **keeps `recordRef`** for the streaming `onUpdate`.
-  Pinned by `test/tools/foreground-runner.test.ts` "calls onUpdate with streaming details while running" — must stay green.
-- "The widget owns detection of completions via `seedFinishedAgents`" (Steps 1–2 outcome).
-  Removing `markFinished` relies on this; pinned by `test/ui/agent-widget.test.ts` "AgentWidget.update self-seeds finished agents" and "does not advance the linger age on repeated update() without a turn".
-- "One session subscription per child; runtime holds zero UI state" (Step 3 outcome).
-  Unchanged here — the widget subscribes to *manager lifecycle notifications*, not a second *session* subscription.
-
-No new test is required to protect these; the surviving streaming and self-seed tests plus the type checker cover them.
-
-## TDD Order
-
-Non-breaking refactor; every commit keeps `pnpm run check` and the full suite green.
-Steps are ordered so the widget is wired as an observer *before* the spawn-tool calls are removed — no commit leaves the widget without a timer-start signal.
-
-1. **Add `CompositeSubagentObserver` (pure addition).**
-   Write `test/observation/composite-subagent-observer.test.ts` (red), then `src/observation/composite-subagent-observer.ts` (green): fan-out in registration order, `add()`, per-delegate fault isolation.
-   Not yet wired.
-   Run `pnpm run check`.
-   Commit: `refactor: add CompositeSubagentObserver to fan out lifecycle notifications (#423)`.
-
-2. **Subscribe the widget to lifecycle notifications.**
-   Add the four observer methods + `implements SubagentManagerObserver` + `startLoop` to `AgentWidget` (red→green with the new widget observer tests); wire `index.ts` (rename `eventsObserver`, wrap in `CompositeSubagentObserver`, `observer.add(widget)`).
-   The spawn tools still call the widget in this commit — the resulting double-drive is idempotent (`ensureTimer` uses `??=`; `update` and finished-seeding are idempotent), so behavior is unchanged.
-   The widget's observer methods are now invoked polymorphically by the manager, so they need no `fallow-ignore`.
-   Run `pnpm run check` and the full suite.
-   Commit: `refactor: subscribe the widget to lifecycle notifications via a composite observer (#423)`.
-
-3. **Stop driving the widget from the spawn tools (atomic removal).**
-   Remove the `widget` parameter and `ForegroundWidgetDeps` / `BackgroundWidgetDeps` interfaces from both spawners; drop the `ensureTimer` / `update` / `markFinished` call sites (and the now-orphaned `fgId`); narrow `AgentToolWidget` to `setUICtx` and drop the `this.widget` args from the spawner calls in `AgentTool`; delete `AgentWidget.markFinished` and make `ensureTimer` private.
-   Update the spawner tests (drop the `widget` arg, remove the two widget-driving tests), `make-deps.ts` (narrow the fixture), and `make-deps.test.ts` (rewrite the widget test, remove the structural-compat tests).
-   Removing the exported interfaces and the `widget` params breaks every call site and test at the type level, so they land together.
-   The widget keeps self-driving via the composite wired in Step 2, so there is no behavior gap.
-   Run `pnpm run check`, the full suite, and `pnpm fallow dead-code`.
-   Commit: `refactor: stop driving the widget from the spawn tools (#423)`.
-
-4. **Update the architecture doc and package skill.**
-   Apply the doc edits in Module-Level Changes (file tree, system-diagram edge, widget prose, Step 4 ✅ + `Landed:` bullet, `S4` Mermaid marker; SKILL.md Observation count `5 → 6` and total `57 → 58`, flow block).
-   Verify any touched Mermaid renders (load the `mermaid` skill).
-   Commit: `docs: mark Phase 18 Step 4 complete and record the widget self-drive (#423)`.
-
-## Risks and Mitigations
-
-- **Behavior gap between commits.**
-  Removing the spawn-tool calls before the widget is an observer would leave the widget with no timer-start signal.
-  Mitigation: Step 2 wires the composite (widget self-drives, alongside the still-present spawn-tool calls) strictly before Step 3 removes those calls.
-- **Construction cycle (widget ↔ manager).**
-  The widget needs the manager; the manager needs the observer; the observer includes the widget.
-  Mitigation: construct the composite with `[eventsObserver]`, pass it to the manager, then `observer.add(widget)` after the widget is built — the manager consults the observer only at spawn time.
-- **Transient double-drive in Step 2.**
-  Both the spawn tools and the observer drive the widget in that commit.
-  Mitigation: every driven method is idempotent (`ensureTimer` `??=`; `update` re-renders; finished-seeding only seeds when absent), so the doubled calls are harmless.
-- **Dead-code surface change.**
-  Privatizing `ensureTimer` and deleting `markFinished` alter what `fallow` sees.
-  Mitigation: Step 3 runs `pnpm fallow dead-code`; the new observer methods are invoked via the interface (the `SubagentEventsObserver` precedent), so they are not flagged.
-- **Foreground completion is unobserved.**
-  The manager does not fire `onSubagentCompleted` for foreground agents.
-  Mitigation: `seedFinishedAgents` already covers foreground completion through polling — pinned by the existing self-seed tests — so removing `markFinished` is safe.
-
-## Open Questions
-
-None blocking.
-Whether the widget should ultimately subscribe to the public `pi.events` (`subagents:*`) broadcast instead of the internal observer — the substitutable-UI direction — is deferred to the public-event-contract reconciliation ([#425]) and the UI-distribution decision ([#427]).
-Option A keeps that future migration to a localized `index.ts` swap.
-
-[#421]: https://github.com/gotgenes/pi-packages/issues/421
-[#422]: https://github.com/gotgenes/pi-packages/issues/422
-[#424]: https://github.com/gotgenes/pi-packages/issues/424
-[#425]: https://github.com/gotgenes/pi-packages/issues/425
-[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/plans/0424-drop-widget-dep-from-subagent-tool.md

@@ -1,166 +0,0 @@
----
-issue: 424
-issue_title: "pi-subagents: drop the widget and activity-map dependencies from the subagent tool"
----
-
-# Drop the widget dependency from the subagent tool
-
-## Problem Statement
-
-The LLM-facing `subagent` tool's real concern is dispatch, yet `AgentTool` still takes a `widget` constructor dependency and calls `this.widget.setUICtx(ctx.ui)` at the start of `execute`.
-Every `AgentTool` unit test has to stub the widget through `createToolDeps` — testability friction that marks the domain seam.
-Now that the widget self-drives its timer from lifecycle notifications (Phase 18 Step 4, [#423]) and `ToolStartHandler` already captures the UI context on every `tool_execution_start`, the tool no longer needs the widget at all.
-
-Note: the issue title and the roadmap entry for this step also mention an `agentActivity` / activity-map dependency, but that was already removed from `AgentTool` and the runtime in Phase 18 Step 3 ([#422]).
-The only remaining dependency to drop is `widget`.
-This plan corrects that stale wording where it appears in the roadmap.
-
-## Goals
-
-- Remove the `widget` constructor parameter from `AgentTool`; the tool depends only on manager / runtime / settings / registry / agentDir.
-- Remove the now-redundant `this.widget.setUICtx(ctx.ui)` call from `AgentTool.execute` — UICtx capture stays in `ToolStartHandler`.
-- Delete the `AgentToolWidget` interface and the `UICtx` import that only that interface used.
-- Drop the `widget` field, its stub, and the `AgentToolWidget` import from the `createToolDeps` fixture.
-- Update the `index.ts` call site and all affected tests in the same commit (the constructor-signature change breaks them at typecheck time).
-- This change is **not breaking** — `AgentTool` is internal (the package's only public exports are the service and settings entries), and observable behavior is preserved because `ToolStartHandler` already captures UICtx before the tool executes.
-
-## Non-Goals
-
-- No change to `ToolStartHandler`, `AgentWidget`, or the `UICtx` type itself (it stays in `src/ui/agent-widget.ts`, consumed by the widget and `ToolStartHandler`).
-- No change to `foreground-runner.ts` / `background-spawner.ts` (their widget driving was already removed in [#423]).
-- No work on Phase 18 Steps 6–8 ([#425], [#426], [#427]) — the public-event-contract reconciliation, test-clone consolidation, and UI-direction ADR are separate steps.
-
-## Background
-
-Relevant modules and their current state:
-
-- `src/tools/agent-tool.ts` — `AgentTool` constructor signature is `(manager, runtime, widget, settings, registry, agentDir)`.
-  `execute` opens with `this.widget.setUICtx(ctx.ui as UICtx)`.
-  The file defines the narrow `AgentToolWidget` interface (`setUICtx` only, already narrowed in [#423]) and imports `UICtx` from `#src/ui/agent-widget` solely for that interface and the cast.
-- `src/handlers/tool-start.ts` — `ToolStartHandler.handleToolExecutionStart` already calls `this.widget.setUICtx(ctx.ui)` then `this.widget.onTurnStart()`.
-  `tool_execution_start` fires before any tool's `execute`, so the widget already has the current UICtx by the time `AgentTool.execute` runs.
-  This handler is wired in `index.ts` and is the canonical UICtx-capture site.
-- `src/index.ts:152` — the sole `new AgentTool(...)` call site, passing `widget` as the third argument.
-  `widget` is still constructed and registered as a lifecycle observer (`observer.add(widget)`) and passed to `ToolStartHandler` — those usages stay.
-- `test/helpers/make-deps.ts` — `createToolDeps` builds an `AgentToolFixture` with a `widget` field stub (`{ setUICtx: vi.fn() }`) and imports `AgentToolWidget`.
-- `test/helpers/make-deps.test.ts` — has a `describe("widget defaults")` block asserting the stub.
-- `test/tools/agent-tool.test.ts` — `makeTool` passes `deps.widget`; the test `"sets UI context on runtime at start of execute"` asserts `deps.widget.setUICtx` was called.
-
-AGENTS.md constraint: pi-subagents is a minimal core whose dependency arrows point inward.
-Removing an outbound widget dependency from the LLM tool moves the package further toward "UI is a pure consumer of broadcast events," which is the stated precondition for the Phase 18 UI-direction decision.
-
-## Design Overview
-
-This is a purely subtractive refactor — no new collaborator, no new interface, no moved behavior.
-The widget already receives its UICtx from `ToolStartHandler` on every turn's first tool execution, so the tool's own `setUICtx` call is redundant.
-
-`AgentTool.execute` after the change opens directly with the registry reload:
-
-```typescript
-async execute(toolCallId, params, signal, onUpdate, ctx) {
-	// Reload custom agents so new .pi/agents/*.md files are picked up without restart
-	this.registry.reload();
-	const config = resolveSpawnConfig(params, this.registry, this.runtime.getModelInfo(), this.settings);
-	// ... unchanged
-}
-```
-
-The `ctx` parameter is still required by the `defineTool` `execute` signature; the tool simply no longer reads `ctx.ui`.
-
-New constructor signature:
-
-```typescript
-constructor(
-	private readonly manager: AgentToolManager,
-	private readonly runtime: AgentToolRuntime,
-	private readonly settings: AgentToolSettings,
-	private readonly registry: AgentTypeRegistry,
-	private readonly agentDir: string,
-) { /* unchanged body */ }
-```
-
-Edge cases:
-
-- UICtx availability — `tool_execution_start` always precedes `execute`, so removing the tool's capture loses no coverage; the widget is registered as an observer and already has the UICtx when it renders.
-- No behavior depends on the tool calling `setUICtx` twice per turn; the second call (in the tool) was idempotent for the same `ctx.ui` and a no-op when unchanged.
-
-## Module-Level Changes
-
-- `src/tools/agent-tool.ts`
-  - Remove the `import { type UICtx } from "#src/ui/agent-widget";` line.
-  - Remove the `AgentToolWidget` interface (and its doc comment).
-  - Remove the `private readonly widget: AgentToolWidget` constructor parameter.
-  - Remove the `this.widget.setUICtx(ctx.ui as UICtx);` statement and its comment from `execute`.
-- `src/index.ts`
-  - Update line 152: `new AgentTool(manager, runtime, settings, registry, getAgentDir())` (drop `widget`).
-  - Leave the `widget` construction, `observer.add(widget)`, and `new ToolStartHandler(widget)` wiring unchanged.
-- `test/helpers/make-deps.ts`
-  - Drop `AgentToolWidget` from the imports from `#src/tools/agent-tool`.
-  - Remove the `widget: AgentToolWidget` field from `AgentToolFixture` (and its doc comment).
-  - Remove the `const widget: AgentToolWidget = { setUICtx: vi.fn() };` stub and the `widget,` entry in the returned object.
-- `test/helpers/make-deps.test.ts`
-  - Remove the `describe("widget defaults", ...)` block.
-- `test/tools/agent-tool.test.ts`
-  - Update `makeTool` to drop `deps.widget` from the `new AgentTool(...)` call.
-  - Remove the `"sets UI context on runtime at start of execute"` test (UICtx capture is covered by `test/handlers/tool-start.test.ts`).
-- `docs/architecture/architecture.md`
-  - Mark Phase 18 Step 5 complete (✅) with a `Landed:` bullet, mirroring the Step 4 entry.
-  - Correct the stale `agentActivity` mention in the Step 5 description (line ~979) — only the `widget` param remains to drop.
-  - Update the step dependency diagram node `S5` to the completed (✅) marker.
-
-Grep confirmation performed during planning: `AgentToolWidget` appears only in `src/tools/agent-tool.ts` and `test/helpers/make-deps.ts`; the `UICtx` type stays in use by `src/ui/agent-widget.ts`, `src/handlers/tool-start.ts` (via `unknown`), and `test/ui/agent-widget.test.ts`.
-No `package-*/SKILL.md` references `AgentToolWidget` or the tool's widget dependency.
-
-## Test Impact Analysis
-
-1. New tests enabled: none required — this is a subtractive refactor, not a new seam.
-   The remaining `AgentTool` tests get simpler (no widget stub to thread).
-2. Tests that become redundant:
-   - `test/tools/agent-tool.test.ts` → `"sets UI context on runtime at start of execute"` — the tool no longer captures UICtx; `test/handlers/tool-start.test.ts` (`"calls setUICtx with the context's ui"`) already pins that behavior on its true owner.
-     Remove it.
-   - `test/helpers/make-deps.test.ts` → `describe("widget defaults")` — the fixture no longer has a widget field.
-     Remove it.
-3. Tests that must stay as-is:
-   - `test/handlers/tool-start.test.ts` — genuinely exercises UICtx capture, now the sole owner of that responsibility.
-   - `test/ui/agent-widget.test.ts` — exercises the widget's own `setUICtx`, unaffected.
-   - All other `AgentTool` dispatch/resume/background/foreground tests — exercise the tool's real concern and only shed the unused widget argument.
-
-## Invariants at risk
-
-Phase 18 Step 4 ([#423]) documented Outcome: "the widget is a reactive consumer; no inbound calls from core spawn tools."
-This step extends that to the LLM tool.
-The invariant that UICtx is captured exactly once per turn by `ToolStartHandler` is pinned by `test/handlers/tool-start.test.ts` (`"calls setUICtx with the context's ui"` and `"calls setUICtx before onTurnStart"`) — both stay green and require no new test.
-No earlier step's `Outcome:` is regressed: the widget's self-driving timer (Step 4) is independent of the tool's removed `setUICtx` call.
-
-## TDD Order
-
-This is a behavior-preserving refactor; the green suite stays green.
-Because removing the constructor parameter breaks the `index.ts` call site, the `make-deps` fixture, and the `agent-tool` tests at typecheck time, all source and test edits land in one commit.
-
-1. **Refactor: drop the widget dependency from `AgentTool`.**
-   Edit `src/tools/agent-tool.ts` (remove the `UICtx` import, `AgentToolWidget` interface, `widget` param, and `setUICtx` call), `src/index.ts` (drop `widget` from the constructor call), `test/helpers/make-deps.ts` (drop the field, stub, and import), `test/helpers/make-deps.test.ts` (remove the widget-defaults block), and `test/tools/agent-tool.test.ts` (drop `deps.widget` from `makeTool`, remove the UICtx test).
-   Run `pnpm run check` and the full package suite.
-   Commit: `refactor: drop the widget dependency from the subagent tool (#424)`.
-2. **Docs: mark Phase 18 Step 5 complete.**
-   Update `docs/architecture/architecture.md` — Step 5 ✅ + `Landed:` bullet, correct the stale `agentActivity` wording, update the `S5` diagram node.
-   Commit: `docs: mark Phase 18 Step 5 complete and drop the tool widget dep (#424)`.
-
-## Risks and Mitigations
-
-- Risk: removing the tool's `setUICtx` loses UICtx for the widget in some path.
-  Mitigation: `tool_execution_start` fires before every `execute`, and `ToolStartHandler` captures UICtx there; the existing handler tests pin this.
-  Run the full suite, not just `agent-tool.test.ts`, since the change touches a shared fixture (`make-deps.ts`).
-- Risk: an orphaned import left behind after deletions (Biome `noUnusedImports` is warning-level, exit 0).
-  Mitigation: re-read `agent-tool.ts` and `make-deps.ts` after editing; confirm `UICtx` and `AgentToolWidget` have no remaining references via grep.
-- Risk: the stale `agentActivity` wording is mistaken for live work to do.
-  Mitigation: this plan explicitly records that `agentActivity` was already removed in [#422]; only `widget` remains.
-
-## Open Questions
-
-None — the scope is fully determined by the established roadmap and the verified current code state.
-
-[#422]: https://github.com/gotgenes/pi-packages/issues/422
-[#423]: https://github.com/gotgenes/pi-packages/issues/423
-[#425]: https://github.com/gotgenes/pi-packages/issues/425
-[#426]: https://github.com/gotgenes/pi-packages/issues/426
-[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/plans/0425-reconcile-subagent-events-contract.md

@@ -1,144 +0,0 @@
----
-issue: 425
-issue_title: "pi-subagents: reconcile the public SUBAGENT_EVENTS contract with emitted channels"
----
-
-# Reconcile the public `SUBAGENT_EVENTS` contract with emitted channels
-
-## Problem Statement
-
-The public lifecycle-event contract has drifted out of sync with what the core actually broadcasts on `pi.events`.
-`SUBAGENT_EVENTS.ACTIVITY = "subagents:activity"` is declared in the service surface (`src/service/service.ts`) and the architecture doc's lifecycle-events table, but no module ever emits it — a vacant hook that the architecture's own "no vacant hooks" rule forbids.
-The vacancy hardened in Phase 18 Steps 1–5, which deleted the entire activity tier (`AgentActivityTracker`, `ui-observer`), so there is no streaming-progress source left to broadcast.
-In the other direction, four channels the core does emit — `subagents:failed`, `subagents:compacted`, `subagents:created` (all in `SubagentEventsObserver`), and `subagents:steered` (in `steer-tool.ts`) — are absent from the constant map.
-A consumer reading `SUBAGENT_EVENTS` therefore gets one channel that never fires and misses four that do.
-
-## Goals
-
-- Remove the vacant `SUBAGENT_EVENTS.ACTIVITY` constant.
-  This is a **breaking change** to the public surface: it deletes a key from the exported `SUBAGENT_EVENTS` map, so a consumer referencing `SUBAGENT_EVENTS.ACTIVITY` breaks at the type level on upgrade.
-  Use `feat!:` with a `BREAKING CHANGE:` footer.
-- Add the four emitted agent-lifecycle channels to the constant map: `FAILED`, `COMPACTED`, `CREATED`, `STEERED`.
-- After the change, declared channels equal emitted agent-lifecycle channels — no vacant hook, no undeclared emission.
-- Update the lifecycle-events table in `docs/architecture/architecture.md` to match, and correct the stale `subagents:completed` payload shape while there.
-- Mark Phase 18 Step 6 complete in the architecture roadmap.
-
-## Non-Goals
-
-- Re-introducing a streaming-progress (`activity`) event.
-  The activity tier was deliberately deleted in Steps 1–3; resurrecting it is out of scope and was rejected during planning.
-- Adding the config-domain events (`subagents:settings_loaded`, `subagents:settings_changed`) or the child-session seam events (`subagents:child:*`) to `SUBAGENT_EVENTS`.
-  Those belong to separate domains and already have their own constant homes (settings emitter, `child-lifecycle.ts`); `SUBAGENT_EVENTS` is the agent-lifecycle bus only.
-- The `subagents:record` session entry — it is an `appendEntry` (session persistence), not a `pi.events.emit`, so it is not a channel constant.
-- Changing any event payload shape or emission site.
-  This issue reconciles the *constant map* with what is *already emitted*; emission logic is untouched.
-- Phase 18 Steps 7–8 (test-clone consolidation, UI reconsideration) — separate issues ([#426], [#427]).
-
-## Background
-
-- `src/service/service.ts` declares `SUBAGENT_EVENTS` as an `as const` object — the public, cross-extension channel constants, re-exported through the `.` subpath entry and rolled into `dist/public.d.ts`.
-- `src/observation/subagent-events-observer.ts` emits `subagents:started`, `subagents:completed`, `subagents:failed`, `subagents:compacted`, and `subagents:created`.
-- `src/tools/steer-tool.ts` emits `subagents:steered` with payload `{ id, message }`.
-- The completed/failed payload is produced by `buildEventData(record)` in `src/observation/notification.ts`: `{ id, type, description, result, error, status, toolUses, durationMs, tokens? }`.
-  The architecture doc's current table lists `subagents:completed` as `{ id, type, status, result?, error? }`, which is stale.
-- AGENTS.md / `package-pi-subagents` skill constraint: any change to the public surface must run `pnpm --filter @gotgenes/pi-subagents run verify:public-types` (a CI gate), and sibling packages consume this one from the published registry release, not a workspace symlink.
-- The "no vacant hooks" rule (ADR-0002, architecture doc §519) governs both directions here: admit a surface only when a real consumer/emitter exists.
-
-This is a value-only reconciliation of a shared constant: no new collaborator, no dependency-wiring change, no new parameter on any interface — so the `design-review` dependency-width / Law-of-Demeter checklist surfaces nothing actionable.
-
-## Design Overview
-
-The reconciled constant map:
-
-```typescript
-/** Event channel constants for pi.events subscriptions. */
-export const SUBAGENT_EVENTS = {
-  STARTED: "subagents:started",
-  COMPLETED: "subagents:completed",
-  FAILED: "subagents:failed",
-  COMPACTED: "subagents:compacted",
-  CREATED: "subagents:created",
-  STEERED: "subagents:steered",
-} as const;
-```
-
-The declared set is now exactly the set of agent-lifecycle channels emitted by `SubagentEventsObserver` and `steer-tool.ts`.
-
-Updated lifecycle-events table (`architecture.md`):
-
-| Channel               | Payload                                                                             | When                                          |
-| --------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- |
-| `subagents:started`   | `{ id, type, description }`                                                         | Agent begins running                          |
-| `subagents:completed` | `{ id, type, description, status, result?, error?, toolUses, durationMs, tokens? }` | Agent finishes successfully                   |
-| `subagents:failed`    | same as `completed` (`buildEventData` shape)                                        | Agent ends in `error`/`stopped`/`aborted`     |
-| `subagents:compacted` | `{ id, type, description, reason, tokensBefore, compactionCount }`                  | Child session compacts                        |
-| `subagents:created`   | `{ id, type, description, isBackground }`                                           | Background agent created (pre-admission)      |
-| `subagents:steered`   | `{ id, message }`                                                                   | Steering message delivered to a running agent |
-
-The `subagents:activity` row is removed.
-
-### Edge cases
-
-- `as const` preservation: the literal-string value types must stay narrow, so the new keys keep the `as const` assertion.
-  `verify:public-types` confirms the rolled `dist/public.d.ts` exposes the narrowed literal types.
-- No runtime emission changes: the four added constants name channels that are *already* fired, so subscribers wired to the string literals see no behavioral change — only the typed constant is now available.
-
-## Module-Level Changes
-
-- `packages/pi-subagents/src/service/service.ts` — remove the `ACTIVITY` key; add `FAILED`, `COMPACTED`, `CREATED`, `STEERED` to `SUBAGENT_EVENTS`.
-- `packages/pi-subagents/test/service/service.test.ts` — update the `SUBAGENT_EVENTS` assertion: drop the `ACTIVITY` expectation, add expectations for the four new constants.
-- `packages/pi-subagents/docs/architecture/architecture.md` — replace the lifecycle-events table (remove the `activity` row, add `failed`/`compacted`/`created`/`steered`, correct the `completed` payload); mark Phase 18 Step 6 complete with a `✅ … — complete.` prefix and a `Landed:` bullet.
-
-Grep confirmation that no other live reference to the removed symbol exists:
-
-- `grep -rn "SUBAGENT_EVENTS.ACTIVITY\|subagents:activity"` across `src/`, `test/`, and `.pi/skills/package-*/SKILL.md`: the only live hits are `service.ts:100`, the `service.test.ts` assertion, and the `architecture.md` table — all three are updated here.
-  Remaining `subagents:activity` matches live in historical/plan docs (`docs/plans/0048-*`, `docs/architecture/history/`, the structural-analysis finding #6 snapshot) and are intentionally left as historical record.
-- `docs/comparison-with-upstream.md` already lists the lifecycle bus as `created, started, completed, failed, steered, compacted` (no `activity`) — it matches the reconciled set and needs no edit.
-- The architecture structural-analysis finding #6 (the phase-start smell snapshot) is left as-is, consistent with how findings #1–5 remain present-tense snapshots while their steps are marked `✅`.
-
-## Test Impact Analysis
-
-This is a constant-map reconciliation, not an extraction, so no new lower-level test surface opens up.
-
-1. New tests enabled: none beyond the expanded `SUBAGENT_EVENTS` assertion — the change adds no new function or collaborator.
-2. Tests becoming redundant: none.
-   The emission-site tests in `test/observation/subagent-events-observer.test.ts` (which assert `subagents:failed`/`compacted`/`created` are emitted) and the steer-tool test stay — they pin the *emission*, while the service test pins the *declaration*.
-3. Tests that must stay as-is: the observer and steer-tool emission tests — they genuinely exercise the channels the constants now name, and are the other half of the "declared == emitted" invariant.
-
-## Invariants at risk
-
-This step touches the public-contract surface that Step 6 is itself responsible for; no earlier Phase 18 step (1–5) refactored `SUBAGENT_EVENTS`, so there is no prior `Outcome:`/`Landed:` invariant to regress.
-The invariant this step establishes — declared channels equal emitted agent-lifecycle channels — is pinned from both sides:
-
-- Declaration: the updated `test/service/service.test.ts` `SUBAGENT_EVENTS` assertion.
-- Emission: existing `test/observation/subagent-events-observer.test.ts` (`failed`/`compacted`/`created`) and the steer-tool test (`steered`).
-
-## TDD Order
-
-1. **Reconcile the constant map (red → green → commit).**
-   Test surface: `test/service/service.test.ts` — rewrite the `SUBAGENT_EVENTS` assertion to expect `STARTED`, `COMPLETED`, `FAILED`, `COMPACTED`, `CREATED`, `STEERED` and to assert `ACTIVITY` is absent (`expect("ACTIVITY" in SUBAGENT_EVENTS).toBe(false)` or drop the import-time reference).
-   This fails to compile/assert against the current map (red).
-   Then edit `src/service/service.ts`: remove `ACTIVITY`, add the four new keys (green).
-   Run `pnpm --filter @gotgenes/pi-subagents run check`, `pnpm --filter @gotgenes/pi-subagents run test`, and `pnpm --filter @gotgenes/pi-subagents run verify:public-types` (public-surface gate).
-   Commit: `feat!: reconcile SUBAGENT_EVENTS with emitted channels (#425)` with a `BREAKING CHANGE:` footer noting the removal of `SUBAGENT_EVENTS.ACTIVITY` and the migration (subscribe to the emitted channel constants `FAILED`/`COMPACTED`/`CREATED`/`STEERED`; there is no replacement for `ACTIVITY` — the activity tier was removed in Phase 18).
-2. **Update the architecture doc (commit, no test).**
-   Replace the lifecycle-events table and correct the `completed` payload; mark Phase 18 Step 6 `✅ … — complete.` with a `Landed:` bullet.
-   Run `pnpm --filter @gotgenes/pi-subagents run lint` (rumdl).
-   Commit: `docs: reconcile lifecycle-events table with SUBAGENT_EVENTS (#425)`.
-
-## Risks and Mitigations
-
-- **Risk:** the breaking removal of `ACTIVITY` surprises a consumer.
-  **Mitigation:** the constant was never emitted, so no consumer could meaningfully act on it; the `BREAKING CHANGE:` footer documents the removal and the absence of a replacement, and release-please carries it to the CHANGELOG and the issue close comment.
-- **Risk:** the rolled `dist/public.d.ts` drifts from the source `as const` shape.
-  **Mitigation:** `verify:public-types` packs the tarball and type-checks a throwaway consumer against both entries — run it in Step 1 before committing.
-- **Risk:** stale `subagents:activity` references linger in docs.
-  **Mitigation:** the Module-Level Changes grep enumerates every live vs. historical hit; only the three live references are edited, historical snapshots are intentionally preserved.
-
-## Open Questions
-
-None.
-The two design choices (remove vs. emit `ACTIVITY`; three vs. four added channels) were resolved during planning: remove `ACTIVITY`, and declare all four emitted agent-lifecycle channels (`failed`/`compacted`/`created`/`steered`).
-
-[#426]: https://github.com/gotgenes/pi-packages/issues/426
-[#427]: https://github.com/gotgenes/pi-packages/issues/427