@nklisch/pi-enhanced 0.4.4 → 0.5.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-This document describes the architecture of the pi-subagents fork: a focused, composable core with a stable API boundary that other extensions can build on.
+This document describes the architecture of `@nklisch/pi-subagents`: a focused, composable core with a stable API boundary that other extensions can build on. A subagent is a child Pi session. Joined delivery returns its settled result through the calling tool; detached delivery returns an identity while the child continues running.
 
 ## Design principles
 
@@ -10,10 +10,10 @@ This document describes the architecture of the pi-subagents fork: a focused, co
 3. **Typed API boundary** — this package exports a `SubagentsService` interface and `Symbol.for()` accessors (`publishSubagentsService` / `getSubagentsService`).
    Consumers declare this package as an optional peer dependency and use dynamic import for compile-time types.
    The runtime bridge is `Symbol.for("@nklisch/pi-subagents:service")` on `globalThis` — no separate API package.
-4. **No time-based scheduling** — cron-style timed dispatch (upstream's `schedule.ts` subsystem) is removed from the core (#52).
+4. **No time-based scheduling** — cron-style timed dispatch stays outside the core.
    Timed dispatch is a separate concern that any extension can implement by calling `launch()` on the published API.
    The max-concurrent admission gate is not scheduling in this sense — concurrency management stays in core.
-5. **UI is an in-core, substitutable consumer** — [ADR-0004](../decisions/0004-reconsider-ui-direction.md) records the per-component decision: the widget shows detached agents only, the bespoke conversation viewer is replaced by native session navigation, the `/agents` command is dissolved into focused surfaces, and the surviving UI stays in the core as a reactive consumer (not extracted to a separate package).
+5. **UI is an in-core, substitutable consumer** — [ADR-0004](../decisions/0004-reconsider-ui-direction.md) records the per-component decision: the widget shows detached agents only, native session navigation provides read-only transcripts, settings have a focused command, and the UI stays in the core as a reactive consumer (not extracted to a separate package).
    Extraction remains an available future option because the composition invariant holds — the core is byte-for-byte identical with or without a given UI consumer.
 6. **Snapshot identity; share the canonical runtime** — mutable parent identity and prompt state are frozen into `ParentSnapshot` at spawn. The parent `ModelRuntime` is deliberately shared so child sessions preserve runtime provider and authentication registrations; no live session context is captured.
 7. **Subscribe, don't thread** — observation of agent progress uses direct session-event subscription, not callback parameters threaded through multiple layers.
@@ -21,7 +21,7 @@ This document describes the architecture of the pi-subagents fork: a focused, co
    If state isn't available yet, the object that needs it doesn't exist yet.
    No post-construction field writes from external code — if an object can't be instantiated ready-to-go, the prep work hasn't been done and the right dependencies haven't been identified.
 9. **State owns its mutations** — mutable state lives in a class whose methods enforce valid transitions and invariants.
-   Free functions that mutate module-scoped variables, closure-captured bags-of-functions, and external writes to shared interfaces are replaced by classes that encapsulate the state they manage.
+   Classes encapsulate the state they manage rather than exposing module-scoped variables or mutable shared interfaces to external writers.
 10. **Open for extension, closed for modification** — pi-subagents is a minimal core that publishes events and a service API.
     Other packages (pi-permission-system, a future UI extension, hypothetical OTel integration) hook into these events to add permissions, rendering, or telemetry.
     Pi-subagents has zero knowledge of its consumers — dependency arrows point inward, never outward.
@@ -104,107 +104,18 @@ flowchart TB
 
 ```mermaid
 classDiagram
-    class Subagent {
-        +id: string
-        +type: SubagentType
-        +description: string
-        -state: SubagentState
-        -execution: SubagentExecution
-        +status: SubagentStatus
-        +result?: string
-        +error?: string
-        +toolUses: number
-        +lifetimeUsage: LifetimeUsage
-        +subagentSession?: SubagentSession
-        +toolCallId?: string
-        +markRunning() delegates
-        +launch()
-        +resume(prompt, mode, signal)
-        +requestStop(reason): boolean
-        +steer(message): Promise~SteerOutcome~
-        +settlement: Promise~void~
-        +isSessionReady(): boolean
-        +getConversation(): string | undefined
-        +getContextPercent(): number | null
-        +subscribeToUpdates(fn): unsub | undefined
-        +messages: readonly unknown[]
-        +effectiveThinkingLevel: ThinkingLevel
-        -executionInFlight: boolean
-        -resumeReserved: boolean
-        +completeRun(result)
-        +failRun(err)
-        +disposeSession(): Promise~void~
-    }
-
-    class SubagentState {
-        +status: SubagentStatus
-        +result?: string
-        +error?: string
-        +startedAt: number
-        +completedAt?: number
-        +toolUses: number
-        +lifetimeUsage: LifetimeUsage
-        +compactionCount: number
-        +markRunning() ... markStopped()
-        +resetForResume()
-        +incrementToolUses()
-        +addUsage(delta)
-        +incrementCompactions()
-    }
-
-    class SubagentExecution {
-        +createSubagentSession(params)
-        +snapshot: ParentSnapshot
-        +prompt: string
-        +baseCwd: string
-        +observer?: SubagentLifecycleObserver
-        +getRunConfig?()
-        +getWorkspaceProvider?()
-        +model?, maxTurns?, thinkingLevel?
-        +parentSession?, signal?
-    }
-
-    class SubagentManager {
-        +spawn(snapshot, type, prompt, config)
-        +launch(snapshot, type, prompt, config)
-        +resume(id, prompt, mode, signal)
-        +stop(id, timeout): StopOutcome
-        +getRecord(id): Subagent
-        +listAgents(): Subagent[]
-    }
-
-    class AgentTypeRegistry {
-        +resolveType(type): string
-        +resolveAgentConfig(type): AgentConfig
-        +reload()
-        +getToolNamesForType(type): string[]
-    }
-
-    class ParentSnapshot {
-        +cwd: string
-        +systemPrompt: string
-        +model: unknown
-        +modelRegistry: unknown
-        +modelRuntime?: unknown
-        +parentContext?: string
-    }
-
-    class SubagentsService {
-        +launch(type, prompt, options?): Promise~LaunchDelivery~
-        +resume(id, prompt, options?): Promise~ResumeDelivery~
-        +stop(id, timeout?): Promise~StopDelivery~
-        +steer(id, message): Promise~SteerDelivery~
-        +list(options?): SubagentRecord[]
-        +getResult(id): ResultDelivery
-        +getRecord(id): SubagentRecord
-        +waitForAll()
-        +hasRunning(): boolean
-    }
+    class Subagent
+    class SubagentState
+    class SubagentExecution
+    class SubagentManager
+    class AgentTypeRegistry
+    class ParentSnapshot
+    class SubagentsService
 
     SubagentManager --> Subagent : creates/manages
-    Subagent --> SubagentState : owns (private)
-    Subagent --> SubagentExecution : runs via (mandatory)
-    SubagentManager --> ParentSnapshot : receives at spawn
+    Subagent --> SubagentState : owns transitions and metrics
+    Subagent --> SubagentExecution : owns run coordination
+    SubagentExecution --> ParentSnapshot : frozen identity and prompt inputs
     SubagentsService --> SubagentManager : wraps via adapter
     SubagentManager --> AgentTypeRegistry : resolves types
 ```
@@ -236,7 +147,7 @@ Resume admission is a record-owned lease. A genuinely running or already-reserve
 
 Terminal outcomes also carry orthogonal consumption state. Joined delivery, `get_subagent_result`, and a queued detached completion notification mark the outcome consumed. Records remain available for the parent session; only their heavy live child sessions are released after the configured consumed or unconsumed retention window. Released records keep their result and persisted transcript pointer but cannot resume. Release detaches the session synchronously before awaiting teardown, so it cannot race a new resume.
 
-Completion notifications are held while the parent agent run is active and flushed on `agent_settled`, rechecking consumption before enqueueing a follow-up. A blocking `get_subagent_result` request claims direct delivery before awaiting, so the same terminal outcome cannot also enqueue a completion follow-up. Child session creation shares the parent model runtime and leaves extension-tool registration open; a denylist removes disallowed built-ins and recursive orchestration tools across registry refreshes. Child teardown mirrors Pi's managed root lifecycle: it emits and awaits `session_shutdown` before `AgentSession.dispose()` revokes extension contexts, then publishes the child `disposed` event.
+Completion notifications are held while the parent agent run is active and flushed on `agent_settled`, rechecking consumption before enqueueing a follow-up. `get_subagent_result` is a bounded, nonblocking read: active runs return status; terminal results are marked consumed so a later completion nudge does not duplicate delivery. Child session creation shares the parent model runtime and leaves extension-tool registration open; a denylist removes disallowed built-ins and recursive orchestration tools across registry refreshes. Child teardown mirrors Pi's managed root lifecycle: it emits and awaits `session_shutdown` before `AgentSession.dispose()` revokes extension contexts, then publishes the child `disposed` event.
 
 ## Execution flow
 
@@ -275,9 +186,7 @@ sequenceDiagram
 
 ## Module organization
 
-The extension has 67 source files organized into six domains plus entry-point wiring.
-All eight domains have directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
-Issue #164 moved the 26 previously flat root-level files into five new domain directories, reducing the root to 5 files + 8 directories.
+The source separates domain logic from entry-point wiring in these directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
 
 ### Current layout
 
@@ -389,7 +298,7 @@ content and labels the degraded state.
 Record statistics (tool uses, token usage, compaction counts) and live activity (active tools, response text, turn counts) are updated by `record-observer.ts`, which subscribes directly to session events.
 This is the single per-child session subscription — all run state lives on the `Subagent` record.
 
-The widget maintains a bounded reactive read model of active detached records and the small terminal linger set, populated by `SubagentManagerObserver` lifecycle callbacks. While active it refreshes that model at 500 ms; each refresh reads only those retained records and requests the normal Pi widget render, rather than cloning or sorting the manager's full terminal history. When only terminal linger records remain, it renders the completion state once and leaves the static widget registered without an interval until turn aging or clear removes it. The `/subagents:sessions` navigator reads messages via `Subagent.agentMessages`, falls back to the retained JSONL source after release, and subscribes to both session and record-release updates — no direct `AgentSession` reference (#277).
+The widget maintains a bounded reactive read model of active detached records and the small terminal linger set, populated by `SubagentManagerObserver` lifecycle callbacks. While active it refreshes that model at 500 ms; each refresh reads only those retained records and requests the normal Pi widget render, rather than cloning or sorting the manager's full terminal history. When only terminal linger records remain, it renders the completion state once and leaves the static widget registered without an interval until turn aging or clear removes it. The `/subagents:sessions` navigator reads messages via `Subagent.agentMessages`, falls back to the retained JSONL source after release, and subscribes to both session and record-release updates — no direct `AgentSession` reference.
 
 ## Cross-extension architecture
 
@@ -402,9 +311,7 @@ flowchart TD
         ui_int["Internal UI: widget, session-navigator,<br/>subagents-settings"]
     end
 
-    core -- "Symbol.for on globalThis" --> sched["scheduling extension<br/>(hypothetical)"]
-    core -- "Symbol.for on globalThis" --> subui["pi-subagents-ui<br/>(deferred)"]
-    core -- "Symbol.for on globalThis" --> future["any future extension"]
+    core -- "Symbol.for on globalThis" --> consumer["cross-extension service consumer"]
 ```
 
 Consumers call `getSubagentsService()?.launch(...)` at runtime.
@@ -418,35 +325,35 @@ They declare this package as an optional peer dependency and use dynamic import
 - `createSubagentSession` — assembly factory: session creation and extension binding; returns a born-complete `SubagentSession`.
 - `SubagentSession` — the born-complete child session: drives turn loops, exposes Pi's idle boundary, steers, and performs idempotent asynchronous teardown (`session_shutdown` → `AgentSession.dispose()` → child `disposed`).
 - `child-lifecycle` — publishes the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) on `pi.events`.
-  Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
-  This replaced the former outbound `permission-bridge` (#261, [ADR-0002]) — the core no longer looks up a named consumer.
-- `workspace` — the single generative seam (#262, [ADR-0002]): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
-  With no provider, children run in the parent cwd (default unchanged); the git worktree strategy lives behind this seam in `@gotgenes/pi-subagents-worktrees` (#263, the seam's first consumer).
+  A permission consumer can register each child session on `session-created` and unregister it on `disposed`.
+  The core does not look up a named consumer; see [ADR-0002].
+- `workspace` — the workspace provider seam ([ADR-0002]): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
+  With no provider, children run in the parent cwd; a companion package can supply a Git worktree strategy behind this seam.
 - `session-config` — pure configuration assembler (called by `createSubagentSession`).
 - `SubagentRuntime` — session-scoped state bag with methods.
 - `ParentSnapshot` — immutable snapshot of parent session state, captured once at spawn time.
 - `record-observer` — session-event observer that updates record statistics without callback threading.
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, skills, environment.
-- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, [ADR-0002]); `git` no longer appears in the core.
+- Worktree isolation is an external workspace-provider strategy, not a core responsibility ([ADR-0002]).
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
-- Internal UI (widget, `/subagents:sessions` session navigator, `/subagents:settings` command) — the conversation viewer and `/agents` menu were removed in Phase 19 (Steps 5–6, [#442], [#441]) per [ADR-0004].
+- Internal UI (widget, `/subagents:sessions` session navigator, `/subagents:settings` command) is a substitutable consumer ([ADR-0004]).
 
-### What the core dropped
+### What stays outside the core
 
-- **Scheduling** (`schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`) — removed (#52).
-- **Ad-hoc RPC** (`cross-extension-rpc.ts`) — replaced by the typed `SubagentsService` published via `Symbol.for()` (#49).
-- **Group join** (`group-join.ts`) — removed (#49).
-- **Output file** (`output-file.ts`) — replaced by `session-dir.ts` + `SessionManager.create()` (#61).
-- **Callback threading** — the three-layer `on*` callback chain was replaced by direct session-event subscriptions (#100).
-- **Live `ctx` capture** — replaced by `ParentSnapshot`, an immutable data object captured once at spawn time (#99).
+Time-based scheduling, event RPC, batch/group identity, hard process termination,
+and agent-definition editors are not core responsibilities. Permission policy and
+workspace strategies belong to companion extensions. The core retains its own
+parent-only tool guard and supported tool-denylist behavior; these are not a
+second permission system.
 
 ## SubagentsService
 
 The `SubagentsService` interface, accessor functions, and serializable types are exported from `@nklisch/pi-subagents` via the root export.
-No separate API package is needed.
+No separate API package is needed. The service adapter resolves caller-supplied
+model strings against the active registry before launch.
 
 Consumers declare this package as an optional peer dependency:
 
@@ -485,774 +392,86 @@ Key types:
 - `LaunchOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `inheritContext`, `mode`, `timeoutSeconds`, and `signal`.
 - `SUBAGENT_EVENTS` — channel constants for `pi.events` subscriptions.
 
-### Accessor pattern
-
-```typescript
-const SERVICE_KEY = Symbol.for("@nklisch/pi-subagents:service");
-
-export function publishSubagentsService(service: SubagentsService): void {
-  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
-}
-
-export function getSubagentsService(): SubagentsService | undefined {
-  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
-    | SubagentsService
-    | undefined;
-}
-```
-
-If Pi gains a native service registry ([earendil-works/pi#4207]), these accessors can be updated to delegate to `pi.registerService()` / `pi.getService()` internally while keeping the same consumer API.
-
 ### Lifecycle events
 
 The core emits events on `pi.events` that any extension can observe:
 
-| Channel               | Payload                                                                             | When                                          |
-| --------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- |
-| `subagents:started`   | `{ id, type, description, runId, mode }`                                             | Agent begins running                          |
-| `subagents:completed` | `{ id, type, runId, mode, status, terminalReason, result?, error?, toolUses, activeRuntimeMs, tokens? }` | Agent reaches a terminal state |
-| `subagents:resumed`   | same as `completed` (`buildEventData` shape)                                        | A retained session's resumed turn finishes    |
-| `subagents:failed`    | same as `completed` (`buildEventData` shape)                                        | Agent ends in `error` or `stopped`             |
-| `subagents:compacted` | `{ id, type, description, reason, tokensBefore, compactionCount }`                  | Child session compacts                        |
-| `subagents:created`   | `{ id, type, description, runId, mode }`                                             | Agent record created (pre-admission)           |
-| `subagents:steered`   | `{ id, message }`                                                                   | Steering message delivered to a running agent |
-
-These are fire-and-forget broadcast events — no request IDs, no reply channels.
-
-## Target architecture
-
-The long-term architectural direction is to make pi-subagents a **minimal orchestrator** with inverted dependencies.
-The core spawns a child session derived from the parent, runs the turn loop, tracks and streams and collects the result, gates concurrency, supports resume, and **publishes its lifecycle**.
-Everything else — permissions, worktree/workspace isolation, UI, telemetry — is an extension that attaches through one of two surfaces and never reaches into the core.
-
-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.
-
-1. **Lifecycle events (observational) — unlimited.**
-   The core emits awaited, ordered events for the child-execution lifecycle (`spawning`, `session-created` pre-`bindExtensions`, `completed`, `disposed`).
-   Any number of extensions subscribe; handlers return nothing.
-   Reactive concerns live here: permission detection, telemetry, UI, notifications.
-   Adding a reactive concern never modifies the core.
-2. **Provider seams (generative) — rationed.**
-   The rare concern that must _inject_ a value the core consumes synchronously registers a provider the core consults.
-   Today there is exactly one: the **workspace provider** (returns the child's working directory plus bracketed setup/teardown).
-   A provider seam is the only place the core is "open," so the list is kept as small as possible.
-
-The discriminator when deciding how a concern attaches:
-
-- It only needs to **know** what happened → subscribe to a lifecycle event (observational, unlimited).
-- It must **return a value the core consumes** → register a provider (generative, rationed).
-
-The governing rule — **no vacant hooks**: the architecture must _admit_ a seam without _shipping_ it until a concrete consumer exists.
-A provider seam with no consumer is a speculative abstraction that taxes every reader and that `fallow` flags as dead.
-Latent extensibility is the deliverable; a vacant hook is not.
-
-The [first-principles refinement](#first-principles-refinement-and-the-deeper-target) below sharpens this two-surface split.
-The awaited, behavior-affecting lifecycle events (notably `session-created` before `bindExtensions`) are _hooks_ — the child's own extension surface applied recursively, generative because the core waits on the handler before deciding what to do next.
-The observational surface then carries only fire-and-forget broadcasts of immutable snapshots, which no consumer can use to change the core.
-
-### Core responsibilities (keep)
-
-- **Agent definitions** — name, model, thinking, system prompt, tools list.
-- **Prompt composition** — system prompt assembly.
-- **Session lifecycle** — create child sessions, bind extensions, run conversation loop, track results.
-- **Concurrency management** — queue, abort, resume, max concurrency.
-- **Recursion guard** — remove pi-subagents' own three tools from child sessions (prevent infinite nesting).
-  With `isolated` removed (#264), children always load the parent's resources, so the guard is unconditional rather than gated on `cfg.extensions`.
-  This is the core defending its own invariant, keyed off its own tool names — not policy.
-- **Lifecycle events** — emit awaited, ordered events when child sessions spawn, are created, complete, and are disposed.
-- **Workspace provider seam** — accept a registered `WorkspaceProvider` and consult it for the child's cwd; default to the parent's cwd when none is registered.
-- **Service API** — publish `SubagentsService` via `Symbol.for()` for cross-extension access.
-
-### Responsibilities to remove
-
-- **Tool policy** (`disallowed_tools`) — access control belongs in pi-permission-system's `permission:` frontmatter.
-- **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
-- **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
-  Git worktrees are one _strategy_ for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
-  Evicted to `@gotgenes/pi-subagents-worktrees` (#263), the first consumer of the workspace provider seam.
-- **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — removed in #264.
-  Deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
-  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a _latent_ (un-built) provider seam, added only if a real consumer needs it.
-
-### Composition model
-
-In the target state, pi-subagents publishes events and a provider seam; other packages hook in:
-
-- **pi-permission-system** (observational) subscribes to child-session lifecycle events, detects subagent execution context in the child, and gates tool calls at runtime.
-- **pi-subagents-worktrees** (generative) registers a `WorkspaceProvider` that prepares a git worktree at run-start and tears it down after, supplying the child's cwd.
-- **pi-subagents-ui** (future, under reconsideration — see the [first-principles refinement](#first-principles-refinement-and-the-deeper-target)) subscribes to the broadcast and the query/behavior interfaces; the conversation viewer and `/agents` menu were removed in Phase 19 per [ADR-0004]; the surviving UI (widget, session navigator, settings command) stays in-core.
-- **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
-
-Composition test: install neither extension, only permissions, only workspaces, or both — the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
-
-This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert dependencies — extensions on a minimal core), and Phase 18 (reconsider UI).
-
-### First-principles refinement and the deeper target
-
-The two-surface model above is correct but coarse.
-Pushing it against our own principles — construct complete, state owns its mutations, tell-don't-ask, dependency inversion — surfaces sharper boundaries that the current code draws through the middle of classes.
-This subsection records the deeper target; the steps that realize it are sequenced in later phases.
-
-#### `Subagent` is four conflated domains
-
-The construction duality that motivates Phase 17 — a class that is simultaneously a passive record and an executor — is only the two most visible of four domains fused into one class.
-Pulling each apart by asking "who changes this, how often, and who needs to know" surfaces:
-
-1. **Lifecycle state** — status, result, error, timestamps.
-   Owned by the subagent; transitions are rare and meaningful; the right outward shape is an immutable snapshot announced on change.
-2. **Metrics** — tool uses, token usage, compaction count.
-   These are not lifecycle state; they are a projection aggregated over the child session's event stream.
-   `record-observer` already computes them — its only error is writing the aggregate back onto the subagent.
-3. **The hook surface** — the points where an extension alters or augments the child before and around its run.
-   This is the child session's own extension binding (see below), not data on the subagent.
-4. **Result delivery** — whether the parent has consumed the result, when to nudge, how the result reaches the caller.
-   The homeless `notification.resultConsumed` field belongs to this domain, not to execution.
-
-The ~20 optional constructor fields and the runtime `run()` throws are the pressure these four domains exert on one class.
-Separating them is what makes the Phase 17 steps fall out rather than fight back.
-
-#### The subagent is a recursive Pi
-
-A subagent is a child Pi session: created with `createAgentSession`, then `bindExtensions`.
-Its extension surface is therefore Pi's extension surface applied recursively — not a bespoke event bus.
-What the current doc calls "awaited, ordered lifecycle events" are not observations; they are **hooks**, structurally identical to Pi's own (`session_start`, `tool_execution_start`).
-The tell is the awaiting: the core waits for the handler because the handler's completion changes what the core does next — an extension registers before the child binds.
-A handler that can change subsequent behavior is generative, not observational, whatever we name the channel.
-
-This splits the current "lifecycle events" surface cleanly in two:
-
-1. **Broadcast** (observational, fire-and-forget) — "this happened; react if you want; you cannot change anything."
-   Carries immutable snapshots for telemetry, notification, and any renderer.
-   No consumer holds a live `Subagent`.
-2. **Hooks** (generative, awaited, ordered) — the recursive Pi extension surface where workspace, permissions, and future concerns attach to the child.
-   The `WorkspaceProvider` is one _typed_ hook; the general form is "be an extension of the child session."
-
-The "no vacant hooks" rule still governs the generative side: admit the surface, ship a hook only when a real consumer exists.
-
-#### Reactive versus discrete (not internal versus external)
-
-The axis that decides push versus pull is whether a need is reactive or discrete — never whether the consumer is in-package or out.
-
-- **Reactive** (ambient state that changes underneath you) → subscribe to the broadcast; be told.
-  The state-owner announces; the consumer maintains its own read-model; nobody pulls.
-- **Discrete** (a one-shot question: current value, full transcript) → pull a query.
-  `get_subagent_result`, `query_subagent_session`, opening a transcript, and the external `SubagentsService.getRecord` are queries by nature and stay pull, in-package or not.
-
-Behavior is a third interface: **tell by id, with outcomes**.
-`steer` and `abort` own their own rules — a non-running agent rejects a steer from inside `steer`, not via a caller's status pre-check — so coordinators never ask-then-tell.
-
-#### Consequences
+| Channel | Meaning |
+| --- | --- |
+| `subagents:started` | Agent begins running. |
+| `subagents:completed` | Agent reaches a terminal state. |
+| `subagents:resumed` | A retained session's resumed turn finishes. |
+| `subagents:failed` | Agent ends in error or stopped state. |
+| `subagents:compacted` | Child session compacts. |
+| `subagents:created` | Agent record exists before admission. |
+| `subagents:steered` | A steering message reaches a running agent. |
 
-Two consequences fall straight out, and both cut scope.
+The event names are defined in `src/service/service.ts`; the lifecycle observer
+and child-lifecycle publisher own payload construction. Consumers should use
+those code-owned contracts rather than a separately maintained payload schema.
 
-1. **The activity/metrics push tier is provisional.**
-   Its only reactive consumer is the inherited widget.
-   Treated from first principles, metrics are accumulated by an observer, exposed as a discrete query, and folded into the completion snapshot — so the high-frequency stream may not need to exist at all.
-   We do not contort the core's event design to feed an inherited consumer.
-2. **Phase 18 is "reconsider the UI," not "extract the UI."**
-   The widget and `/agents` menu predate the fork; they are consumers to be judged on our principles, not requirements to preserve.
-   If a UI survives, it survives as a reactive consumer of the broadcast and a caller of the query/behavior interfaces — built on our terms, possibly smaller, possibly removed.
-
-#### Sibling packages follow the same discipline
-
-`@gotgenes/pi-permission-system` is one of these hooks, and it is subject to the same scrutiny.
-Its boundaries deserve the same first-principles treatment: surface its conflated domains, distinguish what it observes from what it injects, and prefer being told over asking.
-The recursion principle means a consumer's internal design is not exempt because it lives in another package — the same axes (reactive versus discrete, hook versus broadcast, construct complete) apply across the seam.
-
-#### How we find these boundaries
-
-The boundaries above were not deduced top-down; they were surfaced by friction.
-Each place the target got _harder_ to test marked a domain seam drawn through the middle of a class.
-That method — testability friction as a boundary probe, with its limits — is recorded in the `improvement-discovery` skill so it outlives this phase.
-
-## Current structural analysis
-
-### Health metrics
-
-| Metric                     | Value                       |
-| -------------------------- | --------------------------- |
-| Health score               | 78/100 (B), end of Phase 19 |
-| Total LOC                  | 7,068 (57 files)            |
-| Dead code                  | 0 files, 0 exports          |
-| Maintainability index      | 91.0 (good)                 |
-| Avg cyclomatic complexity  | 1.4                         |
-| P90 cyclomatic complexity  | 2                           |
-| Production duplication     | 0 lines                     |
-| Test duplication           | 9 clone groups, 81 lines    |
-| Fallow refactoring targets | 0                           |
-
-### Dependency bag inventory
-
-These interfaces carry hidden dependencies that obscure true coupling.
-Bags with 10+ fields are the highest priority for decomposition.
-
-| Interface                     | Fields                                                       | Consumers                                         | Severity  |
-| ----------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | --------- |
-| `ResolvedSpawnConfig`         | 3 nested                                                     | spawn-config, agent-tool                          | ✓ done    |
-| `AgentSpawnConfig`            | execution options + parent identity                          | subagent-manager (internal)                       | ✓ done    |
-| `CreateSubagentSessionParams` | 6 (snapshot, type, cwd, parentSession, model, thinkingLevel) | create-subagent-session                           | ✓ done    |
-| `TurnLoopOptions`             | 4 (maxTurns, defaultMaxTurns, graceTurns, signal)            | subagent-session                                  | ✓ done    |
-| `SessionConfig`               | 6 (flat fields; extensions/noSkills/extras removed in #264)  | session-config (output of assembler)              | ✓ done    |
-| `NotificationDetails`         | 10                                                           | notification                                      | Low (DTO) |
-| `ResourceLoaderOptions`       | 10                                                           | create-subagent-session (SDK bridge)              | Low (SDK) |
-| `SubagentSessionIO`           | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1)       | create-subagent-session                           | ✓ done    |
-| `CreateSessionOptions`        | 9                                                            | create-subagent-session (SDK bridge)              | Low (SDK) |
-| `AgentToolDeps`               | 8                                                            | agent-tool                                        | ✓ done    |
-| `SubagentInit`                | 5 (id, type, description, invocation, execution, state)      | subagent (one production site)                    | ✓ done    |
-| `SubagentExecution`           | 12 (4 mandatory: factory, snapshot, prompt, baseCwd)         | subagent (mandatory collaborator)                 | ✓ done    |
-
-### Complexity hotspots
-
-Functions with cyclomatic complexity ≥ 21 (critical threshold):
-
-No functions remain above the critical threshold — all hotspots resolved in Phase 12. 6 functions remain at HIGH severity (CRAP ≥ 65); 13 at moderate.
-
-### Churn hotspots
-
-Files with highest commit frequency × complexity:
-
-| Score | File                          | Commits | Trend          |
-| ----- | ----------------------------- | ------- | -------------- |
-| 27.1  | `index.ts`                    | 109     | ▼ cooling      |
-| 9.6   | `tools/agent-tool.ts`         | 56      | ▼ cooling      |
-| 8.8   | `ui/agent-widget.ts`          | 22      | ▼ cooling      |
-| 7.3   | `lifecycle/subagent.ts`        | 22      | ▼ cooling      |
-| 6.6   | `service/service-adapter.ts`  | 15      | ▲ accelerating |
-| 6.3   | `config/custom-agents.ts`     | 13      | ▼ cooling      |
-
-`index.ts` remains the top churn hotspot but has cooled after the Phase 19 terminal cut removed its four `/agents`-wiring blocks; `service-adapter.ts` is now the sole accelerating file.
-
-### Production duplication
-
-The prior clone group between the execution and formatting paths was resolved in #172.
-The definition-management clone groups were removed with the `/agents` terminal cut in Phase 19 ([#441]); the supporting file-writer module was removed with them. Production duplication remains 0 lines.
-
-### Session encapsulation debt (Law of Demeter) — resolved by [#277] ✔️
-
-All consumer reach-throughs to the raw SDK `AgentSession` via `Subagent.session` have been eliminated.
-`Subagent.session` is removed; `SubagentSession.session` is marked `@internal` (lifecycle use only).
-The intent-revealing replacements added by [#277]:
-
-| Reach-through                            | Sites                                                                              | Replacement                                        |
-| ---------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
-| Steer buffer-or-deliver (was duplicated) | `service-adapter.ts`, `steer-tool.ts`                                              | `Subagent.steer(message)`                          |
-| Conversation viewing                     | `session-navigation.ts`, `session-navigator.ts`                                   | `Subagent.agentMessages` / transcript sources     |
-| Session-readiness guard                  | `agent-tool.ts`, `subagent-manager.ts`                                             | `Subagent.isSessionReady()`                        |
-| Context-window stats                     | `steer-tool.ts`, `get-result-tool.ts`, `notification.ts`                           | `Subagent.getContextPercent()`                     |
-| Live updates (subscription)              | `session-navigator.ts`                                                             | `Subagent.subscribeToUpdates(fn)`                  |
-| Session disposal                         | `subagent-manager.ts`                                                              | `SubagentSession.dispose()` — resolved by [#265]   |
-
-### Proposed bag decompositions
-
-#### ResolvedSpawnConfig (15 fields → 3 value objects)
-
-This bag mixes three concerns: who the agent is, how it should run, and how it should be displayed.
-Each consumer uses a different subset.
-
-```typescript
-/** Who this agent is — type resolution result. */
-interface SpawnIdentity {
-  subagentType: string;
-  rawType: SubagentType;
-  fellBack: boolean;
-  displayName: string;
-}
-
-/** How the agent should run — execution parameters. */
-interface SpawnExecution {
-  prompt: string;
-  description: string;
-  model: Model<any> | undefined;
-  effectiveMaxTurns: number | undefined;
-  thinking: ThinkingLevel | undefined;
-  inheritContext: boolean;
-  mode: SubagentMode;
-  timeoutSeconds?: number;
-  agentInvocation: AgentInvocation;
-}
-
-/** How the agent is presented — display metadata. */
-interface SpawnPresentation {
-  modelName: string | undefined;
-  agentTags: string[];
-  detailBase: Pick<AgentDetails, ...>;
-}
-```
-
-`agent-tool` consumes all three to build the internal `AgentSpawnConfig` and the result text.
-The joined/detached mode lives in `SpawnExecution`; no separate foreground/background runner exists.
-After decomposition, each consumer declares its real dependencies explicitly.
-
-#### AgentSpawnConfig — ParentSessionInfo extracted (done, [#166][166])
-
-The `parentSessionFile`, `parentSessionId`, and `toolCallId` fields were grouped into `ParentSessionInfo`:
-
-```typescript
-/** Parent session identity — always travel together from the tool boundary. */
-export interface ParentSessionInfo {
-  parentSessionFile?: string;
-  parentSessionId?: string;
-  toolCallId?: string;
-}
-```
-
-`AgentSpawnConfig` now carries `parentSession?: ParentSessionInfo` instead of three flat optional fields.
-
-#### RunOptions (12 fields → extract RunContext) — done ([#169][169]), updated by [#231]
-
-`RunContext` was extracted and nested as `RunOptions.context` in #169.
-Issue #231 moved the two static dependencies (`exec`, `registry`) to `RunnerDeps` on `ConcreteAgentRunner`, leaving `RunContext` with only per-call fields:
-
-```typescript
-/** Per-call execution context — fields that vary per spawn. */
-export interface RunContext {
-  cwd?: string;
-  parentSession?: ParentSessionInfo;
-}
-```
-
-The current execution seam is `SubagentExecution` in `lifecycle/subagent.ts`; it carries the immutable parent snapshot, joined/detached mode, runtime deadline, session factory, and lifecycle collaborators directly. The old runner-specific `RunOptions` bag is no longer part of the source tree.
-
-#### SessionConfig (11 fields → extract ToolFilterConfig) — done ([#168][168])
-
-The tool-filtering cluster (`toolNames`, `disallowedSet`, `extensions`) was extracted into `ToolFilterConfig` and nested as `SessionConfig.toolFilter`.
-`filterActiveTools` now accepts a single `ToolFilterConfig` argument instead of three positional parameters.
-`SessionConfig` reduced from 10 to 8 top-level fields.
-
-#### Session factory IO (9 methods → 2 focused interfaces) — done ([#167][167])
-
-The IO boundary was split into two focused interfaces:
-
-```typescript
-/** Environment discovery — detect runtime context and resolve directories. */
-export interface EnvironmentIO {
-  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
-  getAgentDir: () => string;
-  deriveSessionDir: (
-    parentSessionFile: string | undefined,
-    effectiveCwd: string,
-  ) => string;
-}
-
-/** Session factory — create SDK objects for a child agent session. */
-export interface SessionFactoryIO {
-  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
-  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
-  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
-  createSession: (
-    opts: CreateSessionOptions,
-  ) => Promise<{ session: AgentSession }>;
-  assemblerIO: AssemblerIO;
-}
-```
-
-The factory consumes the `EnvironmentIO & SessionFactoryIO` boundary directly; no runner implementation or compatibility alias remains.
-
-## Phase 11 (complete)
-
-Phase 11 converted all closure factories to classes, eliminating adapter closure density in `index.ts`.
-Four layers: SessionContext typing → runtime query methods → interface alignment → class conversions → index.ts simplification.
-See [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md) for details.
-
-## Phase 12 (complete)
-
-Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures.
-All four steps are closed: [#205], [#206], [#207], [#208].
-
-## Phase 13 (complete)
-
-Phase 13 addressed remaining closure factories, the last fallow refactoring target, oversized methods, production duplication, SDK boundary coupling, and test clone families.
-All six steps are closed: [#214], [#215], [#216], [#217], [#218], [#219].
-See [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md) for details.
-
-## Phase 14 (complete)
-
-Phase 14 removed tool and extension policy enforcement from pi-subagents, eliminating overlap with pi-permission-system.
-All four steps are closed: [#237], [#238], [#239], [#242].
-See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
-
-[#237]: https://github.com/gotgenes/pi-packages/issues/237
-[#238]: https://github.com/gotgenes/pi-packages/issues/238
-[#239]: https://github.com/gotgenes/pi-packages/issues/239
-[#242]: https://github.com/gotgenes/pi-packages/issues/242
-
-## Phase 15 (complete)
-
-Phase 15 evolved `Agent` from a passive state machine (`AgentRecord`) into an object that owns its entire execution lifecycle.
-Before Phase 15, `AgentManager` orchestrated everything: calling the runner, handling session creation, wiring observers, and cleaning up worktrees — reaching into Agent 10+ times across `spawn()` and `startAgent()`.
-After Phase 15, Agent is born complete with all dependencies and configuration, owns `run()` and `resume()`, and manages its own observer and worktree lifecycle.
-All six steps are closed: [#227], [#228], [#231], [#229], [#230], [#232].
-See [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md) for details.
-
-## Phase 16 (complete)
-
-Phase 16 inverted the core's outbound dependencies: worktree isolation joined permissions as an _extension_ on a minimal core, leaving pi-subagents a pure child-session orchestrator.
-The core now attaches extensions through exactly two surfaces — observational lifecycle events (unlimited) and rationed generative provider seams (today only the workspace provider) — and has zero knowledge of its consumers.
-The "runner" concept is gone: `createSubagentSession()` returns a born-complete `SubagentSession` that owns turn driving, steering, and disposal, and `Subagent.run()` is coordination, not assembly.
-The decision and the full reasoning chain are recorded in [ADR-0002]; the two-surface extension model is described under [Target architecture](#target-architecture).
-All five steps are closed: [#261], [#262], [#263], [#264], [#265].
-The earlier "agent collaborator architecture" framing (#256 superseded, #257 parked, #258 and #259 closed not-planned) was abandoned; its structural win was reached cleanly via the workspace seam.
-See [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md) for details.
-
-## Phase 17 (complete)
-
-Phase 17 consolidated the core's remaining structural debt before the UI reconsideration (Phase 18).
-The `Subagent` record/executor duality was resolved by extracting `SubagentState` (status, result, timestamps, metrics) into a private owned value object and making `SubagentExecution` a mandatory constructor collaborator — eliminating ~20 optional fields and the two "not configured for execution" runtime throws.
-The concurrency queue was replaced with a thunk-based `ConcurrencyLimiter` that knows nothing about agents or IDs.
-Run collaborators (`RunListeners`, `WorkspaceBracket`) were extracted from the 455-LOC `Subagent` class.
-The inline `SubagentManagerObserver` literal was promoted to `SubagentEventsObserver`, making its three concerns (event emission, record persistence, notification dispatch) unit-testable in isolation.
-Widget delegation and the post-construction `runtime.widget =` write were removed from `SubagentRuntime` by dissolving the notification→widget cycle via `AgentWidget.seedFinishedAgents`.
-Lifecycle, UI/tools, and cross-package test fixture clones were consolidated.
-`loadLayeredSettings<T>` was extracted to `src/layered-settings.ts` and published via the `@gotgenes/pi-subagents/settings` subpath export, eliminating the 23-line production clone with `pi-subagents-worktrees`.
-All nine steps are closed: [#381], [#373], [#374], [#375], [#376], [#377], [#378], [#379], [#380].
-[#412] unified the overlapping session-mock builders identified during Step 7.
-[#415] migrated `pi-subagents-worktrees` to `loadLayeredSettings` after the Step 9 published release.
-See [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md) for the full findings, step outcomes, dependency diagram, and tracks.
-
-## Phase 18 (complete)
-
-Phase 18 disentangled the activity tier from the core and recorded a first-principles decision about the UI's direction.
-Steps 1–5 (the spine) consolidated all run state onto `SubagentState`, deleted `AgentActivityTracker` and `ui-observer` (−145 LOC), and made the widget a pure reactive consumer of lifecycle events with no inbound calls from core spawn tools.
-Step 6 reconciled the public event contract (breaking: removed the vacant `SUBAGENT_EVENTS.ACTIVITY` channel; added `FAILED`, `COMPACTED`, `CREATED`, `STEERED`).
-Step 7 consolidated residual test clone families, dropping from 24 to 14 clone groups (below the <15 target).
-Step 8 captured the per-component UI decisions in [ADR-0004]: the widget shrinks to background agents only; the bespoke `ConversationViewer` is replaced by native session navigation (a read-only transcript via `parseSessionEntries`, per the Step 1 spike — see [ADR-0004]'s addendum); the `/agents` command is dissolved (remove the create wizard and agent-types editor, extract settings to a focused command); the surviving UI stays in-core as a substitutable reactive consumer.
-Source LOC decreased from 7,751 (62 files) to 7,650 (61 files); tests grew from 1,031 to 1,047.
-All eight steps are closed: [#420], [#421], [#422], [#423], [#424], [#425], [#426], [#427].
-See [phase-18-reconsider-ui.md](history/phase-18-reconsider-ui.md) for the full findings, step outcomes, dependency diagram, and tracks.
-
-## Phase 19 (complete)
-
-Phase 19 implemented the per-component UI decisions recorded in [ADR-0004]: it shrank the widget to background-only agents, replaced the bespoke conversation viewer with native session navigation dual-sourced by liveness (live record or persisted-file snapshot) and rendered through Pi's own per-entry TUI components, extracted subagent settings to a focused `/subagents-settings` command, and dissolved the monolithic `/agents` menu in a two-commit terminal cut (hub first, then the orphaned agent-definition-management subtree).
-Production duplication dropped to 0 lines; test clone groups dropped from 16 to 9 (target: ≤ 10); source shrank from 7,650 LOC (61 files) to 7,068 LOC (57 files).
-All nine steps are closed: [#446], [#447], [#444], [#445], [#462], [#463], [#442], [#441], [#443].
-A follow-on issue, [#470] (README staleness after the terminal cut), was filed and closed independently.
-See [phase-19-implement-ui-decisions.md](history/phase-19-implement-ui-decisions.md) for the full findings, step outcomes, dependency diagram, and tracks.
-
-## Phase 20 improvement roadmap
-
-> Planning note: this roadmap records the pre-execution-control baseline. The
-> joined/detached execution-control work below supersedes any obsolete runner,
-> unbounded-result, and foreground/background vocabulary in these notes.
-
-Phase 20 realizes the last un-extracted domain from the [first-principles refinement](#first-principles-refinement-and-the-deeper-target) — **result delivery** — and clears the residual boundary and complexity debt discovery surfaced around it.
-
-Discovery findings (fallow + entry-point trace + test-constructibility audit, 2026-07-03):
-
-1. `NotificationState` (`toolCallId`, `resultConsumed`) still lives on `Subagent`; `get-result-tool` reaches through `record.notification?.markConsumed()` twice, always paired with `notifications.cancelNudge(id)` — the doc's own "homeless field" (result-delivery domain) plus a scattered two-step reset.
-2. Both `steer-tool` and `service-adapter` pre-check `status !== "running"` before calling `record.steer()` — ask-then-tell, contradicting the target's "tell by id, with outcomes" rule.
-3. Five file-level eslint-disable headers (`agent-tool` disables 6 rules; `spawn-config` and `agent-widget` 4 each; `model-resolver` 2; `index` 1) and `model: unknown`/`Model<any>`/`any` threading through 8 files mark the SDK type boundary as the largest remaining `any` surface.
-4. Three src functions carry HIGH CRAP scores (notification renderer arrow 79.4, `service-adapter.spawn` 71.3, `get-result-tool.execute` 63.6 — resolved by Step 2); `subagents-settings.handle` (13 cyclomatic, 24 cognitive) is three copy-pasted select→input→validate→apply branches; `service-adapter.ts` is the sole accelerating churn file.
-5. `createTestSubagent` is the most complex function in the workspace (19 cyclomatic, 25 cognitive) because `SubagentStateInit` accepts only transition fields, forcing mutation loops to seed metrics — a Category D "shared factory complexity" signal pointing at the production init surface.
-6. Test duplication sits at 9 in-package clone groups (81 lines), at the ≤ 10 target but with two consolidatable clone families.
-
-No finding scores ≥ 20 on the priority scale (Impact × (6 − Risk)); the phase is a should-fix band (10–15) consolidation.
-Directory organization is healthy (seven domain directories, six root files) — no reorg this phase.
-
-### Health metrics (Phase 20)
-
-| Metric                                           | Phase 19 (end)   | Phase 20 target        |
-| ------------------------------------------------ | ---------------- | ---------------------- |
-| Health score                                     | 78/100 (B)       | ≥ 78 (B)               |
-| Source LOC                                       | 7,068 (57 files) | ~7,050 (no net growth) |
-| `record.notification?.` reach-throughs           | 4 sites          | 0                      |
-| Steer status pre-checks outside `Subagent.steer` | 2 sites          | 0                      |
-| src functions with CRAP ≥ 60                     | 3                | 0                      |
-| File-level eslint-disable headers                | 5                | ≤ 2                    |
-| `createTestSubagent` cyclomatic                  | 19               | ≤ 8                    |
-| Test clone groups (in-package)                   | 9 (81 lines)     | ≤ 5 (≤ 40 lines)       |
-
-### Steps
-
-#### ✅ Step 1 — Extract result delivery from `Subagent` ([#535])
-
-Result delivery evolved twice. `notification-state.ts` was first dissolved and `Subagent.toolCallId` moved to execution identity. Consumption now lives as domain state on `SubagentState`, where retention and every push/pull delivery path can consult it. `NotificationManager` owns only delivery timing: it withholds records during a parent run and rechecks consumption at `agent_settled`, eliminating the uncancellable follow-up race rather than relying on a timer window.
-
-`Release: batch "result-delivery"`
-
-#### ✅ Step 2 — Decompose `get-result-tool.execute` ([#536])
-
-Smell: Category B (oversized function) — 61 lines, 15 cyclomatic, CRAP 63.6; mixes wait/consume policy, stats formatting, and output assembly.
-Target files:
-
-- `src/tools/get-result-tool.ts` — extract a pure report formatter (status line, stats parts, body selection) alongside the existing `result-renderer.ts` pattern; consume via the Step 1 delivery interface.
-- `test/tools/get-result-tool.test.ts` — unit-test the pure formatter directly.
-
-Outcome: `execute` ≤ 30 lines with cyclomatic < 10; off the fallow high-complexity list.
-
-Landed: bounded result formatting was extracted while the earlier result-delivery design was active. The later execution-control clean break removed the standalone report module and its unbounded wait path; `GetResultTool` now owns a nonblocking, bounded status/result projection.
-`get-result-tool.execute` remains a focused lookup-and-render boundary.
-
-`Release: batch "result-delivery"`
-
-#### ✅ Step 3 — `Subagent.steer` returns an outcome ([#537])
-
-Smell: Category C (ask-then-tell) — coordinators pre-check status before telling.
-Target files:
-
-- `src/lifecycle/subagent.ts` — `steer` owns the non-running rejection and returns a discriminated outcome (`delivered` / `buffered` / `rejected` with the observed status).
-- `src/tools/steer-tool.ts`, `src/service/service-adapter.ts` — drop the status pre-checks and switch on the outcome; the adapter maps the outcome to the public `SubagentsService.steer` boolean, so the published contract is unchanged.
-
-Outcome: zero steer status pre-checks outside `Subagent.steer`; `steer-tool.execute` cyclomatic drops below 10.
-
-Landed: `Subagent.steer` returns a discriminated `SteerOutcome` (`delivered` / `buffered` / `rejected` with the observed status) and owns the non-running rejection as its first guard; `SteerOutcome` is exported from `subagent.ts` and re-exported via `types.ts`.
-`SteerTool.execute` and `SubagentsServiceAdapter.steer` dropped their `status !== "running"` pre-checks and switch on the outcome — the adapter maps `outcome.kind !== "rejected"` to the unchanged public boolean, and the tool's delivered-path stats moved into a private `renderDelivered` helper.
-Zero steer status pre-checks remain outside `Subagent.steer`.
-
-`Release: independent`
-
-#### ✅ Step 4 — Type the model boundary ([#538])
-
-Smell: Category C (platform type threading) — `ModelRegistry.find/getAll/getAvailable` return `any`, forcing `any`/`unknown` model threading through `model-resolver`, `spawn-config`, `service-adapter`, and `parent-snapshot`.
-Target files:
-
-- `src/session/model-resolver.ts` — type the registry against `Model<any>` from `@earendil-works/pi-ai` (already imported elsewhere); remove the file-level eslint-disable; extract the fuzzy-scoring loop as a named helper if `resolveModel` (17 cyclomatic, 60 lines) still trips the threshold.
-- `src/service/service-adapter.ts` — type the resolved model in `spawn` (16 cyclomatic, CRAP 71.3, sole accelerating churn file) and extract the model-resolution branch.
-- `src/tools/spawn-config.ts` — shrink the 4-rule file-level disable to line-level or remove it.
-
-Outcome: `model-resolver.ts` file-level eslint-disable removed; `service-adapter.spawn` off the HIGH CRAP list; `any` model returns eliminated from the resolver.
-
-Landed: `ModelRegistry.find/getAll/getAvailable` and `resolveModel`'s return are typed against `Model<any>` from `@earendil-works/pi-ai`; the file-level eslint-disable headers on `model-resolver.ts` (2 rules) and `spawn-config.ts` (4 rules) are both removed — running disable-header tally 5 → 3 (`agent-tool` 6, `agent-widget` 4, `index` 1 remain, all Step 5 scope).
-`resolveModel`'s fuzzy-scoring loop was extracted to a private `findBestFuzzyMatch` helper, dropping `resolveModel` off the complexity list entirely.
-`service-adapter.spawn`'s model-resolution branch was extracted to a private `resolveModelOption`, dropping `spawn` from 16 cyclomatic / CRAP 71.3 (HIGH) to 13 cyclomatic / CRAP 49.5 (moderate) — off the HIGH-CRAP list; running HIGH-CRAP tally 2 → 1 remaining (the notification renderer arrow, untouched — Step 7 scope).
-`resolveInvocationModel` gained a `registry: ModelRegistry | undefined` guard (typed error instead of a crash when a model override is requested with no registry present); the residual `unknown` thread through `ParentSnapshot.model` / `SessionContext.model` is a separate SDK-boundary gap, deferred.
-
-`Release: independent`
-
-#### Step 5 — Narrow `tui`/`theme` render interfaces ([#539])
-
-Smell: Category C/D (platform type threading; wide `any` params in render callbacks).
-Target files:
-
-- `src/ui/agent-widget.ts` — replace `tui: any` with a lean local interface (`terminal.columns`, `requestRender()`); shrink the 4-rule file-level disable.
-- `src/tools/agent-tool.ts` — type `renderCall`/`renderResult` params (`theme`, `result`) with lean local interfaces; shrink the 6-rule file-level disable to the genuinely SDK-gapped lines.
-Some disables are irreducible SDK export gaps; the goal is line-level precision, not zero.
-
-Outcome: file-level eslint-disable headers 5 → ≤ 2; remaining suppressions are line-level with named rules.
-
-`Release: independent`
-
-#### Step 6 — Table-driven settings handler ([#540])
-
-Smell: Category B (function duplication inside one function) — `subagents-settings.handle` (13 cyclomatic, 24 cognitive, 52 lines) repeats the select→input→parse→validate→apply→notify flow three times.
-Target files:
-
-- `src/ui/subagents-settings.ts` — describe each numeric setting as a descriptor (label, prompt, minimum, validation message, apply method) and drive one loop over the table.
-- `test/ui/subagents-settings.test.ts` — assert per-descriptor behavior.
-
-Outcome: `handle` cyclomatic ≤ 6 and cognitive ≤ 10; off the fallow high-complexity list.
-
-`Release: independent`
-
-#### Step 7 — Decompose the notification renderer ([#541])
-
-Smell: Category B/D (oversized arrow, untested complexity) — the renderer arrow in `src/observation/renderer.ts` is fallow's top triage concern (17 cyclomatic, CRAP 79.4).
-Target files:
-
-- `src/observation/renderer.ts` — extract pure line-assembly helpers (status→icon/label selection, stats-parts assembly, preview truncation) that are unit-testable without `Text` or a theme; the arrow becomes a thin wrapper.
-- `test/observation/renderer.test.ts` — test the pure helpers directly.
-
-Soft ordering: land after Step 1 so the notification-domain files settle first.
-
-Outcome: renderer arrow cyclomatic < 10; `renderer.ts` off the top of the fallow triage list.
-
-`Release: independent`
-
-#### Step 8 — Full-value `SubagentStateInit` ([#542])
-
-Smell: Category D (shared factory complexity → narrow/complete the production init surface) — `createTestSubagent` (19 cyclomatic, 25 cognitive) seeds metrics via mutation loops because `SubagentStateInit` accepts only transition fields.
-Target files:
-
-- `src/lifecycle/subagent-state.ts` — extend `SubagentStateInit` to optionally seed the full value (toolUses, lifetimeUsage, compactionCount, turnCount, activeTools, responseText); a value object is legitimately constructible at any point in its value space.
-- `test/helpers/make-subagent.ts` — collapse the mutation loops into direct init.
-
-Outcome: `createTestSubagent` cyclomatic ≤ 8; off the fallow complexity list; no production behavior change.
-
-`Release: independent`
-
-#### Step 9 — Consolidate remaining test clone families ([#543])
-
-Smell: Category D (test duplication) — two clone families (`spawn-config.test.ts`: 2 groups / 21 lines; `subagent-manager.test.ts`: 2 groups / 15 lines) plus the `session-config.test.ts` pair (16 lines).
-Target files: the three test files and `test/helpers/` as needed.
-
-Runs last — Steps 1–3 and 8 rewrite portions of these suites, so consolidating first would churn twice.
-
-Outcome: in-package clone groups 9 → ≤ 5; duplicated lines 81 → ≤ 40.
-
-`Release: independent`
-
-### Step dependencies
+These are fire-and-forget broadcast events — no request IDs, no reply channels.
 
-```mermaid
-flowchart LR
-    S1["✅ Step 1 (#535)<br/>Result delivery off Subagent"] --> S2["✅ Step 2 (#536)<br/>Decompose get-result-tool"]
-    S1 -.soft.-> S7["Step 7 (#541)<br/>Decompose notification renderer"]
-    S3["✅ Step 3 (#537)<br/>Steer returns an outcome"]
-    S4["✅ Step 4 (#538)<br/>Type the model boundary"]
-    S5["Step 5 (#539)<br/>Narrow tui/theme interfaces"]
-    S6["Step 6 (#540)<br/>Table-driven settings handler"]
-    S8["Step 8 (#542)<br/>Full-value SubagentStateInit"] --> S9["Step 9 (#543)<br/>Consolidate test clones"]
-    S2 --> S9
-    S3 --> S9
-```
+## Extension composition
+
+The core owns child-session orchestration. Companion extensions attach through
+lifecycle observation or a concrete provider seam, rather than reaching into
+`SubagentManager` or making the core look up a named consumer.
+
+### Observation and providers
+
+- Child-execution lifecycle publication exposes spawning, pre-bind session
+  creation, completion, and disposal to consumers. Session creation is published
+  before extension binding so a companion can identify the child at that boundary.
+- Agent lifecycle broadcasts report immutable event data. They are notifications,
+  not prompt or result replacement APIs.
+- A workspace provider supplies the child's working directory and bracketed
+  cleanup. With no provider, the child runs in the parent's working directory.
+- Ordered lifecycle interceptors can replace prompts or candidate results, abort a
+  turn, or request bounded same-session continuation. Registration order,
+  cancellation, failure, and disposal follow [ADR-0005].
+
+The governing rule is **no vacant hooks**: admit a seam in the design, but ship it
+only when a concrete consumer needs it. Permissions and workspace strategies
+compose independently; the core depends on neither implementation.
+
+### State, queries, and behavior
+
+Run state has one owner. Observers accumulate statistics and activity from the
+child session; tools and UI read the resulting state rather than counting again.
+Reactive UI keeps its own bounded read model. Discrete questions—status, results,
+and transcript queries—remain bounded pull operations. Steering and stop requests
+are behaviors whose owner checks whether the transition is valid, not a sequence
+of caller-side status checks followed by external mutation.
+
+Mutable parent identity and prompt inputs are frozen before admission. The
+canonical parent model/authentication runtime is shared deliberately, preserving
+runtime registrations without retaining a live session context. Cleanup is owned
+at resource boundaries, and a queued run has an awaitable settlement even before
+its concurrency slot opens.
+
+### Engineering boundaries
+
+The entry point constructs collaborators and binds Pi APIs. Domain modules receive
+explicit dependencies; environment discovery and session-factory I/O are separate
+boundaries so tests can drive real behavior without module-mocking choreography.
+Rendering helpers consume values, while Pi-specific components own terminal
+integration. Shared test setup may be extracted, but the operation under test
+stays visible rather than hidden merely to reduce duplication metrics.
+
+The root service and `./settings` are public package exports. Type declarations
+are generated and bundled independently of the shipped TypeScript runtime source;
+[ADR-0003] owns that packaging decision. Public interfaces and durable user data
+carry compatibility obligations; internal structures remain code-owned.
+
+## Fork ownership
+
+`@nklisch/pi-subagents` is maintained in the `nklisch/pi-extensions` monorepo.
+[Fork maintenance](../FORK-MAINTENANCE.md) owns provenance, release policy, and the
+upstream relationship. [Comparison with upstream](../comparison-with-upstream.md)
+explains the product boundary; upstream ideas are not automatic parity work.
 
-### Parallel tracks
-
-- **Track A — Result delivery:** Steps 1 → 2, then 7 (soft).
-- **Track B — Tell-don't-ask:** Step 3.
-- **Track C — SDK boundary:** Steps 4, 5 (independent of each other).
-- **Track D — UI polish:** Step 6.
-- **Track E — Test health:** Step 8, then 9 (9 also waits on Tracks A/B test churn).
-
-Tracks A–D can proceed in parallel; only Step 9 serializes behind the rest.
-
-### Release batches
-
-- **Batch "result-delivery":** Steps 1, 2 (ship together; tail = Step 2).
-- Independently releasable: Steps 3, 4, 5, 6, 7, 8, 9.
-
-Every step lands as a `refactor:`/`test:` commit — hidden changelog types that cut no release on their own; the work auto-batches into the next unhidden release.
-
-## Refactoring history
-
-Phases 1–5, 7–19 are complete.
-Phase 6 (UI extraction to a separate package) was deferred to Phase 18; its intent was resolved by [ADR-0004] (Phase 18 Step 8).
-Detailed records are preserved in per-phase history files:
-
-| Phase | Title                                               | Status                 | History                                                                              |
-| ----- | --------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------ |
-| 1     | Export SubagentsService API boundary                | Complete               | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
-| 2     | Remove scheduling subsystem                         | Complete               | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
-| 3     | Remove group-join, RPC; replace output-file         | Complete               | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
-| 4     | Implement and publish SubagentsService              | Complete               | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
-| 5     | Decompose index.ts                                  | Complete               | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
-| 6     | Extract UI to separate package                      | Superseded by ADR-0004 | —                                                                                    |
-| 7     | Encapsulation and dependency narrowing              | Complete               | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
-| 8     | Testability, display extraction, menu decomposition | Complete               | [phase-8-testability.md](history/phase-8-testability.md)                             |
-| 9     | Observation consolidation, ctx elimination          | Complete               | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
-| 10    | Domain organization, bag decomposition, complexity  | Complete               | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
-| 11    | Closure factories to classes                        | Complete               | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
-| 12    | Complexity reduction and test fixture extraction    | Complete               | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
-| 13    | Remaining structural smells                         | Complete               | [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md)                 |
-| 14    | Strip policy from core                              | Complete               | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
-| 15    | Domain model evolution                              | Complete               | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
-| 16    | Invert dependencies (extensions on a minimal core)  | Complete               | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
-| 17    | Core consolidation                                  | Complete               | [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md)             |
-| 18    | Reconsider UI (first principles)                    | Complete               | [phase-18-reconsider-ui.md](history/phase-18-reconsider-ui.md)                       |
-| 19    | Implement ADR-0004 UI decisions                     | Complete               | [phase-19-implement-ui-decisions.md](history/phase-19-implement-ui-decisions.md)     |
-
-### Structural refactoring issues
-
-| Phase                | Issue                                                      | Summary                                                                                                                                                                                        |
-| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Foundation           | #69, #71, #76, #80                                         | SubagentRuntime, pure assembler, cwd injection, config consolidation                                                                                                                           |
-| Core decomposition   | #84, #72, #87, #70                                         | WorktreeManager, AgentManager DI, runtime methods, handler extraction                                                                                                                          |
-| Interface polish     | #66, #77                                                   | SDK types, projectAgentsDir                                                                                                                                                                    |
-| Features             | #61                                                        | JSONL session transcripts                                                                                                                                                                      |
-| AgentManager         | #98, #99, #100, #102                                       | Record state machine, ParentSnapshot, session-event observation, test factory                                                                                                                  |
-| Encapsulation        | #108, #109, #110, #111, #112, #113, #114, #115, #116, #118 | Registry, settings, activity tracker, record lifecycle, observer, spawn options, deps narrowing, tool split, type housekeeping                                                                 |
-| Testability          | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                                                              |
-| Observation/ctx      | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                                                                  |
-| Phase 10             | #164, #165, #166, #167, #168, #169, #170, #171, #172       | Domain directories, ResolvedSpawnConfig, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult, content-items                                       |
-| Phase 11             | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                                                               |
-| Phase 12             | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                                                        |
-| Phase 13             | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                                                       |
-| Phase 14             | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                                                                     |
-| Phase 15             | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                                                                     |
-| Phase 16             | #261, #262, #263, #264, #265                               | Lifecycle events (retire permission-bridge), WorkspaceProvider seam, extract worktrees package, remove isolated, born-complete execution / dissolve runner                                     |
-| Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above ([ADR-0002])                                                                                                        |
-| Phase 17             | #381, #373, #374, #375, #376, #377, #378, #379, #380       | ConcurrencyLimiter, SubagentState, run-start encapsulation, run collaborators, events observer, widget decoupling, lifecycle test fixtures, UI/tools test fixtures, settings-loader extraction |
-| Phase 17 (follow-on) | #412, #415                                                 | Session-mock builder unification, worktrees settings-helper migration                                                                                                                          |
-| Phase 18             | #420, #421, #422, #423, #424, #425, #426, #427             | Fold metrics onto record, migrate readers, delete activity tier, widget self-drives, drop widget from tool, reconcile event contract, consolidate test clones, UI-direction ADR                |
-| Phase 19             | #446, #447, #444, #445, #462, #463, #442, #441, #443       | ADR-0004 spike, settings command, background widget, native session nav slice, TUI renderer, file-snapshot source, dissolve /agents + viewer, remove definition mgmt, consolidate test clones  |
-| Phase 19 (follow-on) | #470                                                       | README refresh for the removed /agents command surface                                                                                                                                         |
-
-The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
-
-## Relationship with upstream
-
-This fork (`@gotgenes/pi-subagents` in the [gotgenes/pi-packages] monorepo) is a hard fork of [tintinweb/pi-subagents].
-The decomposition diverges materially from upstream's direction.
-
-The three upstream PRs (#71, #72, #73) remain open.
-If they land, upstream gains the peer-dep fix and the two RepOne patches.
-This fork continues independently regardless.
-
-Upstream fixes and ideas are cherry-picked when they align with this fork's scope.
-The upstream test suite is run periodically as a regression canary for the session assembly core.
-
-[earendil-works/pi#4207]: https://github.com/earendil-works/pi/issues/4207
-[gotgenes/pi-packages]: https://github.com/gotgenes/pi-packages
-[tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents
-[166]: https://github.com/gotgenes/pi-packages/issues/166
-[167]: https://github.com/gotgenes/pi-packages/issues/167
-[168]: https://github.com/gotgenes/pi-packages/issues/168
-[169]: https://github.com/gotgenes/pi-packages/issues/169
-[#205]: https://github.com/gotgenes/pi-packages/issues/205
-[#206]: https://github.com/gotgenes/pi-packages/issues/206
-[#207]: https://github.com/gotgenes/pi-packages/issues/207
-[#208]: https://github.com/gotgenes/pi-packages/issues/208
-[#214]: https://github.com/gotgenes/pi-packages/issues/214
-[#215]: https://github.com/gotgenes/pi-packages/issues/215
-[#216]: https://github.com/gotgenes/pi-packages/issues/216
-[#217]: https://github.com/gotgenes/pi-packages/issues/217
-[#218]: https://github.com/gotgenes/pi-packages/issues/218
-[#219]: https://github.com/gotgenes/pi-packages/issues/219
-[#227]: https://github.com/gotgenes/pi-packages/issues/227
-[#228]: https://github.com/gotgenes/pi-packages/issues/228
-[#229]: https://github.com/gotgenes/pi-packages/issues/229
-[#230]: https://github.com/gotgenes/pi-packages/issues/230
-[#231]: https://github.com/gotgenes/pi-packages/issues/231
-[#232]: https://github.com/gotgenes/pi-packages/issues/232
-[#261]: https://github.com/gotgenes/pi-packages/issues/261
-[#262]: https://github.com/gotgenes/pi-packages/issues/262
-[#263]: https://github.com/gotgenes/pi-packages/issues/263
-[#264]: https://github.com/gotgenes/pi-packages/issues/264
-[#265]: https://github.com/gotgenes/pi-packages/issues/265
-[#277]: https://github.com/gotgenes/pi-packages/issues/277
-[#373]: https://github.com/gotgenes/pi-packages/issues/373
-[#374]: https://github.com/gotgenes/pi-packages/issues/374
-[#375]: https://github.com/gotgenes/pi-packages/issues/375
-[#376]: https://github.com/gotgenes/pi-packages/issues/376
-[#377]: https://github.com/gotgenes/pi-packages/issues/377
-[#378]: https://github.com/gotgenes/pi-packages/issues/378
-[#379]: https://github.com/gotgenes/pi-packages/issues/379
-[#380]: https://github.com/gotgenes/pi-packages/issues/380
-[#381]: https://github.com/gotgenes/pi-packages/issues/381
-[#412]: https://github.com/gotgenes/pi-packages/issues/412
-[#415]: https://github.com/gotgenes/pi-packages/issues/415
-[#420]: https://github.com/gotgenes/pi-packages/issues/420
-[#421]: https://github.com/gotgenes/pi-packages/issues/421
-[#422]: https://github.com/gotgenes/pi-packages/issues/422
-[#423]: https://github.com/gotgenes/pi-packages/issues/423
-[#424]: https://github.com/gotgenes/pi-packages/issues/424
-[#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
-[#441]: https://github.com/gotgenes/pi-packages/issues/441
-[#442]: https://github.com/gotgenes/pi-packages/issues/442
-[#443]: https://github.com/gotgenes/pi-packages/issues/443
-[#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
-[#447]: https://github.com/gotgenes/pi-packages/issues/447
-[#462]: https://github.com/gotgenes/pi-packages/issues/462
-[#463]: https://github.com/gotgenes/pi-packages/issues/463
-[#470]: https://github.com/gotgenes/pi-packages/issues/470
-[#535]: https://github.com/gotgenes/pi-packages/issues/535
-[#536]: https://github.com/gotgenes/pi-packages/issues/536
-[#537]: https://github.com/gotgenes/pi-packages/issues/537
-[#538]: https://github.com/gotgenes/pi-packages/issues/538
-[#539]: https://github.com/gotgenes/pi-packages/issues/539
-[#540]: https://github.com/gotgenes/pi-packages/issues/540
-[#541]: https://github.com/gotgenes/pi-packages/issues/541
-[#542]: https://github.com/gotgenes/pi-packages/issues/542
-[#543]: https://github.com/gotgenes/pi-packages/issues/543
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md
+[ADR-0003]: ../decisions/0003-publish-bundled-type-declarations.md
 [ADR-0004]: ../decisions/0004-reconsider-ui-direction.md
+[ADR-0005]: ../decisions/0005-ordered-lifecycle-interceptors.md