@nklisch/pi-enhanced 0.4.3 → 0.5.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md

@@ -1,98 +1,64 @@
----
-status: accepted
-date: 2026-05-29
----
-
 # 0002 — Workspaces and permissions are extensions on a minimal core
 
-## Status
-
-Accepted.
-Supersedes the "agent collaborator architecture" framing of Phase 16 (an abandoned exploration) and the work shipped under it: issue #256 (`WorktreeIsolation` as an `Agent` collaborator) and issue #257 (`ChildSessionFactory` extraction, parked at planning).
-Reclaims Phase 16's original intent — "invert dependencies" — and extends it to evict worktree isolation from the core.
-
 ## Context
 
-The core question that triggered this decision: a single-method `ChildSessionFactory` with a `create(cwd?)` method (planned for #257) looked like it wanted to be a function, and the `cwd` parameter was late-bound.
-Pulling that thread exposed progressively more rudimentary issues.
-
-1. `cwd` is late-bound because `WorktreeIsolation.setup()` is called lazily inside `Agent.run()`, after construction — a two-phase `construct-then-setup()` that violates design principle 8 ("Construct complete").
-2. The worktree is *ready* only at dequeue (a concurrency slot is held and `git worktree add` has run).
-   "Construct when ready" therefore means constructing the worktree at run-start, not at spawn — which dissolves the lazy `setup()` and makes `cwd` knowable at construction.
-3. The worktree and the child session share one lifespan: both are born at run-start and torn down at completion (the worktree's cleanup saves a branch; the session is disposed).
-   Resources with one lifetime are one resource, not sibling collaborators that `Agent` must sequence.
-   The `create(cwd?)` parameter only existed because we split one run-scoped resource (the worktree) out and made `Agent` relay its output back in.
-4. Worktrees are not intrinsic to what makes subagents useful.
-   The maintainer never uses them (WIP-of-1, trunk-based, CI/CD).
-   Git worktree isolation is one *strategy* for answering "where does this child run, and what brackets the run?"
-   — a container, a throwaway tmpdir, or a remote sandbox are others.
-   The core needs only *a working directory and a disposal hook*; the default (the parent's cwd, no setup/teardown) is always correct.
-5. This mirrors Phase 14, which evicted tool/extension *policy* (`disallowed_tools`, `extensions` filtering) to `@gotgenes/pi-permission-system`.
-   Worktrees are *environment* policy; they belong outside the core for the same reason.
-
-Permissions and workspaces are orthogonal concerns that must compose as independent extensions on the core, never knowing about each other.
-
-## Decision
-
-pi-subagents is a minimal orchestrator: it 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 attaches through exactly two extension surfaces, distinguished by the direction of information flow.
-
-### Two extension surfaces
-
-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.
+Worktrees are not intrinsic to what makes subagents useful. Git worktrees are one
+strategy for answering “where does this child run, and what brackets the run?”
+The core needs a working directory and a disposal hook; the default is the
+parent's working directory with no workspace setup or teardown.
 
-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** (it 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.
+Permissions and workspaces are orthogonal concerns. They must compose as
+independent extensions on the core, never knowing about each other.
 
-### The discriminator
+## Decision
 
-When deciding how a concern attaches:
+pi-subagents is a minimal orchestrator: it creates child sessions, drives their
+turns, tracks results, gates concurrency, supports resume, and publishes lifecycle
+boundaries. The core does not look up a named permission or workspace consumer.
 
-- 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).
+### Lifecycle observation
 
-Permissions are observational: the core does not enforce policy; it publishes the child's identity at the pre-bind instant so the permission extension (loaded in the child) can detect "am I a subagent?"
-and gate tool calls at runtime.
-Workspaces are generative: the core cannot default the cwd away when an isolation strategy is requested, so the provider hands it back.
+Child-execution events expose spawning, session creation before extension binding,
+completion, and disposal. A permission extension can identify the child at the
+pre-bind boundary and enforce its own policy inside the child. Observation does
+not replace prompts or results; those decisions use the separate ordered
+interceptor contract in [ADR 0005](0005-ordered-lifecycle-interceptors.md).
 
-### The governing rule: no vacant hooks
+### Workspace provider
 
-The architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
-A provider seam with no consumer is not extensibility — it is a speculative abstraction that taxes every reader, and `fallow` flags it as dead.
-Latent extensibility (the design can host the seam additively) is the deliverable; a vacant hook is not.
+A registered `WorkspaceProvider` supplies the child's working directory and
+bracketed cleanup. Preparation happens when the run starts, after concurrency
+admission. The session factory receives the resolved working directory, not the
+provider: assembly consumes a value rather than relaying workspace policy.
 
-### What leaves the core
+The provider owns workspace-specific cleanup and result wording. With no provider,
+children run in the parent's working directory. The core does not own Git worktree,
+container, or sandbox implementations.
 
-- **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) → a new package, `@gotgenes/pi-subagents-worktrees`, that implements the workspace provider and owns the git plumbing and the "saved to branch" result.
-- **`permission-bridge.ts`** → retired.
-  The core stops reaching *out* to `Symbol.for("@gotgenes/pi-permission-system:service")` and instead *emits* lifecycle events the permission system subscribes to.
-- **`isolated` / `extensions: false` / `noSkills`** → removed.
-  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 cannot be reduced to observation, so it is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
+### No vacant hooks
 
-### What stays in the core (not policy)
+The architecture must admit a seam without shipping it until a concrete consumer
+exists. A provider with no consumer is speculative machinery, not useful
+extensibility. The workspace provider and ordered lifecycle interceptors are
+concrete seams; neither justifies a generic hook framework.
 
-- The **recursion guard** (stripping the core's own `subagent` / `get_subagent_result` / `steer_subagent` tools from children).
-  It defends the core's own invariant — a subagent must not recursively spawn — keyed off the core's own tool names.
-  With `isolated` gone, children always load the parent's resources, so the guard becomes unconditional rather than gated on `cfg.extensions`.
+### Core invariants
 
-### Composition test
+The core removes parent-only orchestration tools from children to prevent recursive
+orchestration. `src/tools/parent-tool-registry.ts` owns that set. Children otherwise
+use registration-open extension tooling with the supported denylist; permission
+policy remains a companion concern.
 
-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.
-Permissions depend only on the core's events; workspaces depend only on the core's provider seam; the core depends on neither.
+The composition test is the same with neither companion, only permissions, only
+workspaces, or both: the core does not change, and the companions do not reference
+each other.
 
 ## Consequences
 
-- The "agent collaborator architecture" Phase 16 (give `Agent` a worktree collaborator + a session factory) is abandoned.
-  #256 is superseded (worktree was placed in the wrong layer); #257 is parked (it polished a subsystem slated for eviction).
-- A new package `@gotgenes/pi-subagents-worktrees` is introduced; the core spawn API drops `isolation` and `isolated`.
-- `permission-bridge.ts` is removed; `@gotgenes/pi-permission-system` migrates from a published-service lookup to lifecycle-event subscription, which requires the core to emit an awaited, ordered `session-created` event before `bindExtensions()`.
-  Confirming Pi's event model supports awaited pre-bind emission is the first investigation of the reclaimed phase.
-- Once the cwd is resolved through the provider seam rather than relayed by `Agent`, child-session creation can construct a born-complete execution and the "runner" concept dissolves — recovering the structural goal of the abandoned collaborator steps by a cleaner route.
-- The reclaimed Phase 16 roadmap and step issues live in [`docs/architecture/architecture.md`](../architecture/architecture.md).
+Resource ownership stays explicit. The workspace brackets the run, the session
+factory constructs a usable child session, and the subagent owns execution and
+settlement. Contributors can add a workspace strategy or permission consumer
+without introducing an outward dependency from the core.
+
+[Architecture](../architecture/architecture.md) owns the overall component and
+lifecycle model.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0003-publish-bundled-type-declarations.md

@@ -1,71 +1,42 @@
----
-status: accepted
-date: 2026-05-29
----
-
-# 0003 — Publish a bundled `.d.ts` for the public surface
-
-## Status
-
-Accepted.
-Introduces the repository's first build step, scoped to type declarations only.
+# 0003 — Publish bundled declarations for the public surface
 
 ## Context
 
-`@gotgenes/pi-subagents` could not be imported by another TypeScript package in this workspace.
-Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`) is the first intra-repo consumer: it must `implements WorkspaceProvider` and call `getSubagentsService().registerWorkspaceProvider(...)`, both of which require importing the package by name.
-
-A `tsc --traceResolution` of a sibling consuming the package surfaced two compounding failures.
-
-1. `package.json` `exports["."]` pointed at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
-   A latent bug, unnoticed because nothing in-repo imported the package by name.
-2. Once corrected, the public entry's internal alias imports cascade.
-   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via the `#src/*` alias.
-   When a sibling's `tsc` follows the symlink, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and resolve into the *consumer's* `src/` — a global-`paths` collision, since both packages define `#src/*`.
-   The fallback to the publisher's `package.json` `imports` field also fails: `tsc` cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
-
-The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
-A shallow alias-free entry is therefore not achievable without a substantial source restructure.
-
-This collides with the ship-source model ([ADR-0002]): every package ships raw `.ts` executed directly by Pi, with no build step.
+Consumers must be able to import `@nklisch/pi-subagents` by package name without
+adopting its internal path aliases or source layout. Following the internal type
+graph directly can make a consumer's own `#src/*` aliases intercept imports meant
+for this package. Packaging must not require restructuring the domain model to
+satisfy another project's compiler configuration.
 
 ## Decision
 
-Emit a single, self-contained `dist/public.d.ts` for the public surface and advertise it through a `types` export condition, while the runtime entry continues to serve `.ts` source.
+Publish self-contained declaration bundles for the root service and `./settings`
+exports, while runtime consumers continue to load TypeScript source.
 
-```jsonc
-"exports": {
-  ".": {
-    "types": "./dist/public.d.ts",
-    "default": "./src/service/service.ts"
-  }
-}
-```
+- `dist/public.d.ts` describes the root service contract.
+- `dist/settings.d.ts` describes the layered-settings helper.
+- The manifest's `types` conditions point to those bundles; runtime export targets
+  remain the corresponding source modules.
+- The declaration build inlines internal types while leaving peer-dependency types
+  external. It does not generate a second JavaScript runtime.
+- Declarations are generated at pack time, shipped through the package allowlist,
+  and not committed. The manifest and declaration build configuration own exact
+  paths and build inputs.
 
-- `rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into one file, inlining the internal `#src/*` types and keeping peer-dependency types (`@earendil-works/*`, `@sinclair/typebox`) external.
-  We ship `.ts` source, so only the declaration bundle is emitted — no JS.
-- The bundle is generated at `prepack` time and shipped via a `files` allowlist; it is gitignored and never committed.
-- `default` → `./src/service/service.ts` fixes the stale path and serves runtime consumers; its `import type` lines erase, so no runtime `#src/*` resolution is needed.
-- A `pnpm pack` → throwaway-consumer → `tsc` harness proves external consumability with no publish round-trip and no workspace privileges.
-
-This is the repository's first build step.
-It is deliberately narrow: it produces type declarations only and changes nothing about how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+Packed public types must compile in an external consumer without workspace path
+privileges. A workspace-linked consumer also needs the generated declarations
+available before typechecking against the package.
 
 ## Alternatives considered
 
-- Alias-free public entry (restructure the source so the entry's full type closure resolves via same-directory `./` imports).
-  Mechanically possible, but it requires moving the `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and untangling the `agent.ts`/`types.ts` graph, with care that inner layers do not import the outer service layer.
-  `eslint`'s `no-parent-relative-imports` rule (which forbids `../`) narrows the options further.
-  Larger blast radius than emitting a `.d.ts`, and it churns the domain model to serve a packaging concern.
-- A self-contained entry that re-declares the public types inline, guarded by a conformance test.
-  Avoids a build step but duplicates the seam/usage/status type definitions, which drift over time.
+An alias-free public entry could avoid declaration bundling, but would require
+reorganizing the type graph for a packaging concern. Re-declaring public types in
+a separate entry would instead duplicate contract truth and require keeping both
+copies synchronized. A generated declaration bundle avoids both costs.
 
 ## Consequences
 
-- The repository now has a build step, but it is type-only and isolated to this package; the ship-source model is otherwise intact.
-- Consumers (including `@gotgenes/pi-subagents-worktrees` in #263) consume the packaged public interface like any external developer — no `workspace:*` privileges.
-- The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
-  This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
-- Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.
-
-[ADR-0002]: ./0002-extensions-on-a-minimal-core.md
+The build is narrow: declarations for the public contract, not a replacement for
+Pi's source-loading model. Consumers use the packaged interface rather than
+reaching into internal source modules. Public type changes carry the same
+compatibility obligations as the runtime service they describe.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0004-reconsider-ui-direction.md

@@ -1,284 +1,72 @@
----
-status: accepted
-date: 2026-06-18
----
-
-# 0004 — Reconsider the UI direction from first principles
-
-> Historical vocabulary note: this decision predates the joined/detached clean
-> break. In current code, its "background-only widget" means detached-only;
-> joined runs use their inline result surface. Historical delivery labels below
-> are retained as decision history, not as current API contracts.
-
-## Status
-
-Accepted.
-Completes Phase 18 (reconsider the UI) and gateways Phase 19 (implement the recorded decisions).
-Decision-only: this ADR changes no runtime code.
-The inherited UI stays live until Phase 19 acts on these decisions.
+# 0004 — Keep a narrow, substitutable operator UI
 
 ## Context
 
-Phase 18's spine (Steps 1–7, #420 through #426) disentangled the activity tier from the core.
-The core now owns all run state in one place (`SubagentState`), the widget self-drives from lifecycle events, the LLM-facing `subagent` tool no longer depends on the widget, and the public event contract's declared channels equal its emitted channels.
-The UI is therefore a pure reactive consumer of the broadcast-plus-query surface — _substitutable_.
-
-This final step decides the UI's _direction and distribution_, not whether substitution is possible.
-The goal is **substitutable, not optional**: a human needs some surface, but the specific UI is replaceable — the way Pi ships a default TUI built on the same public API any extension targets.
-The disentangled core stays byte-for-byte identical whether or not a given UI consumer is installed (the composition invariant), so a replacement UI is a downstream concern even though _some_ UI is not.
-
-Unlike the worktrees provider seam (generative, rationed — one provider the core consults), the UI is an observational consumer (unlimited, the core never waits on it).
-That asymmetry is why packaging the UI is the secondary question and decoupling it was the real win.
-
-Three operator-framed concerns shape the per-component judgment.
-
-1. **Foreground progress is already shown by the tool call.**
-   In foreground the `subagent` tool's inline `onUpdate` stream renders progress well; the above-editor widget duplicates it.
-2. **Background agents have no tool-call display.**
-   When agents run in the background there is no inline stream, so _something_ must indicate their state — and multiple subagents can run in parallel, so that surface must represent N concurrent agents at once.
-3. **Operator visibility into a subagent's session is a distinct, richer need.**
-   "Switch into a subagent's session, scroll/read it, switch between subagents, and exit back to root" is a navigation interaction, not a live overlay.
-   The core already persists each child as a standalone Pi session JSONL at `Subagent.outputFile`, and `Subagent.messages` exposes the full history — so the data was never the limit; the bespoke, width-capped `ConversationViewer` overlay was.
+Joined runs already have their calling tool's result surface. Detached runs need
+an ambient indication of progress, including several concurrent children. Reading
+a child's conversation is a different task: an operator needs to inspect its
+transcript without replacing the active parent session.
 
-### Relevant Pi SDK surface
-
-Verified against `@earendil-works/pi-coding-agent@0.79.1`:
-
-- `ExtensionActions.switchSession(sessionPath, { withSession })` switches the **active** session to a different session file.
-  It is a full active-session takeover: it fires `session_before_switch` / `session_shutdown`, invalidates the current session context (`setBeforeSessionInvalidate` exists for host-owned UI teardown), and returns `{ cancelled }`.
-  The switched-to session is fully interactive — `ReplacedSessionContext` exposes `sendUserMessage`.
-- `session-manager` exports `loadEntriesFromFile(filePath)` / `parseSessionEntries(content)`, which read a session file's entries without switching — the read-only alternative to a full takeover.
+The goal is substitutable, not optional. A human needs some surface, but that
+surface should be a consumer of the core's lifecycle and query boundaries rather
+than a responsibility threaded through execution code.
 
 ## Decision
 
-Judge each UI component on the first principles above, then record the distribution.
-
-### A — Foreground widget: shrink to background agents only
-
-The above-editor widget duplicates the foreground tool's inline `onUpdate` stream.
-The widget survives **only** as the background-agent status surface (concern 2): foreground runs suppress it, the inline stream is authoritative there, and the background surface keeps the widget's existing per-agent tree so it represents N parallel agents at once.
-The change is _when_ the widget shows (background-only), not _what_ it shows.
+### Detached status widget
 
-### B — Conversation viewer: replace the bespoke overlay with native session navigation
+The above-editor widget represents detached agents only. Joined runs use their
+inline tool surface instead of duplicating progress in the widget. The widget
+maintains a bounded reactive view of active detached records and terminal linger
+state; it does not require the core's spawn tools to drive rendering.
 
-Remove the bespoke `ConversationViewer` overlay.
-Operator visibility (concern 3) is served by Pi's own session machinery applied to the already-persisted child session file, not a hand-rolled transcript renderer — the recursive-Pi insight applied to `Subagent.outputFile`.
+Operator status surfaces show exact effective model, effective thinking level,
+active or final runtime, run id, delivery mode, and terminal reason when present.
 
-The illustrative call shape (Phase 19, not final):
+### Native, read-only session navigation
 
-```typescript
-// "View running agents" → pick a child → switch into its persisted session
-const child = manager.getRecord(id);
-if (child?.outputFile) {
-  await ctx.switchSession(child.outputFile);
-  // operator reads/scrolls in Pi's native viewer; a later switch returns to root
-}
-```
+`/subagents:sessions` lets the operator select a child transcript without leaving
+the parent session. It is read-only: steering remains a separate tool behavior,
+not a second editor embedded in the viewer.
 
-This is Tell-Don't-Ask (hand Pi the session path; Pi owns the viewer) and keeps the core free of transcript-rendering code.
+Do not use `switchSession` for navigation. Switching replaces the active runtime
+and conflicts with keeping the parent and its detached work running. Read and
+render the transcript through supported Pi APIs instead.
 
-This decision records the _direction_ (native session machinery over a bespoke renderer), not the _mechanism_.
-`switchSession` is a full active-session takeover and is interactive, so the operator UX is gated on a Phase 19 spike that chooses between (i) true `switchSession` round-trips and (ii) a read-only transcript built from `loadEntriesFromFile` that renders Pi-standard entries without leaving the root session.
-See "Phase 19 entry criteria."
+The transcript has two sources and one renderer:
 
-### C — `/agents` menu: dissolve the monolithic command into focused surfaces
+- A retained live child supplies messages and update subscriptions.
+- After the live session is released, the retained transcript pointer supplies a
+  file snapshot through Pi's session parsing and context-building APIs.
 
-The single `/agents` command bundles four unrelated jobs; split them, and do not keep all in one command.
-Managing agent _definitions_ through the menu earns no keep — creating or editing agents is better done with other tools (directly in Pi, or a real text editor / IDE).
+Both sources render through Pi's own message and tool-execution components, not a
+parallel transcript renderer. Session release updates the source; an unavailable
+snapshot preserves readable content and labels the degraded state. Candidate
+identity and labels come from retained manager records rather than a directory
+scan of unrelated session files. Session selection includes joined and detached
+records with readable transcript sources.
 
-- **Create new agent (wizard)** → **remove.**
-  An operator generates a new agent `.md` by asking a Pi agent directly (more capable than a fixed wizard) or by writing the file in an editor.
-- **Agent types (list + config editor)** → **remove.**
-  Viewing and editing agent definitions is better served by opening the `.md` files directly in an editor/IDE.
-- **Running agents (visibility)** → **keep the responsibility, re-home it.**
-  _Something_ must own running-agent visibility; it moves onto the background widget (Decision A) plus the native session navigation (Decision B), not a bespoke in-menu overlay.
-- **Settings (concurrency / max turns / grace turns)** → **extract to a focused command** (e.g. `/subagents:settings`).
-  Some value, but it does not belong bundled with agent management.
+### Focused settings and definition ownership
 
-### D — Distribution: keep the surviving UI in-core (substitutable, not extracted)
+`/subagents:settings` owns operational settings. Both commands use the
+`subagents:` namespace. Agent-definition creation and editing belong in ordinary
+files and editors, not built-in wizards or a general `/agents` management menu.
 
-The spine already made the UI substitutable; a replacement UI is a downstream concern that targets the public broadcast-plus-query surface.
-The surviving UI — the background widget, a focused settings command, and the session-navigation glue — **stays in-core** as a reactive consumer.
-Extraction to a separate `@gotgenes/pi-subagents-ui` package is **not** chosen now.
+### Distribution
 
-This answers the issue's headline question — the UI's _distribution_ — with "keep in core, substitutable," recorded explicitly rather than left implicit.
-Extraction remains an available future option precisely because the composition invariant holds: the core is byte-for-byte identical with or without a given UI consumer.
-It would be revisited if a second, materially different UI consumer appears, or if the in-core UI starts to pull SDK or rendering concerns back into core modules.
+The detached widget, session navigator, and settings command stay in-core as
+substitutable consumers. The core's execution behavior does not depend on which UI
+consumer renders it. Extracting another UI package is not required by that
+boundary; reconsider distribution only when a materially different consumer or
+actual coupling makes it useful.
 
 ## Consequences
 
-- The inherited UI is no longer preserved by default; each component now has a recorded fate (shrink / replace / dissolve) motivated by the first principles, not by inheritance.
-- Phase 18 is complete.
-  This ADR gateways Phase 19, which implements the decisions (background-only widget, native session navigation, `/agents` decomposition, `/subagents:settings` extraction) under its own plan and issues.
-- No interim regression: this ADR removes nothing.
-  The widget, the `ConversationViewer`, and the full `/agents` menu stay live until Phase 19 replaces them.
-- Phase 19 must preserve the spine's invariants when it acts on these decisions: the runtime holds zero UI state (#422), the widget is a reactive consumer with no inbound calls from core spawn tools (#423), the LLM tool depends only on manager/runtime/settings/registry (#424), and declared event channels equal emitted channels with no vacant hook (#425).
-  These are pinned today by the existing observer/widget/event-contract suites, which Phase 19 inherits.
-
-## Phase 19 entry criteria
-
-The following are open and must be resolved by a Phase 19 spike before committing to a mechanism; they are deliberately not decided here.
-
-- **Root-continuity during a session switch.**
-  `switchSession` invalidates the current session context — does the root's in-flight turn survive a switch-out-and-return, and what is the correct "return to root" gesture?
-  Resolve before committing to true `switchSession` round-trips.
-- **View-only vs interactive.**
-  A switched-to child session is interactive (`sendUserMessage`).
-  Decide whether steering a child from its own session is desirable, or whether the viewer should be strictly read-only (favoring the `loadEntriesFromFile` transcript path).
-- **Parallel-agent navigation.**
-  With N background agents running, decide the operator's gesture to pick which child to view and to cycle between them — driven from the background widget, a dedicated command, or both.
-- **Settings command namespace.**
-  Confirm the final command name/namespace for the extracted settings surface (`/subagents:settings` vs another form) against how sibling packages register namespaced commands.
-
-The agent create/edit surfaces are **not** open questions: both are removed (Decision C).
-
-## Addendum (2026-06-20): Phase 19 entry-criteria answers ([#446])
-
-The Phase 19 Step 1 spike ([#446]) resolved all four entry criteria.
-Evidence comes from the bundled `@earendil-works/pi-coding-agent` SDK surface (`packages/pi-subagents/node_modules/@earendil-works/pi-coding-agent/dist`) and a throwaway vitest harness run against a **real child session JSONL** (a 43-entry subagent session: 1 `session` header carrying a `parentSession` backref, 1 `model_change`, 1 `thinking_level_change`, 40 `message` entries).
-The harness was discarded after observation; no production source changed.
-
-### Finding 0 — `loadEntriesFromFile` is not part of the package's public surface
-
-The original "Relevant Pi SDK surface" section cited `loadEntriesFromFile` as the read-only alternative to a switch.
-The spike found it is **not reachable** from `@earendil-works/pi-coding-agent`, and that this is not a types/runtime mismatch — the type barrel and the runtime barrel agree, both omitting it.
-`loadEntriesFromFile` is defined in the deep module `core/session-manager.ts` (annotated `/** Exported for testing */`), but the public barrel `src/index.ts` (→ `dist/index.d.ts` + `dist/index.js`) re-exports only a curated subset of that module — including `parseSessionEntries` but **not** `loadEntriesFromFile`.
-The `package.json` `exports` map exposes only `"."` → the barrel, so the deep import `@earendil-works/pi-coding-agent/dist/core/session-manager.js` is not a supported entry point either.
-`tsc` correctly rejects `import { loadEntriesFromFile } from "@earendil-works/pi-coding-agent"` with `TS2305: Module … has no exported member 'loadEntriesFromFile'`; the throwaway Vitest harness only reached a runtime `is not a function` because esbuild strips types without type-checking (the package's own `pnpm run check` would have caught it at compile time).
-This is not version-specific: the barrel omits it identically in both the pinned `0.79.1` and the latest `0.79.8`, so an SDK upgrade does not surface it — Step 4 should not chase one.
-The viable read-only path is therefore `parseSessionEntries(readFileSync(outputFile, "utf8"))` — `parseSessionEntries` _is_ public (both types and runtime) — which the harness confirmed returns the full `FileEntry[]` transcript with no session switch and no active-session mutation.
-Step 4 ([#445]) should read the file itself and call `parseSessionEntries`, not `loadEntriesFromFile`.
-
-Upstream references:
-
-- Barrel that omits it: [`packages/coding-agent/src/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/index.ts).
-- Test-annotated definition: [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/session-manager.ts).
-
-### Finding 1 — the read-only transcript renders entirely on public Pi APIs (no bespoke renderer)
-
-The read-only path returns raw `FileEntry[]`, so _something_ must render them.
-The spike found that every piece needed to turn those entries into a Pi-standard transcript is already re-exported through the public root barrel — so Step 4 wires Pi's own machinery rather than re-implementing the formatting the bespoke `ConversationViewer`/`message-formatters.ts` carried.
-This matters because ADR-0004 Decision B's `switchSession` sketch implied "Pi owns the viewer"; the read-only path keeps that property at the _component_ level (Pi renders each entry) without the active-session takeover.
-
-The verified public pipeline (all symbols confirmed present in `dist/index.d.ts`, the root barrel):
-
-1. **Load** — `parseSessionEntries(readFileSync(record.outputFile, "utf8")): FileEntry[]` (Finding 0).
-2. **Bridge** — `buildSessionContext(entries, leafId?, byId?): SessionContext` turns the entries into `{ messages: AgentMessage[], thinkingLevel, model }`, handling tree traversal, compaction, and branch summaries along the path.
-   Note `buildSessionContext` takes `SessionEntry[]`, so drop the leading `SessionHeader` (`type: "session"`) that `parseSessionEntries` includes.
-3. **Render** — one of:
-   - **Text:** `serializeConversation(messages: Message[]): string` (from `core/compaction`) for a plain-text dump.
-   - **TUI:** the per-entry components `AssistantMessageComponent`, `UserMessageComponent`, `ToolExecutionComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, `CustomMessageComponent`, `SkillInvocationMessageComponent` (from `modes/interactive/components`), plus `renderDiff`, for a scrollable native transcript.
-
-Unlike `loadEntriesFromFile`, all of these _are_ public (both types and runtime).
-So the read-only viewer is buildable end-to-end on supported APIs, and ADR-0004 Decision B's "keep the core free of transcript-rendering code" holds — the rendering is Pi's, imported, not hand-rolled.
-
-Upstream references:
-
-- Component barrel: [`packages/coding-agent/src/modes/interactive/components/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/interactive/components/index.ts).
-- `serializeConversation`: [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/compaction/utils.ts).
-
-### Criterion 1 — Root-continuity during a session switch: avoid the switch
-
-`switchSession` is a full active-session takeover: it fires `session_before_switch` (cancellable) and then tears the current runtime down via `session_shutdown` (whose `targetSessionFile` field marks a replacement-driven shutdown).
-The root's in-flight turn does **not** survive the takeover — the runtime that owns that turn is invalidated — and a "return to root" would require a second `switchSession(rootSessionFile)` that re-incurs the teardown on the way back.
-Because background agents run precisely while the operator keeps working at root, a true `switchSession` round-trip is hostile to a root with a turn in flight.
-
-**Answer:** do not use `switchSession` for navigation.
-The read-only transcript path (Criterion 2) sidesteps root-continuity entirely — it never touches the active session, so there is no return gesture to get wrong.
-
-### Criterion 2 — View-only vs interactive: read-only
-
-`ReplacedSessionContext` (handed to a `switchSession` `withSession` callback) extends `ExtensionCommandContext` and exposes `sendUserMessage`/`sendMessage`, so a switched-to child session is interactive.
-But operator visibility (concern 3) is framed as "switch in, scroll/read, switch between, exit back to root" — a navigation interaction, not a live steering overlay — and steering already has a home (`steer_subagent` tool / the widget).
-Adding in-session steering would create a second, redundant steering surface.
-
-**Answer:** the viewer is strictly **read-only**, loaded via `parseSessionEntries(readFileSync(record.outputFile))` (Finding 0) and rendered through Pi's public entry components (Finding 1) without leaving the root session.
-This also resolves Criterion 1 by construction.
-
-### Criterion 3 — Parallel-agent navigation: command-first
-
-With N background agents running, the operator needs a gesture to pick which child to view.
-The background widget (Decision A, [#444]) already represents N parallel agents as a per-agent tree, making it the natural eventual selection surface; a flat command gives a non-widget entry point that lists running background agents and lets the operator pick one keyed on `record.outputFile`.
-
-**Answer:** Step 4 ([#445]) ships a **command** as the primary, unit-testable selection surface (list background agents → pick → render that child's transcript read-only), with a widget gesture as an optional later enhancement.
-"Both" remains the eventual target; command-first is the Step 4 starting point because it does not depend on the widget shrink ([#444]) landing first.
-
-### Criterion 4 — Settings command name: `/subagents-settings`
-
-Sibling packages register flat, hyphenated command names with no `:` namespace: `registerCommand("agents", …)` (this package), `"colgrep-reindex"`, `"permission-system"`.
-A `/subagents:settings` form would be inconsistent with every existing command in the repo, and `/agents-settings` wrongly implies it manages agent definitions (which Decision C removes).
-
-**Answer:** confirm **`/subagents-settings`** (flat, hyphenated) for Step 2 ([#447]).
-Reject the tentative `/subagents:settings` and the `/agents-settings` alternative.
-
-### Net mechanism for Phase 19
-
-- Session navigation (Step 4, [#445]): a read-only transcript, surfaced through a flat command; no `switchSession`, no `loadEntriesFromFile`.
-  The pipeline is `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` → render via Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / … ) or `serializeConversation` (Findings 0 and 1).
-- Settings command (Step 2, [#447]): `/subagents-settings`.
-
-This keeps bespoke transcript rendering out of the package (rendering is Pi's own public components), adds no inbound call from the UI to the core, and preserves the Phase 18 spine invariants (#422–#425).
-
-## Addendum 2 (2026-06-20): Step 4 sourcing — live record plus file snapshot ([#445])
-
-This addendum revises the first addendum's Criterion 2 answer for Step 4 ([#445]).
-The "strictly read-only, file-only" sourcing and the "not a live overlay" framing are superseded by the dual-source decision below; everything else from the spike stands.
-
-**Why revise.**
-The spike's mechanism — `parseSessionEntries(readFileSync(record.outputFile))` read once — serves a _completed_ subagent well but is a frozen snapshot for a _running_ one: it shows only what was flushed to disk at open time and does not stream.
-The clarified desired behavior is to see the **live** activity of any subagent _and_ the activity of a completed subagent.
-The bespoke `ConversationViewer` being removed in Step 5 already delivers both — it subscribes to the live in-memory record (`record.subscribeToUpdates()`) and renders `record.messages` plus a streaming indicator built from `record.activeTools` / `record.responseText`.
-That liveness comes from the in-memory record, not the persisted file, so a file-only viewer drops it.
-
-**Decision — dual-source, one renderer.**
-Step 4 sources the transcript by liveness and renders both sources through the same Pi public entry components (Finding 1 holds — no bespoke renderer):
-
-- **Tracked agent (still in `manager.listAgents()`)** — render from the live in-memory record: `record.messages` for history, `record.subscribeToUpdates()` to re-render on streaming updates, and `record.activeTools` / `record.responseText` for the running-agent streaming indicator.
-  This is live.
-- **Evicted / untracked agent** — render from the file snapshot: `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` (Findings 0 and 1).
-
-Both sources yield `AgentMessage[]`, so a single Pi-component renderer serves both.
-
-**Type-boundary note.**
-`SubagentSession.messages` is deliberately widened to `readonly unknown[]` at the core boundary (`src/lifecycle/subagent-session.ts`), even though the underlying `_session.messages` is the SDK's `AgentMessage[]`.
-Step 4 should add a typed accessor that returns `AgentMessage[]` (or narrow at the boundary) rather than feeding `unknown[]` into Pi's components.
-This is a read accessor on the existing record — it adds no inbound call from the UI to the core and does not regress the Phase 18 spine invariants.
-
-**Still read-only (non-interactive).**
-The viewer remains strictly non-interactive: Criterion 2's anti-redundant-steering rationale stands (steering lives in the `steer_subagent` tool and the widget), and Criterion 1's rejection of `switchSession` is unchanged — "live" here means the in-memory subscription, not an active-session takeover.
-
-**Candidate set (revises Criterion 3).**
-The selection command lists **any subagent with a live record or a persisted session file** — foreground agents included, not only running background agents.
-This matches the bespoke viewer's current reach (gated on `record.isSessionReady()`, never background-filtered) and avoids an interim regression.
-A foreground agent is navigable only _after_ it completes — while it runs, the root turn is blocked on it — whereas a background agent is navigable live.
-The background widget ([#444]) remains the optional secondary selection gesture for background agents; the command is the primary, unit-testable surface.
-
-**Evicted-agent candidate set ([#463]).**
-Step 4b realizes the file-snapshot branch for fully-evicted agents.
-The candidate set is broadened via **manager-retained descriptors**, not a directory scan of the tasks directory: the persisted child session carries no subagent `type`/`description` (those live only on the in-memory record), so a scan yields degraded labels and parses every file per picker open.
-The cleanup sweep instead stashes a lightweight `EvictedSubagent` descriptor (label fields + `outputFile`, no messages) before disposing a record, preserving rich labels and bounded memory.
-This covers in-session evictions — the sweep's only targets, since a fresh manager per session never reloads prior-process subagents.
-The "render from the file snapshot" mechanism for an evicted agent (above) is unchanged; only the candidate-set _enumeration_ is pinned to descriptors.
-
-## Addendum 3 (2026-06-23): adopt the `subagents:` colon namespace, superseding Criterion 4
-
-This addendum reverses **Criterion 4**, which confirmed flat, hyphenated command names (`/subagents-settings`) and rejected `/subagents:settings`.
-The two registered commands are renamed: `/subagents-settings` → `/subagents:settings` and `/subagent-sessions` → `/subagents:sessions`.
-This is a breaking change to the command surface.
-
-**Why revise.**
-Criterion 4 surveyed only in-repo siblings (`agents`, `colgrep-reindex`, `permission-system`) and concluded a `:` namespace would be inconsistent with every existing command.
-That survey missed the broader Pi ecosystem: `@eko24ive/pi-ask` establishes the colon convention with `answer:again` and `ask:replay`, grouping a package's commands under a shared prefix.
-The colon namespace reads as a deliberate grouping gesture (`subagents:settings`, `subagents:sessions` clearly belong to one package) where the hyphen form blurs into an ordinary command name.
-The newer ecosystem signal outweighs the original in-repo-only consistency argument.
-
-**Scope.**
-This change is pi-subagents-only.
-Whether the colon convention becomes repo-wide (renaming `colgrep-reindex`, `permission-system`, etc.) is deferred — not decided here.
-`/agents` is intentionally left flat: it is slated for removal in the Phase 18 / Step 5 menu retirement, so namespacing it would be churn on a command being deleted.
+The core owns run state and behavior; UI owns transient presentation and selection.
+Native Pi components preserve transcript fidelity without maintaining a second
+rendering system. Read-only navigation preserves parent continuity, and keeping
+agent-definition editing outside the package avoids duplicating tools the operator
+already has.
 
-[#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
-[#463]: https://github.com/gotgenes/pi-packages/issues/463
+[Architecture](../architecture/architecture.md) owns the detailed lifecycle,
+retention, observation, and transcript-query boundaries.