@gotgenes/pi-subagents 18.0.0 → 18.0.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [18.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v18.0.0...pi-subagents-v18.0.1) (2026-06-24)
+
+
+### Documentation
+
+* **pi-subagents:** refresh README for /subagents:settings and /subagents:sessions ([#470](https://github.com/gotgenes/pi-packages/issues/470)) ([945341f](https://github.com/gotgenes/pi-packages/commit/945341fc5527a2e9371d261e0eb1340d09b72f31))
+
 ## [18.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.5.0...pi-subagents-v18.0.0) (2026-06-23)
 
 

package/README.md

@@ -18,7 +18,7 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
 - **In-process & native** — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
-- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
+- **Session transcripts** — open any subagent's full session transcript (running or evicted) in pi's native read-only viewer via `/subagents:sessions`
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
@@ -116,7 +116,7 @@ The LLM receives structured `<task-notification>` XML for parsing, while the use
 The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does.
 Explore and Plan use `replace` mode: the parent prompt is the cacheable base and their specialist read-only instructions are appended last, giving them the final say.
 
-Default agents can be **ejected** (`/agents` → select agent → Eject) to export them as `.md` files for customization, **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
+Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
 
 ## Custom Agents
 
@@ -223,31 +223,22 @@ The message interrupts after the current tool execution.
 
 ## Commands
 
-| Command   | Description                       |
-| --------- | --------------------------------- |
-| `/agents` | Interactive agent management menu |
+| Command               | Description                                            |
+| --------------------- | ------------------------------------------------------ |
+| `/subagents:settings` | Configure subagent settings (concurrency, turn limits) |
+| `/subagents:sessions` | View a subagent's session transcript (read-only)       |
 
-The `/agents` command opens an interactive menu:
+### `/subagents:settings`
 
-```text
-Running agents (2) — 1 running, 1 done     ← only shown when agents exist
-Agent types (6)                             ← unified list: defaults + custom
-Create new agent                            ← manual wizard or AI-generated
-Settings                                    ← max concurrency, max turns, grace turns
-```
+Interactive list to tune runtime settings — max concurrency, default max turns, and grace turns.
+Changes persist across pi restarts (see [Persistent Settings](#persistent-settings)).
+
+### `/subagents:sessions`
+
+Pick any subagent — running or already evicted — and read its full session transcript in pi's native per-entry viewer.
+Read-only: no steering, no session takeover (steering lives in the `steer_subagent` tool and the background widget).
 
-- **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled).
-  Select an agent to manage it:
-  - **Default agents** (no override): Eject (export as `.md`), Disable
-  - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete
-  - **Custom agents**: Edit, Disable, Delete
-  - **Disabled agents**: Enable, Edit, Delete
-- **Eject** — writes the embedded default config as a `.md` file to project or personal location, so you can customize it
-- **Disable/Enable** — toggle agent availability.
-  Disabled agents stay visible in the list (marked `✕`) and can be re-enabled
-- **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file).
-  Any name is allowed, including default agent names (overrides them)
-- **Settings** — configure max concurrency, default max turns, and grace turns at runtime
+Creating and editing agent definitions is not a command — write an agent `.md` file in your editor, or ask a pi session to generate one (see [Custom Agents](#custom-agents)).
 
 ## Graceful Max Turns
 
@@ -274,13 +265,13 @@ Foreground agents bypass the queue — they block the parent anyway.
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns) persist across pi restarts.
+Runtime tuning values set via `/subagents:settings` (max concurrency, default max turns, grace turns) persist across pi restarts.
 Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults.
-  Edit by hand; the `/agents` menu never writes here.
+  Edit by hand; the `/subagents:settings` command never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides.
-  Written by `/agents` → Settings.
+  Written by `/subagents:settings`.
 
 **Precedence:** project overrides global on any field present in both.
 Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`).
@@ -297,10 +288,10 @@ cat > ~/.pi/agent/subagents.json <<'EOF'
 EOF
 ```
 
-Every project now starts with concurrency 16 and grace 10, without ever touching the menu.
-Individual projects can still override via `/agents` → Settings.
+Every project now starts with concurrency 16 and grace 10, without ever touching the command.
+Individual projects can still override via `/subagents:settings`.
 
-**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/agents` toast to a warning with `(session only; failed to persist)`.
+**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/subagents:settings` toast to a warning with `(session only; failed to persist)`.
 
 ## Events
 
@@ -315,7 +306,7 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:steered`          | Steering message sent                                   | `id`, `message`                                                                                                      |
 | `subagents:compacted`        | Agent's session successfully compacted                  | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
 | `subagents:settings_loaded`  | Persisted settings applied at extension init            | `settings` (merged global + project)                                                                                 |
-| `subagents:settings_changed` | `/agents` → Settings mutation was applied               | `settings`, `persisted` (`boolean` — `false` on write failure)                                                       |
+| `subagents:settings_changed` | `/subagents:settings` mutation was applied              | `settings`, `persisted` (`boolean` — `false` on write failure)                                                       |
 
 `tokens.total` = `input + output + cacheWrite`.
 `cacheRead` is excluded — each turn's `cacheRead` is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it.

package/docs/plans/0443-consolidate-remaining-test-clone-families.md

@@ -0,0 +1,268 @@
+---
+issue: 443
+issue_title: "pi-subagents: consolidate remaining test clone families"
+---
+
+# Consolidate remaining test clone families
+
+## Release Recommendation
+
+**Release:** ship independently
+
+This is Phase 19 Step 7 (Track C — test health), tagged `Release: independent` in the architecture roadmap.
+It depends only on the terminal cut (Steps 5–6, [#441] / [#442], both closed) having landed, which it has.
+No other roadmap step is gated on it, so it ships on its own.
+
+## Problem Statement
+
+`fallow dupes` reports test clone families in `pi-subagents`.
+The issue (written at the Phase 18 end) named five files and a "≤ 10 clone groups (from 16)" target, on the premise that each clone is an extractable shared fixture.
+
+Re-running fallow against current `main` (after the terminal cut shifted line numbers and the Phase-19 UI surfaces added new test files) shows the live picture differs from the issue's snapshot.
+There are **16** `pi-subagents` test clone families today, but they split into two kinds:
+
+1. Genuine *arrange / fixture / helper* duplication — safe to extract.
+2. The repeated *system-under-test call* (`resolveSpawnConfig`, `assembleSessionConfig`, `schedule`) — which the `testing` skill explicitly says **not** to wrap in a helper just to clear a duplication metric, because the repeated act *is* the test subject.
+
+Several of the issue's five named targets fall into category 2.
+The operator confirmed (planning `ask_user`) a **guardrail-first** approach over the **full live set** of clones: extract only genuine fixtures, leave act-clones in place and documented, and address the new Phase-19 UI clones the issue never anticipated.
+
+## Goals
+
+- Extract genuine (non-act) test duplication into shared or hoisted helpers, following the package's `test/helpers/*.ts` convention.
+- Clear the clone families that are legitimately arrange/fixture/result-extraction boilerplate.
+- Keep the full suite green at every step — the existing tests are the safety net for their own refactor.
+- Reach the issue's `≤ 10` clone-group target *honestly*, without wrapping any system-under-test call.
+- Document the residual act-clones as intentional in the plan, so a future fallow pass does not re-flag them as oversight.
+
+## Non-Goals
+
+- Do **not** wrap or extract the repeated system-under-test call to clear a clone metric (the `testing`-skill guardrail).
+  These act-clones are left in place by design:
+  - `test/tools/spawn-config.test.ts` — repeated `resolveSpawnConfig(...)` calls (`dup:9b42a569`, `dup:ef875c08`).
+  - `test/session/session-config.test.ts` — repeated `assembleSessionConfig(...)` calls (`dup:539a8ca2`).
+  - `test/lifecycle/concurrency-limiter.test.ts` — repeated `schedule(...)` sequences (`dup:ff841f05`).
+  - `test/lifecycle/subagent-manager.test.ts` — `spawnBg` + `await promise` act blocks (`dup:29158516`, `dup:082c007e`).
+  - `test/lifecycle/subagent.test.ts` — `agent.run()` act block (`dup:a3814745`).
+  - `test/tools/get-result-tool.test.ts` — `execute(...)` act block (`dup:230828a8`, 5 lines, marginal).
+- No production-source changes — this is test-only.
+- No change to test *assertions* or behavior coverage; only the arrange/setup ceremony is consolidated.
+- No new fallow rule or config change.
+
+## Background
+
+- Phase 19 Step 7 in `packages/pi-subagents/docs/architecture/architecture.md` ([#443]) — the roadmap entry, `Release: independent`.
+- The terminal cut ([#441], [#442]) removed `agent-menu.ts`, the conversation viewer, and the definition-management subtree, deleting ~4 of the Phase-18 clone groups automatically and shifting the line numbers in the issue's target list.
+- The Phase-19 replacement surfaces added new test files the issue could not have named: `test/ui/session-navigation.test.ts` and `test/ui/session-navigator.test.ts` ([#445], [#462], [#463]), which carry the largest genuine clone (an identical `makeNavigable` factory duplicated across both files).
+- Shared-fixture convention: `test/helpers/<name>.ts` exporting named helpers, imported via the `#test/helpers/<name>` path alias, each with a companion `<name>.test.ts` (e.g. `make-subagent.ts` + `make-subagent.test.ts`).
+- The `testing` skill rule that drives the guardrail: "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."
+
+## Design Overview
+
+### Clone classification (live fallow output vs. issue)
+
+| Fingerprint    | Location                                                                      | Kind                                           | Disposition                 |
+| -------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------- |
+| `dup:1d5dc276` | `ui/agent-widget.test.ts` :229 / :292                                         | duplicated `makeWidget` helper                 | **Extract** (hoist)         |
+| `dup:e29e4749` | `ui/session-navigation.test.ts` :23 / `ui/session-navigator.test.ts` :47      | duplicated `makeNavigable` factory (identical) | **Extract** (shared helper) |
+| `dup:6268a42f` | `ui/session-navigator.test.ts` :201 / :229                                    | captured-overlay invocation boilerplate        | **Extract** (local helper)  |
+| `dup:ea0a1bce` | `ui/session-navigator.test.ts` :220 / :243                                    | captured-overlay invocation boilerplate        | **Extract** (local helper)  |
+| `dup:b0d55079` | `lifecycle/subagent-manager.test.ts` :92 / :109                               | `resultConsumed`-observer arrange              | **Extract** (local helper)  |
+| `dup:080c5017` | `lifecycle/subagent.test.ts` :257 / :273                                      | "ready subagent" arrange                       | **Extract** (local helper)  |
+| `dup:5d8dbd48` | `lifecycle/subagent-manager.test.ts` :376 / `lifecycle/subagent.test.ts` :717 | resume-events mock body (cross-file)           | **Extract** (shared helper) |
+| `dup:f4c08c00` | `lifecycle/workspace-bracket.test.ts` :90 / :97                               | prepared-bracket arrange                       | **Extract** (local helper)  |
+| `dup:9b42a569` | `tools/spawn-config.test.ts` :43 / :56                                        | `resolveSpawnConfig` act                       | Leave (Non-Goal)            |
+| `dup:ef875c08` | `tools/spawn-config.test.ts` :81 / :95                                        | `resolveSpawnConfig` act                       | Leave (Non-Goal)            |
+| `dup:539a8ca2` | `session/session-config.test.ts` :131 / :151                                  | `assembleSessionConfig` act                    | Leave (Non-Goal)            |
+| `dup:ff841f05` | `lifecycle/concurrency-limiter.test.ts` :21 / :148                            | `schedule` act                                 | Leave (Non-Goal)            |
+| `dup:29158516` | `lifecycle/subagent-manager.test.ts` :335 / :383                              | `spawnBg` + await act                          | Leave (Non-Goal)            |
+| `dup:082c007e` | `lifecycle/subagent-manager.test.ts` :410 / :422                              | `spawnBg` + await act                          | Leave (Non-Goal)            |
+| `dup:a3814745` | `lifecycle/subagent.test.ts` :504 / :533                                      | `agent.run()` act                              | Leave (Non-Goal)            |
+| `dup:230828a8` | `tools/get-result-tool.test.ts` :81 / :89                                     | `execute` act (5 lines)                        | Leave (Non-Goal)            |
+
+Extracting the eight **Extract** families clears those fingerprints and drops the count from 16 to **8** — below the issue's `≤ 10` target — with no act-clone wrapped. (The four primary UI/lifecycle extractions alone reach 10; the cross-file and workspace-bracket arrange extractions take it to 8.)
+
+### Shared-helper extractions (cross-file → `test/helpers/`)
+
+Two clones span two files each, so their helpers must live in `test/helpers/` (the package convention for shared fixtures, with a companion test):
+
+`test/helpers/make-navigable.ts`:
+
+```typescript
+import type { NavigableSubagent } from "#src/ui/session-navigation";
+
+export function makeNavigable(overrides: Partial<NavigableSubagent> = {}): NavigableSubagent {
+  return {
+    id: "agent-1",
+    type: "general-purpose",
+    description: "Test task",
+    status: "completed",
+    startedAt: 1000,
+    completedAt: 4000,
+    toolUses: 2,
+    activeTools: new Map(),
+    responseText: "",
+    agentMessages: [],
+    isSessionReady: () => true,
+    subscribeToUpdates: vi.fn(() => () => {}),
+    getToolDefinition: vi.fn(() => undefined),
+    ...overrides,
+  };
+}
+```
+
+The two source copies are byte-identical (verified with `diff`), so this is a pure lift with no reconciliation.
+Both call sites import it: `import { makeNavigable } from "#test/helpers/make-navigable";`.
+
+`test/helpers/mock-session.ts` (extend the existing helper) — add a resume-events emitter for `dup:5d8dbd48`:
+
+```typescript
+export function emitResumeUsageAndCompaction(session: MockSession): void {
+  session.emit({ type: "message_end", message: { role: "assistant", usage: { input: 70, output: 30, cacheWrite: 5 } } });
+  session.emit({ type: "compaction_end", aborted: false, result: { tokensBefore: 999 }, reason: "overflow" });
+}
+```
+
+Both `subagent-manager.test.ts` and `subagent.test.ts` set this inside a `mockImplementation(async () => { …; return "second"; })`, so the helper emits the events and each call site keeps its own `mockImplementation` wrapper and `return`. (Adding to the already-shared `mock-session.ts` avoids a one-function new module; its companion `mock-session.test.ts` gains a case.)
+
+### Local-helper extractions (single-file)
+
+These stay file-local (the convention reserves `test/helpers/` for cross-file sharing); each is a `function` declared once at the top of its `describe`/module and called from each test, with the **act left explicit** in every test:
+
+- `ui/agent-widget.test.ts` — the `makeWidget(agents)` helper is currently declared *twice* (one per `describe`).
+  Hoist a single copy to module scope (above the first `describe`) and delete the second.
+  The second `describe` uses `vi.useFakeTimers()` in `beforeEach`, but `makeWidget` does not touch timers, so a module-scope definition serves both.
+- `ui/session-navigator.test.ts` — extract a `renderCapturedOverlay(ui): string[]` helper that performs the repeated `const factory = ui.custom.mock.calls[0][0] as (…) => Component; return factory(mockTui(), ansiTheme(), undefined, vi.fn()).render(80);`.
+  This is *result extraction* (reading what the SUT produced), not the act (`new SessionNavigatorHandler().handle(…)` stays explicit in each test).
+  The `#423` reactive-consumer invariant assertion (`expect(record.getToolDefinition).not.toHaveBeenCalled()`) lives in the test body, untouched by the helper.
+- `lifecycle/subagent-manager.test.ts` — extract a local `seedResultConsumedObserver()` returning `{ manager, record, seenConsumed: () => boolean | undefined }` for the two Bug-1 tests; the act (`markConsumed()` before/after `await record.promise`) stays in each test.
+- `lifecycle/subagent.test.ts` — extract a local `makeReadySubagent()` returning `{ agent }` (build `makeSubagent()`, push a message onto a `createMockSession()`, wire `createSubagentSessionStub`/`toSubagentSession`); the act (reading `agent.messages` vs `agent.agentMessages`) stays in each test.
+- `lifecycle/workspace-bracket.test.ts` — extract a local `preparedBracket(addendum?)` async helper that builds the workspace, constructs the `WorkspaceBracket`, and awaits `prepare(ctx)`, returning the bracket; the act (`bracket.dispose(outcome)`) stays in each test.
+
+### Guardrail rationale (why the act-clones stay)
+
+`spawn-config.test.ts` already extracts its arrange (`makeModelInfo`, `testRegistry`, `defaultSettings`); the only remaining duplication is the four-argument `resolveSpawnConfig(...)` call — the SUT.
+`session-config.test.ts`'s clone is the six-argument `assembleSessionConfig(...)` SUT call.
+`concurrency-limiter.test.ts`'s clone is the `schedule(...)` act sequence.
+Wrapping any of these would hide the test subject behind a helper, exactly the anti-pattern the `testing` skill names.
+They are recorded in Non-Goals so a later fallow pass reads them as deliberate.
+
+### Design-review check
+
+The `design-review` checklist (dependency width, Law of Demeter, output arguments, shared-interface changes) targets production wiring.
+This change touches only test arrange code and introduces no production collaborator or shared-interface change, so the checklist finds nothing applicable.
+The new `makeNavigable` helper follows ISP — it returns a full `NavigableSubagent` because both consumers (`listNavigableAgents` fixtures and `SessionNavigatorHandler` records) need the whole shape; there is no unused-field smell.
+
+## Module-Level Changes
+
+New files:
+
+- `packages/pi-subagents/test/helpers/make-navigable.ts` — shared `makeNavigable` factory.
+- `packages/pi-subagents/test/helpers/make-navigable.test.ts` — companion test (per convention).
+
+Changed files:
+
+- `packages/pi-subagents/test/helpers/mock-session.ts` — add `emitResumeUsageAndCompaction(session)`.
+- `packages/pi-subagents/test/helpers/mock-session.test.ts` — add a case for the new emitter.
+- `packages/pi-subagents/test/ui/session-navigation.test.ts` — delete local `makeNavigable`, import the shared one.
+- `packages/pi-subagents/test/ui/session-navigator.test.ts` — delete local `makeNavigable`, import the shared one; add `renderCapturedOverlay` local helper and migrate its two clone sites.
+- `packages/pi-subagents/test/ui/agent-widget.test.ts` — hoist `makeWidget` to a single module-scope definition; delete the duplicate.
+- `packages/pi-subagents/test/lifecycle/subagent-manager.test.ts` — add `seedResultConsumedObserver` local helper (migrate `:92`/`:109`); migrate the `dup:5d8dbd48` resume-mock site to `emitResumeUsageAndCompaction`.
+- `packages/pi-subagents/test/lifecycle/subagent.test.ts` — add `makeReadySubagent` local helper (migrate `:257`/`:273`); migrate the `dup:5d8dbd48` resume-mock site to `emitResumeUsageAndCompaction`.
+- `packages/pi-subagents/test/lifecycle/workspace-bracket.test.ts` — add `preparedBracket` local helper; migrate the four construct-and-prepare sites.
+
+Documentation:
+
+- `packages/pi-subagents/docs/architecture/architecture.md` — Phase 19 Step 7 currently states "Outcome: test clone groups ≤ 10 (from 16); `subagent-manager.test.ts` uses shared factory helpers."
+  Update the Outcome to record the achieved count (8) and that the residual six families are intentional act-clones (left per the `testing` guardrail), so the roadmap and fallow stay reconciled.
+  No layout/complexity table references these test files, so no other architecture edit is needed.
+- No `package-pi-subagents` SKILL.md reference to these helpers or counts — grep confirms no doc symbol to update beyond the architecture Outcome line.
+
+## Test Impact Analysis
+
+1. **New lower-level tests enabled.**
+   `make-navigable.test.ts` and the new `mock-session.test.ts` case pin the shared helpers' default shapes directly — previously each consumer test re-encoded the defaults inline.
+   These are the only genuinely new tests; the rest is arrange consolidation.
+2. **Tests made redundant.**
+   None are removed.
+   The behavior assertions in every migrated test stay exactly as-is; only their arrange/setup lines collapse into a helper call.
+   The local copies of `makeNavigable`/`makeWidget` are deleted (duplication removed), not their tests.
+3. **Tests that must stay as-is.**
+   All act-clone tests (Non-Goals list) keep their explicit SUT call.
+   The `session-navigator.test.ts` `#423` reactive-consumer assertions stay in the test body; `renderCapturedOverlay` only factors out the overlay-rendering boilerplate, not the assertions.
+
+## Invariants at risk
+
+- **`#423` reactive-consumer invariant** (`SessionNavigatorHandler` sources the transcript and never reads tool definitions off the record): pinned by `expect(record.getToolDefinition).not.toHaveBeenCalled()` in `session-navigator.test.ts`.
+  The `renderCapturedOverlay` extraction must leave that assertion in the test body, not absorb it.
+- **Resume usage/compaction accumulation** (`#420`/`#421`/Phase 17 observer lifecycle): pinned by the resume tests in both `subagent-manager.test.ts` and `subagent.test.ts`.
+  `emitResumeUsageAndCompaction` must emit the identical event payloads (`input:70 output:30 cacheWrite:5`, `tokensBefore:999`, `reason:"overflow"`); the migrated tests assert on these exact numbers, so a value drift would surface as a red test in the same step.
+- **Widget background-only filter** (`#444`/`#423`): the hoisted `makeWidget` must keep the `runInBackground: true` default merge (`{ invocation: { runInBackground: true }, ...a }`) — both `describe` copies already share it, so the hoist preserves it verbatim.
+
+Each invariant is already covered by an existing assertion; no new pinning test is required beyond the helper companion tests.
+
+## TDD Order
+
+This is a test-only refactor: there is no new product behavior, so the "green" gate at each step is the **existing suite staying green** after the arrange is consolidated.
+Each step is independently committable and leaves the suite green.
+Run the affected file(s) with `pnpm --filter @gotgenes/pi-subagents exec vitest run <path>` and the full suite before the final commit (shared `test/helpers` changes touch multiple files).
+
+1. **Shared `makeNavigable` fixture.**
+   Add `test/helpers/make-navigable.ts` and `make-navigable.test.ts` (companion: assert default shape + an override).
+   Delete the two local copies in `session-navigation.test.ts` / `session-navigator.test.ts` and import from `#test/helpers/make-navigable`.
+   Run both UI files green.
+   Commit: `test(pi-subagents): extract shared makeNavigable test fixture`.
+2. **`agent-widget` makeWidget hoist.**
+   Hoist one `makeWidget` to module scope; delete the duplicate in the second `describe`.
+   Run `agent-widget.test.ts` green.
+   Commit: `test(pi-subagents): hoist duplicated makeWidget helper`.
+3. **`session-navigator` captured-overlay helper.**
+   Add `renderCapturedOverlay(ui)` and migrate the two clone sites (`dup:6268a42f`, `dup:ea0a1bce`), keeping the `#423` assertions inline.
+   Run `session-navigator.test.ts` green.
+   Commit: `test(pi-subagents): extract captured-overlay render helper`.
+4. **`subagent-manager` resultConsumed arrange + resume-events emitter.**
+   Add `emitResumeUsageAndCompaction` to `mock-session.ts` (+ companion case).
+   Add local `seedResultConsumedObserver` and migrate `:92`/`:109`.
+   Migrate the resume-mock site (`dup:5d8dbd48` manager half) to the emitter.
+   Run `subagent-manager.test.ts` + `mock-session.test.ts` green.
+   Commit: `test(pi-subagents): consolidate subagent-manager arrange helpers`.
+5. **`subagent` ready-subagent arrange + resume-events emitter.**
+   Add local `makeReadySubagent` and migrate `:257`/`:273`.
+   Migrate the resume-mock site (`dup:5d8dbd48` subagent half) to `emitResumeUsageAndCompaction`.
+   Run `subagent.test.ts` green (this clears the cross-file `dup:5d8dbd48` once both halves use the emitter).
+   Commit: `test(pi-subagents): consolidate subagent ready-state arrange`.
+6. **`workspace-bracket` prepared-bracket arrange.**
+   Add local `preparedBracket(addendum?)` and migrate the four construct-and-prepare sites.
+   Run `workspace-bracket.test.ts` green.
+   Commit: `test(pi-subagents): extract preparedBracket setup helper`.
+7. **Verify + document.**
+   Run the full suite, `pnpm run check`, `pnpm run lint`, and `pnpm fallow dupes --workspace @gotgenes/pi-subagents` to confirm the eight target fingerprints are gone and the count is ≤ 10.
+   Update the Phase 19 Step 7 Outcome line in `architecture.md` to the achieved count and the intentional-residual note.
+   Commit: `docs(pi-subagents): reconcile Phase 19 Step 7 outcome with achieved clone count`.
+
+## Risks and Mitigations
+
+- **Risk: hoisting `makeWidget` past the fake-timers `beforeEach` changes timing.**
+  Mitigation: `makeWidget` constructs objects only (no timer calls); the `vi.useFakeTimers()` lives in the second `describe`'s `beforeEach`, unaffected by where the helper is declared.
+  Step 2 runs the file green to confirm.
+- **Risk: the resume-events emitter drifts from one of the two call sites' expected numbers.**
+  Mitigation: both sites currently use identical payloads (verified); the migrated tests assert the exact numbers, so any drift fails red in steps 4–5.
+- **Risk: a `test/helpers` change silently breaks an unrelated importer.**
+  Mitigation: `mock-session.ts` is widely imported; the change is purely additive (new export), and step 4 runs the full suite.
+- **Risk: orphaned imports after deleting local helpers (Biome `noUnusedImports` is warning-level).**
+  Mitigation: after each deletion, re-check the file's imports (e.g. `vi` may still be used elsewhere; `NavigableSubagent` import in the UI files is type-only and still referenced).
+  The step 7 `pnpm run lint` is the backstop.
+- **Risk: fallow re-flags the intentional act-clones in a future audit.**
+  Mitigation: the Non-Goals list and the architecture Outcome note record them as deliberate.
+
+## Open Questions
+
+- None.
+  The guardrail-first / full-live-set scope was settled via the planning `ask_user`; no follow-up issue is warranted because the residual act-clones are intentional, not deferred work.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#443]: https://github.com/gotgenes/pi-packages/issues/443
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463

package/docs/plans/0470-refresh-readme-command-surface.md

@@ -0,0 +1,159 @@
+---
+issue: 470
+issue_title: "pi-subagents: README still documents the removed /agents command and omits /subagents:settings and /subagents:sessions"
+---
+
+# Refresh pi-subagents README to the post-Phase-19 command surface
+
+## Release Recommendation
+
+**Release:** ship independently
+
+This is a standalone documentation fix.
+It is not a member of any architecture-roadmap step or `Release: batch` — the `dissolve-agents` batch (Steps 5–6, [#442]/[#441]) already shipped as `pi-subagents-v18.0.0`, and this issue corrects README staleness that batch left behind.
+There is no code change and nothing to batch with, so it ships on its own.
+
+## Problem Statement
+
+The Phase 19 terminal cut ([#442], [#441]) removed the `/agents` command, the bespoke conversation viewer, and the agent creation wizard / config editor, replacing them with `/subagents:settings`, `/subagents:sessions`, and the always-on background widget.
+`packages/pi-subagents/README.md` was never updated and still documents the deleted surface as if it were live.
+This shipped to npm with `pi-subagents-v18.0.0`, so the published package's README actively misleads users toward commands and menu actions that no longer exist.
+
+## Goals
+
+- Replace every reference to the removed `/agents` interactive menu with the current focused commands `/subagents:settings` and `/subagents:sessions`.
+- Remove the **Conversation viewer** feature bullet — the live-scrolling overlay was deleted; transcript viewing is now served by `/subagents:sessions`.
+- Remove the **eject** customization story from the Default Agent Types section — the eject/disable/enable/edit/delete menu is gone; customization is now "override by creating `.pi/agents/<name>.md`" and disabling stays `enabled: false` frontmatter (per ADR-0004 Decision C).
+- Rewrite the **Commands** section to document the two real commands instead of the deleted `/agents` menu tree.
+- Correct the **Persistent Settings** section's `/agents` → Settings references to `/subagents:settings`.
+- Correct the **Events** table's `subagents:settings_changed` description (currently "`/agents` → Settings mutation").
+- Add a feature bullet (or amend an existing one) so the read-only session navigation surface (`/subagents:sessions`) is discoverable in the Features list, since the deleted Conversation viewer bullet was its only nearby mention.
+
+## Non-Goals
+
+- No source, test, or behavior changes — this is a pure documentation edit.
+  `src/`, `test/`, the architecture doc, and the ADRs are already accurate (architecture.md lines 405/559 already describe the Phase 19 outcome) and are not touched.
+- No rewrite of accurate sections (Quick Start, UI widget render examples, Default Agent Types table, Custom Agents, Tools, Graceful Max Turns, Concurrency, Worktree Isolation, migration notes, For Extension Authors).
+- No new screenshots or media.
+  The widget render examples in the **UI** section already describe the background-only widget accurately and stay as-is.
+- No change to the `subagents.json` settings-file layering description (global `~/.pi/agent/subagents.json` + project `.pi/subagents.json`) — that mechanism is unchanged; only the command name that writes the project file changed.
+
+## Background
+
+Relevant current surface (verified against `src/index.ts`):
+
+- `pi.registerCommand("subagents:settings", …)` → `SubagentsSettingsHandler.handle({ ui })` — interactive list to set max concurrency, default max turns, and grace turns at runtime (`src/ui/subagents-settings.ts`).
+  This is the re-homed Settings job from the old `/agents` menu; it still persists to the same `subagents.json` files.
+- `pi.registerCommand("subagents:sessions", …)` → `SessionNavigatorHandler.handle({ … agents, evicted, registry, cwd, readFile })` — read-only transcript navigation over `manager.listAgents()` and `manager.listEvicted()`, so any subagent (live or evicted) is navigable (`src/ui/session-navigation.ts`, `session-navigator.ts`).
+
+ADR-0004 Decision C (`docs/decisions/0004-reconsider-ui-direction.md`) is the authority for the customization story the README must now tell:
+
+- Create-new-agent wizard → removed.
+  An operator generates a new agent `.md` by asking a Pi session directly or by writing the file in an editor.
+- Agent-types list + config editor → removed.
+  Viewing/editing definitions is done by opening the `.md` files in an editor/IDE.
+- The eject convenience no longer exists; overriding a default agent is done by creating `.pi/agents/<name>.md` with the same name, and disabling stays `enabled: false` frontmatter.
+
+AGENTS.md constraint that applies: this is a single-package README change, so it lives in `packages/pi-subagents/docs/plans/`.
+The README documents commands, not module filenames, which is exactly why the Phase 19 module-name doc-staleness check missed it (the issue's own root-cause note, Refs [#442]/[#441]).
+
+## Design Overview
+
+Pure prose edit, no decision model or data shapes.
+The README is restructured section-by-section to describe the live surface.
+The one structural choice is how to present the two commands in the **Commands** section: keep the existing two-column command table (`| Command | Description |`) with two rows, then a short subsection per command describing what it opens, instead of the old single-command-plus-menu-tree layout.
+
+### Commands section — target shape (illustrative)
+
+```markdown
+## Commands
+
+| Command               | Description                                            |
+| --------------------- | ------------------------------------------------------ |
+| `/subagents:settings` | Configure subagent settings (concurrency, turn limits) |
+| `/subagents:sessions` | View a subagent's session transcript (read-only)       |
+
+### `/subagents:settings`
+
+Interactive list to tune runtime settings — max concurrency, default max turns, and grace turns.
+Changes persist across pi restarts (see Persistent Settings).
+
+### `/subagents:sessions`
+
+Pick any subagent — running or already evicted — and read its full session transcript in pi's native per-entry viewer.
+Read-only: no steering, no session takeover (steering lives in the `steer_subagent` tool).
+```
+
+The command descriptions in the table are copied verbatim from the `registerCommand` calls in `src/index.ts` so the README matches what `/help` shows.
+
+### Customization story — Default Agent Types section
+
+Replace the eject sentence (line 119) with two retained mechanisms only:
+
+```markdown
+Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
+```
+
+(The "ejected … to export them as `.md` files" clause is dropped entirely — there is no eject UI to produce the export.)
+
+## Module-Level Changes
+
+Single file: `packages/pi-subagents/README.md`.
+Line numbers are against the current README (from the issue's "Affected lines"); each is a prose edit, not a code change.
+
+1. **Line 21 — Features list, Conversation viewer bullet.**
+   Remove the `**Conversation viewer**` bullet (it describes selecting an agent in `/agents` to open a live overlay).
+   In its place, add a bullet for read-only session navigation, e.g. `**Session transcripts** — open any subagent's full session transcript (running or evicted) in a read-only viewer via /subagents:sessions`.
+2. **Line 119 — Default Agent Types, eject sentence.**
+   Reword to drop eject; keep override + disable (see Design Overview snippet).
+3. **Lines ~226–303 — Commands + Persistent Settings sections.**
+   - Rewrite the **Commands** section (table row `/agents` and the entire interactive-menu code block + bullet list, lines ~228–252) to document `/subagents:settings` and `/subagents:sessions` per the target shape above.
+   - In **Persistent Settings**, replace each `/agents` → Settings reference (lines 277, 281, 283, 301) with `/subagents:settings`, and "the `/agents` menu never writes here" (line 281) with "the `/subagents:settings` command never writes here", and "without ever touching the menu" (line 300) with "without ever touching the command".
+   - Line 303 failure-behavior sentence: change "the `/agents` toast" to "the `/subagents:settings` toast".
+4. **Line 318 — Events table, `subagents:settings_changed` row.**
+   Change the "When" cell from "`/agents` → Settings mutation was applied" to "`/subagents:settings` mutation was applied".
+
+Doc-staleness cross-checks performed (per plan-issue checklist):
+
+- Grepped the README for every removed term (`/agents`, `eject`/`Eject`, `conversation viewer`, `wizard`, `Create new agent`, `interactive menu`, `menu`) — all occurrences are enumerated in the steps above (lines 21, 119, 228, 230, 235, 241–248, 277, 281, 283, 300, 301, 303, 318).
+- Confirmed no other `packages/pi-subagents/docs/` file or `.pi/skills/package-pi-subagents/SKILL.md` references `/agents` as a live command needing update (architecture.md already describes the Phase 19 removal as past tense; the SKILL.md describes `/subagents:settings`/`/subagents:sessions` already).
+- The **UI** widget-render examples and the **Default Agent Types** table are accurate post-Phase-19 and are left unchanged — verify they are not contradicted by the edits.
+
+## Test Impact Analysis
+
+Not applicable — documentation-only change with no test surface.
+There is no executable behavior to cover; correctness is verified by `pnpm run lint` (rumdl markdown rules) and visual review against `src/index.ts`'s registered commands.
+
+## Invariants at risk
+
+None.
+This change touches no code surface a prior phase step refactored; the Phase 19 spine invariants ([#422]–[#425]) are pinned by existing source/observer/event-contract suites and are untouched by a README edit.
+
+## Build Order
+
+This is a `/build-plan` (docs-only) change, executed as a single reviewable commit — no red→green cycles.
+
+1. Edit `packages/pi-subagents/README.md` per all four Module-Level Changes steps in one pass.
+   Apply one-sentence-per-line formatting (markdown-conventions skill) to all rewritten prose.
+   Suggested commit message: `docs(pi-subagents): refresh README for /subagents:settings and /subagents:sessions (#470)`.
+2. Verify: run `pnpm --filter @gotgenes/pi-subagents run lint` (or `pnpm run lint` at root) to confirm rumdl passes, and re-grep the README for `/agents`, `eject`, `wizard`, `conversation viewer` to confirm zero stale references remain.
+   Cross-check the two command descriptions against `src/index.ts` `registerCommand` strings.
+
+## Risks and Mitigations
+
+- **Risk: missing a stale reference.**
+  Mitigation: the grep in Module-Level Changes enumerated every occurrence; the build step re-greps after editing to confirm none survive.
+- **Risk: command description drift from the actual `/help` text.**
+  Mitigation: copy the table descriptions verbatim from the `registerCommand` calls in `src/index.ts`.
+- **Risk: markdown lint failure on the rewritten Commands table or code fences.**
+  Mitigation: follow markdown-conventions (compact table style, fenced-block languages, sequential numbering) and run `pnpm run lint` before committing.
+
+## Open Questions
+
+None.
+The issue is the operator's own, the surface is verified against source, and no follow-up work is named.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#425]: https://github.com/gotgenes/pi-packages/issues/425

package/docs/retro/0441-remove-agent-definition-management-subtree.md

@@ -43,3 +43,55 @@ All checks green: 62 test files / 950 tests, `fallow dead-code` clean, `fallow d
 - `makeMenuManager` was removed whole (not just its `spawnAndWait` relay) because its only post-cut consumer was its own self-test — exactly the right call, consistent with the planning decision.
 - Final file count in `src/`: 57 (was 58 in SKILL.md header; now corrected).
 - Pre-completion reviewer: **PASS** (third dispatch, after two WARN rounds on the stale doc sections).
+
+## Stage: Final Retrospective (2026-06-23T18:30:00Z)
+
+### Session summary
+
+Shipped #441 as the tail of release batch "dissolve-agents": pushed, CI green, closed both #441 and the stacked #442, merged release-please PR #469, and cut `pi-subagents-v18.0.0`.
+The whole arc (plan → build → ship) executed in one session with no rework to the deletion itself — the only friction was doc staleness inherited from #442, caught by the pre-completion reviewer across two WARN rounds.
+
+### Observations
+
+#### What went well
+
+- The fresh-context `pre-completion-reviewer` earned its keep on a deletion task: it caught five stale `architecture.md` sections (a domain Mermaid diagram, a cross-extension diagram label, and three prose passages) that referenced modules deleted in #442, none of which the plan or the implementation agent flagged.
+  Doc staleness is exactly the category a focused deletion misses, and the reviewer is the safety net that held.
+- Batch-tail release mechanics worked exactly as planned: a `refactor(pi-subagents):` tail commit carried no version weight itself, the unreleased `feat(pi-subagents)!:` from #442 (`cb813f2c`) drove the major bump, and `release-please` cut `v18.0.0` cleanly while both issues closed with curated comments.
+
+#### What caused friction (agent side)
+
+1. `missing-context` (cross-session) — `#442`'s retro explicitly deferred a "holistic architecture-doc refresh" to the batch tail (#441), but #441's planning stage never pulled that deferred work into the plan's `Module-Level Changes` doc scope.
+   The `/plan-issue` "Check for prior session context" step reads only the **current** issue's retro (`NNNN` matching the issue number), so a predecessor batch member's deferred work is invisible to it.
+   Impact: three extra doc-fixup commits (`e440d0d1`, `04b13812`, and the `SKILL.md` file-count fix) and three pre-completion reviewer dispatches (two WARN, then PASS) during the build stage.
+2. `wrong-abstraction` (fix scope) — after the first reviewer WARN named three stale sections, the fix addressed exactly those three rather than grepping `architecture.md` exhaustively for every reference to the deleted modules (`conversation-viewer`, `agent-menu`, `/agents`).
+   Impact: the second review round found two more stale sections, forcing another fix → commit → re-review cycle that one exhaustive grep would have collapsed into the first round.
+
+#### What caused friction (user side)
+
+- None substantive.
+  The user's two `Continue.` prompts during the build stage were mechanical resumptions (after an autoformat tool message and a context boundary), not redirections — the work was well-specified by the plan throughout.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the `pre-completion-reviewer` ran on `anthropic/claude-sonnet-4-6` (per its agent frontmatter), an appropriate match for judgment-heavy doc-staleness and design review; no high-cost-model-on-mechanical-work or weak-model-on-judgment mismatch.
+  No other subagents were dispatched.
+- **Unused-tool detection** — friction point 2 was a `grep`/`colgrep` gap: an exhaustive search for the deleted-module names across `architecture.md` after the first WARN would have surfaced all five stale references in one pass instead of two.
+- **Feedback-loop gap analysis** — no gap; verification ran incrementally (baseline `check`/`lint` before edits, then `check`/`test`/`lint`/`fallow dead-code`/`fallow dupes` after each step, then the reviewer), not bunched at the end.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added step 5 to "Check for prior session context": a release-batch tail plan must read earlier batch members' retros for deferred work and fold it into `Module-Level Changes`.
+2. `.pi/skills/pre-completion/SKILL.md` — added a line under "Overall: WARN": when a WARN names stale references to a deleted symbol, grep the file exhaustively for every instance before fixing, to avoid a second WARN round.
+
+### Post-commit follow-up — stale `README.md`
+
+After the retro commit, the user caught that `packages/pi-subagents/README.md` still documents the removed `/agents` command and conversation viewer and omits `/subagents:settings` and `/subagents:sessions` — a published, user-facing miss that shipped in `pi-subagents-v18.0.0`.
+
+- `missing-context` (cross-session, user-caught) — the README was stale from #442's deletions (it documents `/agents`, not the module `agent-menu.ts`) and was never folded into #442's or #441's plan.
+  The pre-completion reviewer's README check keyed on module names, not the command names a README actually documents, so a module-name match missed it.
+  Impact: a user-facing doc defect shipped to npm; tracked as a follow-up in #470 (recommend `/plan-issue`).
+
+3. Filed #470 to rewrite the stale `README.md` (removed `/agents` surface, missing `/subagents:` commands, eject UI gone).
+4. `.pi/prompts/plan-issue.md` — `Module-Level Changes`: when a change adds, removes, or renames a slash command or user-facing feature, grep `packages/<PKG>/README.md` for the command/feature name (the `src/`-symbol grep misses command names).
+5. `.pi/agents/pre-completion-reviewer.md` — broadened the forward-doc README check: when a change removes or renames a slash command or user-facing feature, grep the package `README.md` for the command/feature name, not just module names.

package/docs/retro/0443-consolidate-remaining-test-clone-families.md

@@ -0,0 +1,28 @@
+---
+issue: 443
+issue_title: "pi-subagents: consolidate remaining test clone families"
+---
+
+# Retro: #443 — pi-subagents: consolidate remaining test clone families
+
+## Stage: Planning (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Planned Phase 19 Step 7 (test-clone consolidation) for `pi-subagents`.
+Re-ran `fallow dupes` against current `main` and found the live state diverged from the issue's Phase-18-era snapshot: line numbers shifted after the terminal cut ([#441]/[#442]) and new Phase-19 UI test files added clones the issue never named.
+Wrote `packages/pi-subagents/docs/plans/0443-consolidate-remaining-test-clone-families.md` and committed it.
+
+### Observations
+
+- The issue is the operator's own, but the proposed "extract a shared fixture" list was substantially invalidated by live evidence: several named targets (`resolveSpawnConfig`, `assembleSessionConfig`, `schedule`) are the repeated *system-under-test act*, which the `testing` skill says not to wrap to clear a clone metric.
+- `ask_user` gate settled two decisions: **guardrail-first** (leave act-clones, extract only genuine fixtures) and **full live set** (include the new Phase-19 UI clones, notably the byte-identical `makeNavigable` factory duplicated across `session-navigation.test.ts` and `session-navigator.test.ts`).
+- Eight genuine extraction targets identified; clearing them drops the count from 16 to 8 — below the issue's `≤ 10` target — without wrapping any act.
+  The four primary UI/lifecycle extractions alone reach 10.
+- Six residual families are documented as intentional act-clones in Non-Goals so a future fallow pass reads them as deliberate, not oversight.
+- Convention confirmed: cross-file helpers go in `test/helpers/<name>.ts` (imported via `#test/helpers/<name>`) with a companion `<name>.test.ts`; single-file helpers stay local.
+- Invariants at risk flagged: the `#423` reactive-consumer assertion in `session-navigator.test.ts` must stay in the test body (not absorbed by the `renderCapturedOverlay` helper), and the resume-events emitter must preserve exact usage/compaction payloads.
+- `Release: independent` — ships on its own; no batch coupling.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442

package/docs/retro/0470-refresh-readme-command-surface.md

@@ -0,0 +1,40 @@
+---
+issue: 470
+issue_title: "pi-subagents: README still documents the removed /agents command and omits /subagents:settings and /subagents:sessions"
+---
+
+# Retro: #470 — pi-subagents README still documents the removed /agents command
+
+## Stage: Planning (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Planned a docs-only refresh of `packages/pi-subagents/README.md` to replace the removed `/agents` interactive-menu surface with the live `/subagents:settings` and `/subagents:sessions` commands, drop the deleted Conversation viewer feature bullet, and remove the eject customization story (ADR-0004 Decision C).
+Verified the current command surface against `src/index.ts` `registerCommand` calls and enumerated every stale reference by grep (lines 21, 119, 228–252, 277–303, 318).
+Classified as **ship independently** — not a member of any roadmap step or release batch; the `dissolve-agents` batch already shipped as `pi-subagents-v18.0.0`.
+
+### Observations
+
+- Author is the operator (`gotgenes`), and the issue spells out the stale lines and expected behavior precisely, so the `ask_user` gate was skipped — no design ambiguity.
+- This is a `/build-plan` (docs-only) change: one reviewable commit, no red→green cycles, verified by `pnpm run lint` (rumdl) plus a re-grep for stale terms.
+- Root cause (from the issue itself): the Phase 19 doc-staleness check keyed on module names (`agent-menu.ts`), not the command names a README documents (`/agents`) — the plan-issue README grep checklist now catches this class.
+- Scope deliberately excludes `src/`, tests, `architecture.md`, and the ADRs — all already accurate post-Phase-19.
+  Only the README lagged.
+- `.pi/skills/package-pi-subagents/SKILL.md` needs no update: it is an implementation-architecture reference that does not document slash commands, and its sole `/agents` mention is past-tense Phase 18 historical context (not a live-command reference).
+
+## Stage: Implementation — Build (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Executed the single-step docs plan in one commit: refreshed `packages/pi-subagents/README.md` to the post-Phase-19 command surface.
+Replaced the removed `/agents` interactive-menu surface with `/subagents:settings` and `/subagents:sessions`, dropped the Conversation viewer feature bullet (now a Session transcripts bullet), removed the eject customization story (override + `enabled: false` only), and corrected the `subagents:settings_changed` events-table description.
+No `src/`/`test/`/`.ts` files touched; `pnpm run lint` and `pnpm run check` stayed green throughout.
+
+### Observations
+
+- Command table descriptions were copied verbatim from the `registerCommand` calls in `src/index.ts` so the README matches `/help` output.
+- The post-edit grep for `/agents` still matches lines 22/119/131/132/137 — all legitimate `.pi/agents/<name>.md` file-path references, not the removed command; `eject`/`wizard`/`conversation viewer` return zero matches.
+- Pre-completion reviewer: WARN (non-blocking).
+- Reviewer warnings: one finding — the planning-stage retro observation incorrectly claimed `SKILL.md` "already references the new commands."
+  The conclusion (no skill update needed) was correct, but the justification was wrong.
+  Corrected the planning observation in this same retro commit; `SKILL.md` is an architecture reference that does not document slash commands, so it genuinely needs no update.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "18.0.0",
+  "version": "18.0.1",
   "type": "module",
   "exports": {
     ".": {