@gotgenes/pi-subagents 17.0.0 → 17.0.1

package/docs/plans/0426-consolidate-residual-test-clone-families.md

@@ -0,0 +1,235 @@
+---
+issue: 426
+issue_title: "pi-subagents: consolidate residual test clone families"
+---
+
+# Consolidate residual test clone families
+
+## Release Recommendation
+
+**Release:** ship independently
+
+The architecture roadmap (`docs/architecture/architecture.md`, Phase 18, step 7) tags this issue "Independent of the disentanglement spine — can land at any time" and carries no `Release: batch` annotation.
+It is a test-only consolidation with no production-surface change, so it ships on its own.
+
+## Problem Statement
+
+fallow reports a long tail of test clone groups in `pi-subagents` (currently 24 test clone groups across the suite).
+A handful of these clone families are stable test scaffolding — tmp-directory setup, repeated arrange-then-act blocks, and near-identical menu-assertion cases — that the Phase 18 disentanglement spine does not rewrite as a side effect.
+They warrant their own shared fixtures rather than riding along with a production refactor.
+
+The goal is to extract shared fixtures for the clone families fallow identifies in the four named test files, dropping the package's test clone-group count below 15.
+
+## Goals
+
+- Eliminate the cross-file tmp-directory + `writeGlobal`/`writeProject` duplication between `test/settings.test.ts` and `test/layered-settings.test.ts` via a shared fixture helper.
+- Eliminate the three internal clone groups in `test/lifecycle/create-subagent-session.test.ts` by extracting the repeated arrange (factory session + deps) while keeping each `createSubagentSession(...)` act explicit.
+- Eliminate the four internal clone groups in `test/ui/agent-config-editor.test.ts` — convert the menu-option-structure cases to a table-driven `it.each` and hoist the shared `filePath`/arrange in the Edit/Delete blocks.
+- Land the package below 15 test clone groups (the four files contribute exactly 10 of the current 24 groups → 14 remaining).
+- Keep the full `vitest` suite green and the assertion strength unchanged (no behavioral coverage loss).
+
+This change is **not breaking** — it touches only test files and adds test-only helpers; no production module, export, or default changes.
+
+## Non-Goals
+
+- The production-code clone in `src/ui/agent-config-editor.ts` (the `location`/`targetDir`/`targetPath` block, dup `ff960d84`) — the issue scopes to *test* clone families; a production extraction is a separate concern.
+- The remaining test clone groups outside the four named files (`subagent-manager.test.ts`, `subagent.test.ts`, `concurrency-limiter.test.ts`, `workspace-bracket.test.ts`, `session-config.test.ts`, `get-result-tool.test.ts`, `spawn-config.test.ts`, `agent-creation-wizard.test.ts`, `agent-file-ops.test.ts`, `agent-menu.test.ts`, `agent-widget.test.ts`).
+  The cross-file group `5d8dbd48` (`subagent-manager.test.ts` ↔ `subagent.test.ts`) is explicitly left alone — neither side is a target file.
+- The cross-package `vitest.config.ts` clone (`e5e6691e`, 6 instances) — not a `pi-subagents` test-suite group and not in scope.
+- Phase 18 step 8 ([#427]), the UI-direction ADR — a separate, later step.
+
+## Background
+
+Relevant existing test-helper conventions live in `packages/pi-subagents/test/helpers/`:
+
+- `make-deps.ts`, `make-spawn-config.ts`, `make-subagent.ts`, `manager-stubs.ts`, `mock-session.ts`, `stub-ctx.ts`, `subagent-session-io.ts`, `ui-stubs.ts` — each exports `createX`/`makeX` factory functions with matching `*.test.ts` self-tests.
+- `subagent-session-io.ts` already exports `createFactorySession`, `createSubagentSessionDeps`, `createSubagentSessionIO`, `createAgentLookup`, `createChildLifecycleMock` — the create-subagent-session consolidation builds on these.
+- `ui-stubs.ts` already exports `createTestSubagentConfig`, `makeFileOps`, `makeMenuUI` — the agent-config-editor consolidation builds on these.
+
+Constraints from the `testing` skill that shape this plan:
+
+- **Do not wrap the system-under-test call in a helper to eliminate a duplication-metric clone — the repeated act is the test subject, not duplication to remove.**
+  Consolidate the *arrange*, not the *act*.
+  For `create-subagent-session`, extract the factory-session + deps arrange but keep `await createSubagentSession(...)` written out in each test.
+- **Group shared setup in a describe-scoped `beforeEach` and keep the act explicit** when the arrangement is uniform.
+- A table-driven `it.each` keeps the act visible in the parameterized body (run once per row) and is the right tool for the menu-option-structure cases — it is not a helper that hides the act.
+- Test-only refactors carry the `test:` conventional-commit type.
+
+Each helper module in `test/helpers/` ships a paired `*.test.ts`; any new shared helper follows that convention.
+
+## Design Overview
+
+This is a refactor verified by the existing suite staying green plus a falling fallow clone count — there are no new red→green behavior cycles.
+Three independent consolidations, each scoped to its file(s).
+
+### 1. Settings tmp-dir fixture (cross-file)
+
+`test/settings.test.ts` and `test/layered-settings.test.ts` both stand up two `mkdtempSync` directories in `beforeEach`, tear them down in `afterEach`, and define identical `writeGlobal`/`writeProject` helpers (clone groups `21d1fb01`, `4003c0e7` span both files; `4fc062db` is internal to `layered-settings.test.ts`).
+
+Extract a shared fixture into `test/helpers/tmp-settings-dirs.ts`:
+
+```typescript
+export interface SettingsDirs {
+  globalDir: string; // agentDir / global scope
+  projectDir: string; // cwd / project scope
+  globalFile: (filename?: string) => string;
+  projectFile: (filename?: string) => string;
+  writeGlobal: (obj: unknown, filename?: string) => void;
+  writeProject: (obj: unknown, filename?: string) => void;
+}
+
+// Caller wires it into beforeEach/afterEach:
+export function createSettingsDirs(filename: string): SettingsDirs;
+export function disposeSettingsDirs(dirs: SettingsDirs): void;
+```
+
+Each test file calls `createSettingsDirs(...)` in `beforeEach` and `disposeSettingsDirs(...)` in `afterEach`, then references `dirs.writeGlobal` / `dirs.writeProject`.
+`settings.test.ts` uses `"subagents.json"`; `layered-settings.test.ts` uses its `FILENAME` constant.
+The malformed-settings warn-assertion clone inside `layered-settings.test.ts` (`4fc062db`, two adjacent `it` blocks) collapses into a single `it.each` over `[malformed-global, malformed-project]` rows that share the spy-assert body.
+
+Interaction sketch (consumer call site, ~5 lines):
+
+```typescript
+let dirs: SettingsDirs;
+beforeEach(() => { dirs = createSettingsDirs("subagents.json"); });
+afterEach(() => { disposeSettingsDirs(dirs); });
+it("loads from global when no project file", () => {
+  dirs.writeGlobal({ maxConcurrent: 16 });
+  expect(loadSettings(dirs.globalDir, dirs.projectDir)).toEqual({ maxConcurrent: 16 });
+});
+```
+
+The helper owns only filesystem scaffolding (Tell-Don't-Ask: callers ask it to write, not for raw paths to write themselves); it does not import or know about `loadSettings`/`loadLayeredSettings`, so the act stays in the test.
+
+### 2. create-subagent-session arrange helper (internal)
+
+Clone groups `48ff1484`, `c92feb70`, `5fbe9ebb` all live in the `createSubagentSession — post-bind recursion guard` describe block (lines ~204–262).
+Each test repeats:
+
+```typescript
+const session = createFactorySession({ toolsBeforeBind, toolsAfterBind });
+io.createSession.mockResolvedValue({ session });
+await createSubagentSession(
+  { snapshot: STUB_SNAPSHOT, type: "Explore" },
+  createSubagentSessionDeps({ io, exec, registry: mockAgentLookup }),
+);
+const postBindArgs = session.setActiveToolsByName.mock.calls[0][0];
+```
+
+The variation is the factory tool-list config and the assertions; the act is identical.
+Add two file-local arrange helpers (the factory mocks differ per test, so a describe-scoped `beforeEach` cannot fully arrange):
+
+```typescript
+function arrangeFactory(opts?: Parameters<typeof createFactorySession>[0]) {
+  const session = createFactorySession(opts);
+  io.createSession.mockResolvedValue({ session });
+  return session;
+}
+function defaultDeps() {
+  return createSubagentSessionDeps({ io, exec, registry: mockAgentLookup });
+}
+```
+
+Each test becomes `const session = arrangeFactory({...}); await createSubagentSession({ snapshot: STUB_SNAPSHOT, type: "Explore" }, defaultDeps());` — the act line stays written out.
+The remaining two-line arrange+act sequence falls below fallow's clone threshold.
+These helpers stay file-local (one consumer file), so no new `test/helpers/` module is needed.
+
+### 3. agent-config-editor table-driven menu cases (internal)
+
+Clone groups `4ac7b228`, `a8e71e9c` (×3), `e36d2314` cluster in the "Menu option structure" block (lines ~104–139); `23fe1f93` is in the Edit/Delete blocks (~180–210).
+
+- **Menu-option-structure cases** → one `it.each` table.
+  Each existing case differs only in (a) the `resolveAgentConfig` mock (default vs. custom vs. disabled) and (b) the expected option array.
+  Model the rows as `{ name, config, filePath, expected }` and run the shared act once per row:
+
+  ```typescript
+  it.each([
+    { name: "default agent, no file", config: testDefaultConfig, filePath: undefined,
+      expected: ["Eject (export as .md)", "Disable", "Back"] },
+    // …one row per existing menu-structure case…
+  ])("shows $name options", async ({ config, filePath, expected }) => {
+    vi.spyOn(testRegistry, "resolveAgentConfig").mockReturnValue(config);
+    const { editor, ui } = setupDetail([undefined], filePath ? { filePath } : {});
+    await editor.showAgentDetail(ui, "test-agent");
+    expect((ui.select.mock.calls[0][1] as string[])).toEqual(expected);
+  });
+  ```
+
+  The act (`editor.showAgentDetail(...)`) stays visible in the table body.
+- **Edit/Delete block (`23fe1f93`)** → hoist the shared `const filePath = "/project/.pi/agents/test-agent.md"` to a describe-scoped constant and keep each `await editor.showAgentDetail(...)` act explicit; the residual per-test arrange (`setupDetail`, `ui.editor`/`ui.confirm` resolution) stays inline because it carries the test's intent.
+
+No change to `setupDetail`, `makeEditor`, or `ui-stubs.ts` — they already provide the right arrange seam.
+
+## Module-Level Changes
+
+- `test/helpers/tmp-settings-dirs.ts` — **new**: shared tmp-dir fixture (`createSettingsDirs`, `disposeSettingsDirs`, `SettingsDirs` type, `writeGlobal`/`writeProject`).
+- `test/helpers/tmp-settings-dirs.test.ts` — **new**: self-test for the fixture (follows the `test/helpers/*.test.ts` convention — every helper module ships a paired test).
+- `test/settings.test.ts` — **changed**: replace inline tmp-dir `beforeEach`/`afterEach`/`writeGlobal`/`writeProject` with the shared fixture.
+- `test/layered-settings.test.ts` — **changed**: same fixture swap; fold the two adjacent malformed-settings warn cases into one `it.each`.
+- `test/lifecycle/create-subagent-session.test.ts` — **changed**: add file-local `arrangeFactory`/`defaultDeps`; rewrite the post-bind-guard tests to call them while keeping each `createSubagentSession(...)` act explicit.
+- `test/ui/agent-config-editor.test.ts` — **changed**: convert the menu-option-structure cases to `it.each`; hoist the shared `filePath` in the Edit/Delete blocks.
+
+No `src/` files change.
+No SKILL.md, architecture-doc, or README references to the affected test internals exist to update — these are intra-test fixtures (verified: the architecture roadmap references the *issue* `#426`, not the specific helpers).
+The roadmap step's status flips to ✅ in a follow-up doc pass at ship time, not in this plan (consistent with how steps 1–6 were marked).
+
+## Test Impact Analysis
+
+This issue *is* a test-maintenance change, so the standard extraction lens is inverted:
+
+1. **New tests enabled** — only the new `tmp-settings-dirs.test.ts`, a self-test pinning the shared fixture's filesystem behavior (writes land at the right global/project paths; dispose removes both dirs).
+   No production seam is newly testable.
+2. **Tests becoming redundant** — none are removed outright.
+   The two malformed-settings cases in `layered-settings.test.ts` merge into one `it.each` (two rows = same two assertions, no coverage loss); the agent-config-editor menu cases merge into one `it.each` (one row per former case, identical assertions).
+   The total assertion set is preserved; only the surrounding arrange is deduplicated.
+3. **Tests that must stay as-is** — the act in every consolidated test (`loadSettings`/`loadLayeredSettings`/`createSubagentSession`/`showAgentDetail`) stays written out per the `testing` skill rule; the distinct intent of each Edit/Delete case (write vs. no-write vs. cancel) stays inline.
+
+## Invariants at risk
+
+The four target files belong to surfaces earlier Phase 17/18 steps refactored (`subagent-session-io.ts` fixtures from #378/#412; `create-subagent-session` from #257/#265; `agent-config-editor` UI from the disentanglement spine).
+The invariant at risk is purely **coverage preservation** — a consolidation must not silently drop an assertion.
+Each consolidation step is gated by:
+
+- The full `vitest` suite staying green (test count must not *drop* except by the deliberate `it.each` merges, whose row count equals the former case count).
+- Running `pnpm fallow dupes` after each step to confirm the targeted clone groups disappear and no new ones appear.
+
+No production `Outcome:`/`Landed:` invariant from a prior roadmap step is touched, because no `src/` file changes.
+
+## Refactor Order
+
+These are refactor (not red→green) steps: each makes a consolidation, verifies the suite stays green and the targeted clone groups drop, then commits with `test:`.
+Order is independent — the three consolidations do not depend on each other — but listed for clean, reviewable commits.
+
+1. **Shared settings tmp-dir fixture.**
+   Add `test/helpers/tmp-settings-dirs.ts` + `tmp-settings-dirs.test.ts`; migrate `test/settings.test.ts` and `test/layered-settings.test.ts` to it; fold the two malformed-settings cases in `layered-settings.test.ts` into one `it.each`.
+   Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/settings.test.ts test/layered-settings.test.ts test/helpers/tmp-settings-dirs.test.ts` green; `pnpm fallow dupes` shows `21d1fb01`, `4003c0e7`, `4fc062db` gone.
+   Commit: `test: extract shared settings tmp-dir fixture (#426)`.
+2. **create-subagent-session arrange helpers.**
+   Add file-local `arrangeFactory`/`defaultDeps`; rewrite the post-bind-guard tests to use them with the act kept explicit.
+   Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/lifecycle/create-subagent-session.test.ts` green; clone groups `48ff1484`, `c92feb70`, `5fbe9ebb` gone.
+   Commit: `test: consolidate create-subagent-session post-bind arrange (#426)`.
+3. **agent-config-editor table-driven menu cases.**
+   Convert the menu-option-structure cases to `it.each`; hoist the shared `filePath` in the Edit/Delete blocks.
+   Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/ui/agent-config-editor.test.ts` green; clone groups `4ac7b228`, `a8e71e9c`, `e36d2314`, `23fe1f93` gone.
+   Commit: `test: table-drive agent-config-editor menu cases (#426)`.
+4. **Final verification.**
+   Run the full suite (`pnpm --filter @gotgenes/pi-subagents exec vitest run`), `pnpm run check`, `pnpm run lint`, `pnpm fallow dead-code` (catch orphaned imports left by removed inline helpers), and `pnpm fallow dupes` to confirm the package's test clone-group count is below 15 (expected: 24 → 14).
+   No separate commit unless cleanup is needed.
+
+## Risks and Mitigations
+
+- **Risk: an `it.each` merge silently drops an assertion.**
+  Mitigation: map each former `it` to exactly one table row with the same assertions; confirm the post-merge test count equals (old count − merged duplicates) and the suite stays green.
+- **Risk: removing an inline `writeGlobal`/`writeProject` leaves an orphaned import** (Biome `noUnusedImports` is warning-level, exit 0).
+  Mitigation: step 4 runs `pnpm fallow dead-code`; re-check each migrated file's imports (`mkdirSync`, `writeFileSync`, `mkdtempSync`, `rmSync`, `tmpdir`, `join`) after the fixture swap.
+- **Risk: a helper that wraps the act re-introduces the "act is the subject" smell.**
+  Mitigation: the design keeps every `loadSettings`/`createSubagentSession`/`showAgentDetail` call written out in the test body; helpers cover arrange only.
+- **Risk: the fixture's `filename` parameterization diverges from the two call sites' expectations** (`subagents.json` vs. `FILENAME`).
+  Mitigation: `createSettingsDirs(filename)` takes the filename explicitly; the self-test pins both path shapes.
+
+## Open Questions
+
+- Whether to also dissolve the production clone in `src/ui/agent-config-editor.ts` (dup `ff960d84`) — deferred as a Non-Goal; revisit if the Phase 18 UI-direction ADR (#427) reworks that file anyway.
+- Whether a shared tmp-dir fixture should live in a cross-package location (other packages stand up similar dirs) — out of scope; keep it `pi-subagents`-local until a second consumer appears.
+
+[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/plans/0427-reconsider-ui-direction.md

@@ -0,0 +1,212 @@
+---
+issue: 427
+issue_title: "pi-subagents: reconsider the UI direction from first principles (ADR)"
+---
+
+# Reconsider the UI direction from first principles (ADR)
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 18 carries no `Release:` batch annotation in the architecture roadmap, so this issue ships on its own.
+It is a decision-only ADR plus an architecture-doc update — docs-only, no runtime change — and it completes the Phase 18 roadmap, gateway-ing the (separately planned) Phase 19 implementation.
+
+## Problem Statement
+
+Phase 18's spine (Steps 1–7) disentangled the activity tier from the core, leaving the inherited UI a pure reactive consumer of the broadcast-plus-query surface.
+The UI is now _substitutable_.
+This final step (Step 8, [#427]) decides the UI's _direction and distribution_, not whether substitution is possible — and records the decision in an ADR that gateways Phase 19.
+
+The decision is **per component** (widget, conversation viewer, `/agents` menu) and per the architecture's own first principles: keep, shrink, extract to a separate package, or remove — judged on our terms, not preserved by default.
+Two standing concerns are the evidence:
+
+- **Foreground widget redundancy** — in foreground the tool's inline `onUpdate` stream already shows progress, so the above-editor widget duplicates it; the widget earns its keep only for background agents.
+- **Truncated transcript** — the bespoke conversation viewer renders a custom, capped transcript, yet each child is already persisted as a standard Pi session JSONL (`outputFile`); the limit is the bespoke overlay, not data access.
+
+## Goals
+
+- Write `docs/decisions/0004-reconsider-ui-direction.md` recording a per-component decision for the widget, the conversation viewer, and the `/agents` menu.
+- Record the **distribution** decision: the surviving UI stays in-core as a reactive consumer (substitutable, not extracted to a separate package now).
+- Record the open feasibility questions for the native-session-navigation direction as Phase 19 spike gates (not pretend-resolved).
+- Update `docs/architecture/architecture.md`: mark Phase 18 Step 8 complete, mark Phase 18 complete, and add a forward pointer to ADR-0004 / Phase 19.
+- This is a **decision-only** ADR — no `src/` or `test/` changes; the implementation lands in the separately-planned Phase 19.
+
+## Non-Goals
+
+- No UI code changes (no widget edit, no viewer removal, no menu decomposition, no new `/subagents:settings` command).
+  Those are Phase 19 implementation, planned and shipped separately.
+- No new `@gotgenes/pi-subagents-ui` package — extraction is explicitly _not_ chosen now.
+- No resolution of the `switchSession` mechanics (root-continuity, view-only-vs-interactive) — the ADR records these as Phase 19 spike entry criteria.
+- No full Phase 19 roadmap — the arch-doc update adds only a forward pointer; Phase 19's steps are planned in their own pass.
+- No SKILL.md edits — `package-pi-subagents` SKILL describes the UI domain's module count, which changes only when Phase 19 code lands.
+
+## Background
+
+Relevant modules and how they relate:
+
+- `src/ui/agent-widget.ts` (~290 LOC) — `AgentWidget implements SubagentManagerObserver`; self-drives an 80 ms render loop from lifecycle events (Step 4, [#423]), renders running/completed agents above the editor.
+- `src/ui/conversation-viewer.ts` (~241 LOC) — bespoke `ConversationViewer` overlay; subscribes to `record.subscribeToUpdates`, renders a live, width-capped transcript of one agent's `messages`, plus a streaming indicator.
+- `src/ui/agent-menu.ts` (~331 LOC) + `agent-config-editor.ts`, `agent-creation-wizard.ts`, `agent-file-ops.ts` — the `/agents` command.
+  Four entries: **Running agents** (→ `ConversationViewer`), **Agent types** (→ `AgentConfigEditor` view/edit/enable/disable), **Create new agent** (→ `AgentCreationWizard`), **Settings** (max concurrency / default max turns / grace turns, written to layered settings).
+- `src/tools/foreground-runner.ts` — foreground runs stream progress via the tool's inline `onUpdate` callback; the result is rendered by `result-renderer.ts` (caps display at 50 lines).
+- The core persists each child as a standalone Pi session JSONL at `Subagent.outputFile`; `Subagent.messages` exposes full history.
+
+Pi SDK surface relevant to the candidate redesign (verified against `@earendil-works/pi-coding-agent@0.79.1`):
+
+- `ExtensionActions.switchSession(sessionPath, { withSession })` — switches the **active** session to a different session file; fires `session_before_switch` / `session_shutdown` and invalidates the current session context (`setBeforeSessionInvalidate` exists for host-owned UI teardown).
+  Returns `{ cancelled }`.
+  The switched-to session is fully interactive — `ReplacedSessionContext` exposes `sendUserMessage`.
+- `session-manager` exports `loadEntriesFromFile(filePath)` / `parseSessionEntries(content)` — read a session file's entries without switching (the read-only alternative).
+
+Constraint from AGENTS.md / the package SKILL: pi-subagents is a minimal core, open for extension and closed for modification; the UI is an _observational consumer_ (unlimited, the core never waits on it), distinct from the rationed generative `WorkspaceProvider` seam.
+The ADR records a consumer-design decision; it must not introduce any new inbound dependency from the core onto the UI.
+
+## Design Overview
+
+The ADR records four decisions, each motivated by the first principles in the architecture doc's "first-principles refinement."
+
+### Decision A — Foreground widget: shrink to background agents only
+
+The above-editor widget duplicates the foreground tool's inline `onUpdate` stream.
+Decision: the widget survives **only** as the background-agent status surface (concern (b): background agents have no tool-call display, so _something_ must indicate their state).
+Foreground runs suppress the widget; the inline stream is authoritative there.
+
+Multiple subagents can run in parallel, so the background surface must represent N concurrent agents at once — the widget's existing per-agent tree already does this; the change is _when_ it shows (background-only), not _what_ it shows.
+
+### Decision B — Conversation viewer: replace the bespoke overlay with native session navigation
+
+Concern (c) — "let the operator switch into a subagent's session, scroll/read it, switch between subagents, and exit back to root" — is a richer interaction than a live overlay.
+The core already persists each child as a standalone Pi session JSONL, so this maps onto Pi's own session machinery rather than a bespoke renderer.
+
+Decision (direction): **remove `ConversationViewer`**; the operator navigates into a child's persisted session via Pi's native viewer and back to root.
+The bespoke, width-capped transcript is replaced by the same viewer Pi uses for any session — the recursive-Pi insight applied to the already-persisted session file.
+
+Candidate call-site shape (Phase 19, illustrative — verifies the interaction pattern, not final):
+
+```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
+}
+```
+
+This is Tell-Don't-Ask (hand Pi the session path; Pi owns the viewer) and keeps the core free of transcript-rendering code.
+
+Open mechanics (recorded in the ADR, resolved by a Phase 19 spike — see Open Questions): `switchSession` is a full active-session takeover (not a view-only overlay), it invalidates the current session context, and the switched-to session is interactive.
+The spike decides whether the operator UX is (i) true `switchSession` round-trips, or (ii) a read-only transcript built from `loadEntriesFromFile` that renders Pi-standard entries without leaving root.
+The ADR records the _direction_ (native session machinery over a bespoke renderer) and gates the mechanism on the spike.
+
+### Decision C — `/agents` menu: dissolve the monolithic command into focused surfaces
+
+The single `/agents` command bundles four unrelated jobs.
+Decision (direction): split them; do not keep all in one command.
+The operator does not value managing agent definitions through the menu at all — creating or editing agents is firmly better done with other tools (directly in Pi, or a real text editor / IDE), so both of those surfaces are **removed outright**, not merely deprioritized.
+
+- **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 — the wizard earns no keep.
+- **Agent types (list + config editor)** → **remove.**
+  Viewing and editing agent definitions is better served by opening the `.md` files directly in an editor/IDE; the in-menu config editor earns no keep.
+- **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.
+
+### Decision D — Distribution: keep the surviving UI in-core (substitutable, not extracted)
+
+The spine already made the UI substitutable — a replacement UI is a downstream concern that targets the public broadcast-plus-query surface.
+Decision: the surviving UI (background widget + a settings command + session-navigation glue) **stays in-core** as a reactive consumer.
+Extraction to `@gotgenes/pi-subagents-ui` is _not_ chosen now; it remains an available future option precisely because the core is byte-for-byte identical with or without a given UI consumer (the composition invariant).
+
+This answers the issue's headline question — the UI's _distribution_ — with "keep in core, substitutable," recorded explicitly rather than left implicit.
+
+## Module-Level Changes
+
+This is a decision-only ADR; the only files touched are docs.
+
+- **New:** `packages/pi-subagents/docs/decisions/0004-reconsider-ui-direction.md`.
+  Frontmatter (`status: accepted`, `date: <ISO date>`), then `# 0004 — ...`, `## Status`, `## Context`, `## Decision` (Decisions A–D), `## Consequences`, `## Phase 19 entry criteria` (the spike gates + per-component implementation handles).
+- **Changed:** `packages/pi-subagents/docs/architecture/architecture.md`:
+  - Phase 18 Step 8 (`### Steps`, item 8) — mark complete with a `Landed:` bullet referencing ADR-0004 and the recorded decisions.
+  - Step dependency diagram node `S8` — append a ✅ marker (matching S1–S7) so the diagram is consistent.
+  - The phase summary table row `| 18 | Reconsider UI (first principles) | In progress |` → `Complete`, and add the per-phase pointer to the ADR.
+  - Add a forward-pointer line gateway-ing Phase 19 (implementation of the recorded decisions, planned separately).
+  - Add a `[#427]` reference usage is already present; no new link-ref definition needed.
+    Add an ADR-0004 reference link if the doc cites it by path.
+
+No `src/`, `test/`, or SKILL.md changes — every removed-symbol / reworded-mechanism check is therefore vacuous for this issue (no symbols removed, no runtime mechanism reworded).
+The architecture doc's UI-domain module count and health metrics are _not_ edited here — they change when Phase 19 code lands.
+
+## Test Impact Analysis
+
+None — this is a docs-only ADR.
+
+1. No new unit tests are enabled (no extraction, no behavior change).
+2. No existing tests become redundant (no code removed).
+3. No tests must stay-as-is for a layer being extracted (nothing is extracted in this issue).
+
+The Phase 19 implementation that acts on these decisions will carry its own Test Impact Analysis when it is planned.
+
+## Invariants at risk
+
+None regressed by this issue — it changes no code, so every Phase 18 spine outcome stays green by construction.
+
+The ADR _records_ that Phase 19 must preserve these spine invariants when it implements the decisions:
+
+- Step 3 ([#422]) outcome "runtime holds zero UI state" — Phase 19 must not re-introduce UI state on the core when wiring the background-only widget or session navigation.
+- Step 4/5 ([#423], [#424]) outcome "the widget is a reactive consumer; no inbound calls from core spawn tools / the LLM tool depends only on manager/runtime/settings/registry" — the background-only restriction and the `/agents` decomposition must keep the dependency direction inward.
+- Step 6 ([#425]) outcome "declared channels equal emitted channels; no vacant hook" — any new navigation surface must consume existing broadcast/query channels, not add a vacant one.
+
+These are pinned today by the existing observer/widget/event-contract suites; Phase 19 inherits them.
+
+## Build Order
+
+Docs-only — no red→green test cycles.
+Numbered build steps, each a single reviewable commit.
+
+1. **Write ADR-0004.**
+   Author `docs/decisions/0004-reconsider-ui-direction.md` with Status / Context / Decision (A–D) / Consequences / Phase 19 entry criteria, capturing the `switchSession` findings and open mechanics.
+   Verify: `pnpm run lint` passes (rumdl markdown rules); the ADR states a decision for every component named in [#427].
+   Commit: `docs: add ADR-0004 reconsidering the UI direction (#427)`.
+2. **Update the architecture doc.**
+   Mark Phase 18 Step 8 complete (Landed bullet → ADR-0004), append ✅ to the `S8` diagram node, flip the phase table row to Complete, and add the Phase 19 forward pointer.
+   Verify: `pnpm run lint` passes; the `[#427]` reference still resolves; no orphaned link-ref definitions (MD053); Phase 18 reads as complete end-to-end.
+   Commit: `docs: mark Phase 18 complete and gateway Phase 19 (#427)`.
+
+(Both steps may be folded into one commit if preferred; kept separate here because they touch different documents with different review concerns.)
+
+## Risks and Mitigations
+
+- **Risk:** the ADR over-commits to `switchSession` before its mechanics are understood, locking Phase 19 into an infeasible UX.
+  **Mitigation:** the ADR records the _direction_ (native session machinery over a bespoke renderer) and explicitly gates the _mechanism_ on a Phase 19 spike, listing the read-only `loadEntriesFromFile` fallback as a first-class alternative.
+- **Risk:** removing the conversation viewer and the running-agents menu entry leaves a visibility gap before Phase 19 ships.
+  **Mitigation:** this issue removes _nothing_ — it only records decisions; the viewer/menu stay live until Phase 19 replaces them, so there is no interim regression.
+- **Risk:** the arch-doc edits silently drop an enclosing structure (the Steps list, the diagram fence, the phase table).
+  **Mitigation:** anchor edits on unique adjacent lines, re-read each edited region after editing, and run `pnpm run lint` to confirm the Mermaid fence and tables still parse.
+- **Risk:** a future reader treats the recorded "keep in core" distribution decision as permanent.
+  **Mitigation:** the ADR frames extraction as a still-available option enabled by the composition invariant, with the conditions under which it would be revisited.
+
+## Open Questions
+
+These are recorded in the ADR as Phase 19 spike entry criteria, not resolved 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?
+  Spike before committing Phase 19 to true `switchSession` round-trips.
+- **View-only vs interactive.**
+  A switched-to child session is interactive (`sendUserMessage`).
+  Is steering a child from its own session desirable, or should the viewer be strictly read-only (favoring the `loadEntriesFromFile` transcript path)?
+- **Parallel-agent navigation.**
+  With N background agents running, what is 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: the operator firmly removes both (managing agent definitions belongs in an editor/IDE or a Pi agent, not the menu).
+
+[#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
+[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/plans/0446-spike-session-navigation-entry-criteria.md

@@ -0,0 +1,171 @@
+---
+issue: 446
+issue_title: "pi-subagents: spike — resolve ADR-0004 session-navigation entry criteria"
+---
+
+# Spike: resolve ADR-0004 session-navigation entry criteria
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 1 ([#446]) carries `Release: independent` in the architecture roadmap, and the roadmap's "Release batches" subsection lists it among the independently releasable steps (the only batch is "dissolve-agents" = Steps 5, 6).
+The deliverable is an ADR addendum that unblocks Step 4 ([#445]); it ships on its own with no batch coupling.
+
+## Problem Statement
+
+ADR-0004 (Phase 18) decided the UI *direction* — replace the bespoke `ConversationViewer` overlay with Pi's own session machinery applied to each child's already-persisted session JSONL — but deliberately left the *mechanism* open behind four "Phase 19 entry criteria."
+Each criterion changes the shape of the Step 4 session-navigation code, so all four must be answered before that work can begin.
+This is a spike: produce a minimal, throwaway investigation that answers each criterion against the real SDK surface, then record the answers as an addendum to `docs/decisions/0004-reconsider-ui-direction.md`.
+No production source files change; the spike closes when the ADR addendum is merged.
+
+## Goals
+
+- Answer all four ADR-0004 entry criteria with evidence from the bundled `@earendil-works/pi-coding-agent` SDK surface and a real child session JSONL:
+  1. Root-continuity during a session switch (and the correct "return to root" gesture).
+  2. View-only vs interactive (switch-takeover vs `loadEntriesFromFile` read-only transcript).
+  3. Parallel-agent navigation gesture (widget, command, or both).
+  4. Settings command name (`/subagents-settings` vs `/agents-settings` vs a `:`-namespaced form).
+- Record the answers as a dated addendum to ADR-0004 so Step 4 ([#445]) can commit to a mechanism.
+- Validate the read-only transcript path empirically: a throwaway vitest harness exercises `loadEntriesFromFile` against a real child session file and confirms entries render without a session switch.
+
+## Non-Goals
+
+- No production source changes — `session-navigator.ts`, the widget background-only filter, the settings command, and the `/agents` dissolution are all later Phase 19 steps ([#445], [#444], [#447], [#442], [#441]).
+- Do not implement the chosen mechanism; the spike only chooses it.
+- Do not commit the vitest spike harness — it is throwaway evidence, discarded after observation (operator decision: ADR addendum only).
+- Do not modify `0004-reconsider-ui-direction.md`'s existing Status/Decision/Consequences body beyond appending the addendum.
+
+## Background
+
+Relevant SDK surface, verified against the bundled `@earendil-works/pi-coding-agent` types in `packages/pi-subagents/node_modules/.../dist`:
+
+- `ExtensionCommandContext.switchSession(sessionPath, { withSession })` — a **full active-session takeover** (`core/extensions/types.d.ts:276`).
+  It returns `{ cancelled }` and hands the replacement session to an optional `withSession(ctx: ReplacedSessionContext)` callback.
+- `ReplacedSessionContext extends ExtensionCommandContext` (`types.d.ts:289`) — exposes `sendUserMessage` and `sendMessage`, so a switched-to child session is **interactive**, not read-only.
+- `session_before_switch` (cancellable; `reason: "new" | "resume"`) and `session_shutdown` (`reason: "quit" | "reload" | "new" | "resume" | "fork"`, with `targetSessionFile`) events (`types.d.ts:414`, `:440`) fire around a switch — the current runtime is torn down when the active session is replaced.
+- `setBeforeSessionInvalidate` lives on the **host** runtime (`core/agent-session-runtime.*`, `modes/interactive/interactive-mode.*`), not on the extension command context — it is a host-owned UI-teardown seam, not something this extension calls.
+- `loadEntriesFromFile(filePath): FileEntry[]` and `parseSessionEntries(content): FileEntry[]` (`core/session-manager.d.ts:151`, `:141`, both re-exported from the package root `index.d.ts`) — read a session file's entries **without** switching.
+- `Subagent.outputFile: string | undefined` (`src/lifecycle/subagent.ts:120`, delegating to `subagentSession?.outputFile`) — already exposes each child's persisted session JSONL path; no new SDK dependency is needed.
+- Sibling command registration uses **flat, hyphenated** names with no `:` namespace: `registerCommand("agents", …)` (this package), `registerCommand("colgrep-reindex", …)`, `registerCommand("permission-system", …)`.
+
+AGENTS.md constraint: pi-subagents is a minimal core; the surviving UI is an in-core reactive consumer (ADR-0004 Decision D).
+The spike chooses the navigation mechanism but adds no policy and no new core dependency.
+
+## Design Overview
+
+The spike is an investigation, not a feature.
+Each criterion is answered from the SDK surface above; the one path with genuine runtime uncertainty (read-only transcript rendering) is confirmed with a throwaway vitest harness against a real child session JSONL.
+
+### Criterion 1 — Root-continuity during a session switch
+
+`switchSession` replaces the active session: it fires `session_before_switch` (cancellable) then tears the current runtime down via `session_shutdown` (the `targetSessionFile` field marks a replacement-driven shutdown).
+The root's in-flight turn does **not** survive a takeover — the runtime that owns that turn is invalidated.
+The "return to root" gesture under a true round-trip would be a second `switchSession(rootSessionFile)`, re-incurring the same teardown/replay cost on the way back.
+
+Expected finding: a true `switchSession` round-trip is hostile to a root that may have a turn in flight (background agents run precisely while the operator keeps working at root).
+This pushes the recommendation toward the read-only `loadEntriesFromFile` path, which never touches the active session and so has no return gesture to get wrong.
+
+### Criterion 2 — View-only vs interactive
+
+`ReplacedSessionContext` exposes `sendUserMessage`/`sendMessage`, so switching makes the child interactive — the operator could steer a child from inside its own session.
+ADR-0004 frames operator visibility (concern 3) as "switch in, scroll/read, switch between, exit back to root" — a **navigation** interaction, not a live steering overlay.
+Steering already has a home (`steer_subagent` tool / the widget), so conflating read-navigation with in-session steering adds a second, redundant steering surface.
+
+Expected finding: the viewer should be **read-only**, favoring `loadEntriesFromFile` to render the child's persisted entries without leaving the root session.
+This also resolves Criterion 1 by construction (no switch, no root-continuity problem).
+
+### Criterion 3 — Parallel-agent navigation
+
+With N background agents running, the operator needs a gesture to pick which child to view.
+The background widget (ADR-0004 Decision A, [#444]) already represents N parallel agents as a per-agent tree, making it the natural **selection** surface.
+A flat command (Criterion 4 naming) gives a non-widget entry point that lists running background agents and lets the operator pick one keyed on `record.outputFile`.
+
+Expected finding: provide a **command** as the primary, testable selection surface (lists background agents → operator picks → render that child's transcript read-only), with a widget gesture as an optional later enhancement.
+The command is unit-testable and does not depend on the widget landing first; "both" is the eventual target, command-first is the spike's recommended Step 4 starting point.
+
+### Criterion 4 — Settings command name
+
+Sibling packages register flat, hyphenated command names with no `:` namespace (`agents`, `colgrep-reindex`, `permission-system`).
+A `/subagents:settings` form would be inconsistent with every existing command in the repo.
+
+Expected finding: confirm **`/subagents-settings`** (flat, hyphenated) — already the name used in the architecture roadmap's Step 2 ([#447]).
+Reject the ADR's tentative `/subagents:settings` and the `/agents-settings` alternative (the latter implies it manages agent definitions, which Decision C removes).
+
+### Throwaway vitest harness (discarded, not committed)
+
+A single throwaway spec confirms the read-only path end to end:
+
+```typescript
+// throwaway — discarded after observation, never committed
+import { loadEntriesFromFile } from "@earendil-works/pi-coding-agent";
+
+// against a REAL child session JSONL produced by a background subagent run
+const entries = loadEntriesFromFile(childOutputFile);
+// assert: returns FileEntry[] with the expected message/turn entries,
+// renderable as a transcript, with no switchSession / no active-session mutation.
+```
+
+The harness sources `childOutputFile` from a real run (or an existing session fixture under the Pi session dir), not a synthetic stub, so the observation reflects the actual on-disk JSONL shape the Step 4 viewer will consume.
+It asserts the entries are well-formed and that the read path requires no session switch — confirming `loadEntriesFromFile(Subagent.outputFile)` is a viable read-only transcript source.
+
+## Module-Level Changes
+
+- `packages/pi-subagents/docs/decisions/0004-reconsider-ui-direction.md` — **append** an addendum section (e.g. `## Addendum (2026-06-..): Phase 19 entry-criteria answers`) recording the four answers with their SDK evidence and the resulting Step 4 mechanism decision (read-only `loadEntriesFromFile` transcript, command-first selection, `/subagents-settings` name).
+  Do not rewrite the existing "Phase 19 entry criteria" section — leave it as the question of record and let the addendum answer it.
+- `packages/pi-subagents/docs/architecture/architecture.md` — optional doc-sync only: the Step 1 entry already states its `Outcome`; if marking the spike resolved here is desired, update only that step's status line.
+  Keep out of scope unless the operator wants it folded in at ship time.
+
+No `src/` or committed `test/` files change.
+The vitest spike harness is throwaway and is **not** added to the committed tree (operator decision: ADR addendum only).
+
+## Test Impact Analysis
+
+Not applicable in the usual sense — this spike commits no production code and no retained tests.
+The throwaway vitest harness exists only to observe `loadEntriesFromFile` behavior against a real child session JSONL and is discarded; it enables no new committed test surface and makes no existing test redundant.
+Step 4 ([#445]) will introduce the committed tests for the chosen mechanism.
+
+## Invariants at risk
+
+None.
+The spike changes no runtime code, so the Phase 18 spine invariants ADR-0004 lists (runtime holds zero UI state [#422]; widget is a reactive consumer with no inbound core calls [#423]; the `subagent` tool depends only on manager/runtime/settings/registry [#424]; declared event channels equal emitted channels [#425]) are untouched and stay pinned by their existing suites.
+The addendum must not recommend a Step 4 mechanism that would later violate them — the read-only `loadEntriesFromFile` path is chosen partly because it keeps transcript rendering out of core and adds no inbound call to the core from the UI.
+
+## Build Order
+
+This is a docs/spike deliverable (next stage: `/build-plan`), so the order is investigate → confirm → write → discard, not red→green→commit.
+
+1. **Investigate the SDK surface and confirm the read path.**
+   Re-verify the `switchSession`/`ReplacedSessionContext`/event semantics and `loadEntriesFromFile` signatures in the bundled SDK types, then run the throwaway vitest harness against a real child session JSONL to confirm read-only transcript rendering is viable.
+   No commit (throwaway harness is discarded).
+2. **Write the ADR-0004 addendum.**
+   Append the dated addendum answering all four criteria with their SDK evidence and the resulting Step 4 mechanism decision.
+   Verify: addendum present, four criteria each answered with a recommendation, markdown lints clean (`pnpm --filter @gotgenes/pi-subagents run lint` or repo `pnpm run lint`).
+   Commit: `docs: resolve ADR-0004 session-navigation entry criteria (#446)`.
+3. **Optional doc-sync.**
+   If folding in the architecture status update, amend only Step 1's status line in `architecture.md` in the same or a follow-up `docs:` commit; otherwise leave it for ship time.
+
+## Risks and Mitigations
+
+- **Risk: root-continuity cannot be fully proven without a live multi-session run, and the chosen method is an automated harness only.**
+  Mitigation: the answer is derivable from the documented event semantics (a switch tears down the active runtime via `session_shutdown`), which is exactly why the recommendation avoids `switchSession` for navigation; the harness confirms the read-only alternative works, sidestepping the unproven path.
+- **Risk: the addendum recommends a mechanism that Step 4 cannot honor (e.g. a TUI rendering limitation in `loadEntriesFromFile`).**
+  Mitigation: the throwaway harness exercises the real entries shape before the recommendation is written; Step 4 retains the freedom to revisit if a rendering gap surfaces, since the ADR records direction, not an irreversible commitment.
+- **Risk: scope creep into implementing the chosen surface.**
+  Mitigation: Non-Goals explicitly defer all production changes to [#445]/[#444]/[#447]/[#442]/[#441]; the only committed file is the ADR addendum.
+
+## Open Questions
+
+- Whether to also land the `architecture.md` Step 1 status update in this issue or defer it — decide at ship time (Build Order step 3).
+- The widget gesture for parallel-agent navigation (Criterion 3 "both") is left to Step 4 — the spike recommends command-first and notes the widget gesture as an optional follow-up.
+
+[#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
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#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