@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0463-file-snapshot-source-evicted-agents.md

@@ -1,306 +0,0 @@
----
-issue: 463
-issue_title: "pi-subagents: add file-snapshot source to /subagent-sessions for evicted agents"
----
-
-# File-snapshot source for evicted agents in `/subagent-sessions`
-
-## Release Recommendation
-
-**Release:** ship independently
-
-Architecture roadmap Phase 19 Step 4b ([#463]) carries `Release: independent`.
-This is a new capability the bespoke viewer never had — it gates nothing and is not a Step 5 prerequisite — so it ships on its own once landed.
-
-## Problem Statement
-
-The [#445] native-session-navigation slice sources transcripts live, from `manager.listAgents()` only.
-The manager's cleanup sweep (`SubagentManager.cleanup()`, every 60 s) disposes a completed/stopped/errored record 10 minutes after it finishes — `disposeSession()` frees the heavy in-memory session (its message history included) and the record is deleted from the map.
-The lightweight session JSONL persists on disk at `Subagent.outputFile`, but with no live record the agent is unreachable from `/subagent-sessions`.
-
-This step makes a fully-evicted agent navigable: it adds the file-snapshot `TranscriptSource` branch the #445 seam was designed for, and broadens the picker's candidate set to include evicted agents.
-
-## Goals
-
-- Implement `fileSnapshotSource(outputFile, readFile)` in `src/ui/session-navigation.ts`: `parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages` → a static (no-subscribe, no-streaming) `TranscriptSource`.
-- Broaden the `/subagent-sessions` candidate set to include evicted agents, deduped against live records.
-- Render an evicted agent's transcript read-only from its persisted file when picked; the renderer (`buildTranscriptComponents`) and overlay (`TranscriptOverlay`) are untouched.
-- Inject `readFile` as a parameter so the pure module performs no `fs` calls.
-
-This change is **not** breaking: it is additive (a new source branch and a broadened candidate set); no existing behavior, output shape, or default changes for a tracked agent.
-
-## Non-Goals
-
-- No directory scan of the tasks directory and no surfacing of prior-process orphan session files (see Design Overview → Candidate-set decision).
-- No change to the cleanup sweep's 10-minute eviction policy or to `disposeSession()`.
-- No renderer or overlay changes — `session-navigator.ts`'s `buildTranscriptComponents` / `TranscriptOverlay` / `addMessageComponents` are unchanged (Step 4a, [#462], already brought them to parity).
-- No `switchSession` / `loadEntriesFromFile` (rejected by the Step 1 spike, [#446]).
-- No live re-read or file-watching of the snapshot — a file source is a static snapshot by design.
-
-## Background
-
-Relevant modules:
-
-- `src/ui/session-navigation.ts` — the pure, unit-testable core: `NavigableSubagent` (narrow record view), `NavigationEntry`, `TranscriptSource`, `listNavigableAgents(agents, registry)`, `liveSource(record)`, `buildLabel(record, registry)`.
-  It imports SDK *types* only (`ToolDefinition`) and the lifecycle type `SubagentStatus`.
-- `src/ui/session-navigator.ts` — the SDK/TUI consumer half: `SessionNavigatorHandler` (picker + source selection) and `TranscriptOverlay` (read-only scrollable renderer).
-  The handler already calls `liveSource(entry.record)`; the source is the only seam that varies.
-- `src/lifecycle/subagent-manager.ts` — `listAgents()` (sorted live records), `cleanup()` (the 10-minute sweep), `clearCompleted()` (new-session wipe, called from `handlers/lifecycle.ts` on `session_start` / `session_before_switch`), `removeRecord()` (`disposeSession()` + `agents.delete`).
-- `src/lifecycle/subagent.ts` — `Subagent` exposes `id`, `type`, `description` (readonly), and getters `status`, `startedAt`, `completedAt`, `toolUses`, `outputFile`.
-- `src/index.ts` — registers `subagent-sessions`, calling `sessionNavigator.handle({ ui, agents: manager.listAgents(), registry, cwd })`.
-
-SDK functions (`@earendil-works/pi-coding-agent`): `parseSessionEntries(content): FileEntry[]`, `buildSessionContext(entries: SessionEntry[]): { messages: AgentMessage[]; … }`, and the types `SessionEntry` / `SessionHeader`.
-`FileEntry = SessionHeader | SessionEntry`; only the header has `type: "session"`, so `entries.filter((e): e is SessionEntry => e.type !== "session")` is a sound type guard.
-`SessionMessage` (the navigator's message type) is `SessionContext["messages"][number]` = `AgentMessage`, so `buildSessionContext(...).messages` matches `TranscriptSource.getMessages()` with no cast.
-
-Constraints from AGENTS.md / skills that apply:
-
-- `code-design` SDK-boundary guideline: pure helpers should avoid SDK *runtime* imports.
-  `fileSnapshotSource` calls the SDK runtime functions `parseSessionEntries` / `buildSessionContext` directly (see Design Overview → SDK-runtime decision); there is no `no-restricted-imports` lint rule, and the module already depends on SDK types.
-- `testing`: components used by `session-navigator.ts` need `initTheme(undefined, false)` in `beforeAll` (already present in `session-navigator.test.ts`).
-- `fallow dead-code`: a new export with no caller fails the gate.
-  Producers (`fileSnapshotSource`, `listEvicted`) gain their caller in the integration step within the same push; the pushed tip is dead-code-clean (see Risks).
-
-## Design Overview
-
-### Candidate-set decision — manager-retained descriptors (not a directory scan)
-
-The issue proposes enumerating persisted JSONL files in the tasks directory.
-The persisted child session carries **no** subagent `type` or `description` — those live only on the in-memory `Subagent` record; the file holds only the conversation plus a header (`id`, `timestamp`, `cwd`, `parentSession`).
-A directory scan therefore yields degraded labels (agent type → generic placeholder; curated `description` → a raw first-prompt snippet or filename) and must parse every file on every picker open.
-
-Decision (confirmed with the operator): the manager retains a lightweight **descriptor** at eviction time instead.
-When `cleanup()` disposes a record that has a persisted file, it first copies the record's label fields plus `outputFile` into a separate `evicted` map (no messages — the heavy state is still freed, so memory stays bounded by the number of subagents spawned, not their transcripts).
-The picker's candidate set is `live ∪ evicted`, deduped by id, with identical rich labels for both.
-
-Coverage: this surfaces agents evicted **in the current root session** — which are the cleanup sweep's only targets.
-A fresh `SubagentManager` is created per session and `clearCompleted()` runs on `session_start`, so prior-process subagents are never reloaded into the manager; the only files a directory scan would *additionally* surface are old-session orphans, which are exactly the ones with degraded labels.
-Picking an evicted agent still reads its file to render (the messages are gone from memory regardless) — so `fileSnapshotSource` is required either way; the descriptor only feeds the *label*.
-
-### SDK-runtime decision — call `parseSessionEntries` / `buildSessionContext` directly
-
-`fileSnapshotSource` imports and calls these SDK runtime functions directly rather than injecting them.
-Rationale: they are deterministic parsers of Pi's own session format; the injected `readFile` already provides the unit-test seam (a fake `readFile` returning fixture JSONL fully exercises parse → drop-header → build → messages), so injecting the parsers adds wiring without testability gain.
-There is no `no-restricted-imports` rule, and `session-navigation.ts` already imports SDK types.
-
-### Data shapes
-
-`EvictedSubagent` — the descriptor, owned by lifecycle (the manager constructs it), imported as a type by the UI (the UI already imports `SubagentStatus` from lifecycle):
-
-```typescript
-// src/lifecycle/subagent-manager.ts
-export interface EvictedSubagent {
-  readonly id: string;
-  readonly type: SubagentType;
-  readonly description: string;
-  readonly status: SubagentStatus;
-  readonly startedAt: number;
-  readonly completedAt: number | undefined;
-  readonly toolUses: number;
-  readonly outputFile: string;
-}
-```
-
-`NavigationEntry` changes from `{ record, label }` to a discriminated union so the handler can pick the source by kind:
-
-```typescript
-// src/ui/session-navigation.ts
-export type NavigationEntry =
-  | { readonly kind: "live"; readonly label: string; readonly record: NavigableSubagent }
-  | { readonly kind: "evicted"; readonly label: string; readonly outputFile: string };
-```
-
-`buildLabel` is narrowed to a per-call interface (ISP) that both a `NavigableSubagent` and an `EvictedSubagent` satisfy, and gains an `evicted` marker:
-
-```typescript
-interface LabelFields {
-  readonly type: SubagentType;
-  readonly description: string;
-  readonly status: SubagentStatus;
-  readonly startedAt: number;
-  readonly completedAt: number | undefined;
-  readonly toolUses: number;
-}
-
-function buildLabel(fields: LabelFields, registry: AgentConfigLookup, evicted = false): string {
-  const name = getDisplayName(fields.type, registry);
-  const duration = formatDuration(fields.startedAt, fields.completedAt);
-  const marker = evicted ? " · evicted (snapshot)" : "";
-  return `${name} (${fields.description}) · ${fields.toolUses} tools · ${fields.status} · ${duration}${marker}`;
-}
-```
-
-### `fileSnapshotSource`
-
-```typescript
-export function fileSnapshotSource(
-  outputFile: string,
-  readFile: (path: string) => string,
-): TranscriptSource {
-  const entries = parseSessionEntries(readFile(outputFile));
-  const sessionEntries = entries.filter(
-    (entry): entry is SessionEntry => entry.type !== "session",
-  );
-  const { messages } = buildSessionContext(sessionEntries);
-  return {
-    getMessages: () => messages,
-    subscribe: () => undefined, // static snapshot — no live updates
-    streaming: () => undefined, // never streaming
-    getToolDefinition: () => undefined, // no live tool registry off disk
-  };
-}
-```
-
-### `listNavigableAgents` (broadened) and the handler call site
-
-```typescript
-export function listNavigableAgents(
-  agents: readonly NavigableSubagent[],
-  evicted: readonly EvictedSubagent[],
-  registry: AgentConfigLookup,
-): NavigationEntry[] {
-  const live = agents
-    .filter((record) => record.isSessionReady())
-    .map((record): NavigationEntry => ({ kind: "live", record, label: buildLabel(record, registry) }));
-  const liveIds = new Set(agents.map((record) => record.id));
-  const evictedEntries = evicted
-    .filter((d) => !liveIds.has(d.id))
-    .map((d): NavigationEntry => ({ kind: "evicted", outputFile: d.outputFile, label: buildLabel(d, registry, true) }));
-  return [...live, ...evictedEntries];
-}
-```
-
-Dedup is keyed by `id` (both shapes carry it) rather than `outputFile`: a record leaves `listAgents()` at the same instant its descriptor is captured, so the sets cannot overlap; the filter is defensive.
-Order is live-then-evicted, which is already recency-ordered (evicted agents completed > 10 min ago).
-
-Handler consumer sketch (Tell-Don't-Ask: the entry tells the handler its kind; the handler asks the right source constructor — no reach-through into the record's internals):
-
-```typescript
-const entry = entries.find((candidate) => candidate.label === choice);
-if (!entry) return;
-let source: TranscriptSource;
-try {
-  source = entry.kind === "live" ? liveSource(entry.record) : fileSnapshotSource(entry.outputFile, readFile);
-} catch {
-  ui.notify("Could not read the session transcript file.", "error");
-  return;
-}
-// …unchanged: getMarkdownTheme(), ui.custom(new TranscriptOverlay({ source, … }))
-```
-
-### Manager retention sketch
-
-```typescript
-private readonly evicted = new Map<string, EvictedSubagent>();
-
-private cleanup() {
-  const cutoff = Date.now() - 10 * 60_000;
-  for (const [id, record] of this.agents) {
-    if (record.status === "running" || record.status === "queued") continue;
-    if ((record.completedAt ?? 0) >= cutoff) continue;
-    if (record.outputFile) this.evicted.set(id, toEvictedSubagent(record));
-    this.removeRecord(id, record);
-  }
-}
-
-listEvicted(): EvictedSubagent[] {
-  return [...this.evicted.values()].sort((a, b) => b.startedAt - a.startedAt);
-}
-```
-
-`clearCompleted()` and `dispose()` also `this.evicted.clear()` — descriptors belong to the session that evicted them, so a new session starts empty.
-`toEvictedSubagent(record)` copies the eight fields; it is a private helper (or a free function in the module) and reads `record.outputFile` only after the `if (record.outputFile)` guard, so the `outputFile` field is always a defined `string`.
-
-### Edge cases
-
-- **`outputFile` undefined at eviction** (headless / never-persisted session) → no descriptor captured; nothing to navigate.
-- **File deleted/unreadable after eviction** → `fileSnapshotSource`'s eager read throws; the handler's `try/catch` notifies and returns without opening the overlay.
-- **Empty or header-only JSONL** → `buildSessionContext` returns `messages: []`; the overlay renders an empty transcript (no crash).
-- **No navigable sessions at all** (no live, no evicted) → existing `ui.notify("No subagent sessions to view.", "info")` path, unchanged.
-
-## Module-Level Changes
-
-- `src/lifecycle/subagent-manager.ts` — add the `EvictedSubagent` interface (exported), the `evicted` map field, descriptor capture in `cleanup()`, `evicted.clear()` in `clearCompleted()` and `dispose()`, the `listEvicted()` method, and the `toEvictedSubagent` helper.
-  Import `SubagentType` (already in `#src/types`) and `SubagentStatus` (`#src/lifecycle/subagent-state`) for the interface.
-- `src/ui/session-navigation.ts` — add `fileSnapshotSource`; import `EvictedSubagent` (type), and the SDK runtime `parseSessionEntries` / `buildSessionContext` plus the `SessionEntry` type; change `NavigationEntry` to the discriminated union; broaden `listNavigableAgents` to `(agents, evicted, registry)`; narrow `buildLabel` to `LabelFields` + `evicted` flag.
-- `src/ui/session-navigator.ts` — `SessionNavigatorParams` gains `evicted: readonly EvictedSubagent[]` and `readFile: (path: string) => string`; the handler selects the source by `entry.kind` inside a `try/catch`.
-  No change to `TranscriptOverlay`, `buildTranscriptComponents`, `addMessageComponents`, or `addUserComponents`.
-- `src/index.ts` — add `import { readFileSync } from "node:fs"`; the `subagent-sessions` handler passes `evicted: manager.listEvicted()` and `readFile: (path) => readFileSync(path, "utf8")`.
-- `docs/architecture/architecture.md` — mark Step 4b ([#463]) **Landed** with a note recording the descriptor-vs-scan decision and that ADR-0004 Addendum 2's dual-source design is now realized; flip the `S4b` node label in the step-dependency Mermaid diagram to ✅.
-- `docs/decisions/0004-reconsider-ui-direction.md` — optional one-line note under Addendum 2 that Step 4b chose manager-retained descriptors over a directory scan (the addendum's "evicted/untracked" wording said file snapshot for *rendering*, which still holds; only the *candidate-set* mechanism is being pinned down).
-
-No SKILL update: the package SKILL's UI section references no session-navigation internals and the file/domain counts are unchanged (no new module — `fileSnapshotSource` joins the existing `session-navigation.ts`).
-The architecture LOC/complexity tables are explicit end-of-phase snapshots, not per-file inventories, so a ~30-LOC addition does not update them.
-
-## Test Impact Analysis
-
-1. **New unit tests enabled by this change:**
-   - `fileSnapshotSource` (pure, in `session-navigation.test.ts`): fixture JSONL via a fake `readFile` → assert `getMessages()` equals the parsed messages, the `SessionHeader` is dropped, and `subscribe()` / `streaming()` / `getToolDefinition()` return `undefined`.
-   - `listNavigableAgents` with evicted descriptors: evicted entries appear with the `· evicted (snapshot)` marker; an evicted descriptor whose id matches a live record is deduped out.
-   - `SubagentManager.listEvicted()` (in `subagent-manager.test.ts`): after advancing fake timers past the cutoff, a completed agent with an `outputFile` produces a descriptor; one without an `outputFile` does not; `clearCompleted()` empties the set.
-   - `SessionNavigatorHandler` evicted path (in `session-navigator.test.ts`): picking an evicted label opens an overlay sourced from `readFile`; a throwing `readFile` notifies and skips the overlay.
-2. **Tests that become redundant:** none — the live-source tests still exercise the tracked-agent branch.
-3. **Tests that must stay as-is:** the existing `liveSource`, `listNavigableAgents` (live-only), `TranscriptOverlay`, and live-source handler tests — they pin the tracked-agent behavior this change must not regress.
-
-## Invariants at risk
-
-Step 4 (#445) and Step 4a (#462) established invariants on the navigation surface; this step must preserve them:
-
-- **Handler is a reactive consumer with no inbound call into the core** (Invariant #423/#445).
-  Pinned by the existing `session-navigator.test.ts` assertion `expect(record.getToolDefinition).not.toHaveBeenCalled()` in the live-source handler test.
-  The evicted path reads only `entry.outputFile` (a string) + the injected `readFile`; it makes no inbound call into a record.
-- **Read-only, non-interactive overlay** (#445/#446).
-  The file source returns `subscribe: () => undefined` and `streaming: () => undefined`; the overlay's existing read-only behavior is unchanged.
-  Pinned by the existing overlay tests.
-- **Renderer parity via Pi per-entry components** (#462).
-  The renderer is untouched; both sources still yield `SessionMessage[]` into the same `buildTranscriptComponents`.
-  Pinned by the existing `TranscriptOverlay` render tests.
-
-No new test is needed for these — existing tests already pin them; the integration step keeps them green.
-
-## TDD Order
-
-1. **`fileSnapshotSource` (pure, additive).**
-   Surface: `test/ui/session-navigation.test.ts`.
-   Red: a `describe("fileSnapshotSource")` with a fake `readFile` returning fixture JSONL (a `session` header line + a couple of `message` entries) — assert messages parsed, header dropped, and the three static-source methods return `undefined`.
-   Green: implement `fileSnapshotSource` and the SDK runtime imports.
-   Commit: `test(pi-subagents): cover file-snapshot transcript source` then `feat(pi-subagents): add file-snapshot transcript source` (or a single `feat` commit with test + impl).
-2. **Manager evicted-descriptor retention (additive).**
-   Surface: `test/lifecycle/subagent-manager.test.ts`.
-   Red: with fake timers, advance past the 10-minute cutoff and assert `listEvicted()` returns a descriptor for a completed agent with an `outputFile`, none for one without, and an empty set after `clearCompleted()`.
-   Green: add `EvictedSubagent`, the `evicted` map, capture in `cleanup()`, `clear()` in `clearCompleted()`/`dispose()`, `listEvicted()`, and `toEvictedSubagent`.
-   Run `pnpm run check` after this commit (new exported interface).
-   Commit: `feat(pi-subagents): retain evicted-agent descriptors in the manager`.
-3. **Integrate: broaden the candidate set and dual-source the handler (breaking the `NavigationEntry` shape).**
-   This step changes `NavigationEntry` and `listNavigableAgents`'s signature, so the handler, `index.ts` call site, and both UI test files break and are updated together.
-   Surfaces: `src/ui/session-navigation.ts`, `src/ui/session-navigator.ts`, `src/index.ts`, `test/ui/session-navigation.test.ts`, `test/ui/session-navigator.test.ts`.
-   Red: update `listNavigableAgents` tests to the union shape and add the evicted-entry (marker + dedup) cases; add the handler evicted-path tests (file source + throwing-`readFile` notify).
-   Green: change `NavigationEntry` to the union, broaden `listNavigableAgents`, narrow `buildLabel`, add `evicted` + `readFile` to `SessionNavigatorParams`, switch the handler source by kind inside `try/catch`, and wire `manager.listEvicted()` + `readFileSync` in `index.ts`.
-   Run `pnpm run check` (shared interface change with a single non-test call site).
-   Commit: `feat(pi-subagents): source evicted-agent transcripts from disk in /subagent-sessions`.
-4. **Docs.**
-   Update `docs/architecture/architecture.md` Step 4b to Landed (descriptor decision + dual-source realized) and the `S4b` diagram node to ✅; add the optional Addendum 2 note in `docs/decisions/0004-reconsider-ui-direction.md`.
-   Commit: `docs(pi-subagents): mark Phase 19 Step 4b landed (#463)`.
-
-## Risks and Mitigations
-
-- **Transient dead code between steps 1–2 and 3.**
-  `fileSnapshotSource` and `listEvicted()` have no caller until step 3.
-  CI / pre-completion `fallow dead-code` runs on the pushed tip, which is clean once step 3 lands; all steps ship in one push.
-  Mitigation: do not run `/ship-issue` before step 3 is committed.
-- **`buildSessionContext` / `parseSessionEntries` behavior on malformed JSONL.**
-  Mitigation: the handler `try/catch` covers a throwing read/parse; a TDD fixture exercises a valid header-plus-messages file, and an empty-messages case confirms a graceful empty render.
-- **Memory: the `evicted` map grows over a long session.**
-  Each descriptor is eight scalar fields (no messages), bounded by subagents spawned; the heavy session objects are still disposed.
-  `clearCompleted()` resets it per session.
-- **Divergence from the issue's "enumerate persisted JSONL files" wording.**
-  Documented and operator-confirmed (descriptors over scan, for rich labels and bounded IO); the architecture/ADR notes record the rationale so the file-scan option is not silently lost.
-
-## Open Questions
-
-None — the candidate-set strategy and the evicted-entry marker were resolved with the operator during planning.
-
-[#445]: https://github.com/gotgenes/pi-packages/issues/445
-[#446]: https://github.com/gotgenes/pi-packages/issues/446
-[#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

@@ -1,159 +0,0 @@
----
-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/0048-implement-subagents-api.md

@@ -1,44 +0,0 @@
----
-issue: 48
-issue_title: "feat: implement and publish SubagentsService at extension init"
----
-
-# Retro: #48 — implement and publish SubagentsService at extension init
-
-## Final Retrospective (2026-05-17T15:30:00Z)
-
-### Session summary
-
-Planned and implemented a typed `SubagentsService` interface with `Symbol.for()` accessor functions, an adapter wrapping `AgentManager` with model resolution and record serialization, and wired it into the extension init.
-Released as `@gotgenes/pi-subagents@4.0.0` (breaking: old untyped global removed).
-The plan was revised mid-session to align naming with `pi-permission-system`'s established conventions after the user flagged the discrepancy.
-
-### Observations
-
-#### What went well
-
-- TDD execution was clean: 8 steps, zero rework, all 33 new tests green on first pass.
-- The adapter design was well-scoped — `index.ts` wiring was +16/−12 lines, and the narrow `AgentManagerLike` interface made test mocks trivial.
-- The allowlist serialization pattern (`toSubagentRecord`) prevents future leaks of non-serializable fields by default.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The initial plan adopted the issue body's naming verbatim (`SubagentsAPI`, `api.ts`, `pi:service:subagents`, `(globalThis as any)`) without checking `pi-permission-system` for the established convention (`SubagentsService`, `service.ts`, `@gotgenes/<pkg>:service`, `Record<symbol, unknown>`).
-  The user had to explicitly ask "Does this structure follow the pattern set forth by pi-permission-system?"
-  Impact: full plan rewrite (replaced entire file), issue title update, issue body update — ~15 minutes of rework across 3 user turns.
-  This was **user-caught**.
-
-- `missing-context` — Same pattern as the #49 retro: following the issue spec literally without checking the codebase.
-  The architecture doc also used the stale naming, reinforcing the wrong choice.
-  Root cause: the "Gather context" step in `/plan-issue` didn't include a cross-package convention check.
-
-#### What caused friction (user side)
-
-- The user had to perform mechanical oversight ("Does this follow the pi-permission-system pattern?") that the planner should have caught independently.
-  If the `/plan-issue` prompt included a step to grep sibling packages for established API patterns, this would have been a design decision surfaced during planning rather than a correction after the fact.
-
-### Changes made
-
-1. Created `packages/pi-subagents/docs/retro/0048-implement-subagents-api.md` (this file).
-2. Updated `.pi/skills/package-pi-subagents/SKILL.md` — changed `SubagentsAPI` → `SubagentsService` in Implementation Priorities; added `service.ts` and `service-adapter.ts` to module dependency graph and descriptions.
-3. Updated `.pi/prompts/plan-issue.md` — added step 7 to Gather context: check sibling packages for established API patterns before adopting issue body naming.

package/docs/retro/0049-remove-group-join-output-file-rpc.md

@@ -1,49 +0,0 @@
----
-issue: 49
-issue_title: "feat: remove group-join, output-file, and ad-hoc RPC"
----
-
-# Retro: #49 — remove group-join, output-file, and ad-hoc RPC
-
-## Final Retrospective (2026-05-17T15:15:00Z)
-
-### Session summary
-
-Planned and implemented the removal of group-join and ad-hoc RPC from `pi-subagents`, releasing v3.0.0.
-The original scope included `output-file.ts` removal, but the user intervened to retain it for post-hoc debugging value.
-A new issue (#61) was filed to port the output-file format to Pi's official JSONL session schema.
-
-### Observations
-
-#### What went well
-
-- User intervention produced a materially better outcome — retaining debugging transcripts and identifying a format conformance gap that became #61.
-- TDD execution was clean: 6 steps, zero rework, all tests green on first pass after each step.
-- The `feat!:` → release-please → v3.0.0 pipeline worked smoothly end-to-end.
-
-#### What caused friction (agent side)
-
-- `missing-context` — Included `output-file.ts` removal in the initial plan without questioning its debugging value, despite AGENTS.md's rule "Ask before removing functionality or changing defaults."
-  The issue body explicitly listed it for removal so I followed the spec literally.
-  Impact: required plan revision (amend commit), scope-narrowing comment on issue, and filing #61 — roughly 10 minutes of rework, but produced a better design.
-
-- `missing-context` — When asked whether output-file adheres to Pi's session format, searched the web (`web_search` for "Claude Code session JSONL format") instead of checking the local `~/development/pi/pi` monorepo.
-  The user had to explicitly say "~/development/pi/pi has the code for Pi's JSONL format."
-  Impact: one extra round-trip and less authoritative initial answer (Claude Code's format vs Pi's `SessionManager`).
-  Self-identified after user redirect.
-
-- `instruction-violation` (self-identified) — Shell-escaped the `gh issue comment` body incorrectly; backtick-wrapped `src/output-file.ts` was interpreted by bash.
-  Caught immediately via `gh issue view` and fixed with `--edit-last`.
-  Impact: trivial — one extra command.
-
-#### What caused friction (user side)
-
-- The issue body listed output-file for removal without noting its debugging value.
-  The user's "How confident are we in getting rid of the logging system?"
-  intervention was the correction.
-  If the issue had marked output-file removal as "tentative pending debugging value assessment," the plan would have surfaced it as a design decision from the start.
-  Minor — the discussion was quick and productive.
-
-### Changes made
-
-1. Created `packages/pi-subagents/docs/retro/0049-remove-group-join-output-file-rpc.md` (this file).

package/docs/retro/0051-update-adr-0001-hard-fork.md

@@ -1,39 +0,0 @@
----
-issue: 51
-issue_title: "docs: update ADR 0001 to reflect hard-fork decision"
----
-
-# Retro: #51 — docs: update ADR-0001 to reflect hard-fork decision
-
-## Final Retrospective (2026-05-16)
-
-### Session summary
-
-Updated [ADR-0001] to reflect the hard-fork decision documented in `docs/architecture/architecture.md`.
-The change was planned, implemented, shipped, and released as `pi-subagents-v1.0.2` in a single clean pass with no rework.
-
-### Observations
-
-#### What went well
-
-- The entire plan→build→ship pipeline completed with zero corrections, zero CI failures, and zero user interventions.
-- Parallel context gathering (issue body, `AGENTS.md`, ADR file, architecture doc, two skill files) in one tool call made the planning phase efficient.
-- The 4-edit approach (`Edit` with a single call containing four `edits[]` entries) was well-matched to the task — each edit was small, unique, and non-overlapping.
-
-#### What caused friction (agent side)
-
-- No friction observed.
-  The task was unambiguous and the tooling well-suited.
-
-#### What caused friction (user side)
-
-- No friction observed.
-  The session required no user input beyond invoking the three slash commands.
-
-### Follow-ups identified
-
-- The `package-pi-subagents` skill (`.pi/skills/package-pi-subagents/SKILL.md`) still frames the fork as "a friendly fork… carrying a small number of patches" with priorities like "stays as close to upstream as possible."
-  This framing is now stale given the hard-fork commitment.
-  A separate issue should update the skill to reflect the architecture document's posture.
-
-[ADR-0001]: ../decisions/0001-deferred-patches.md

package/docs/retro/0053-extract-model-resolution-from-execute.md

@@ -1,40 +0,0 @@
----
-issue: 53
-issue_title: "refactor: extract model resolution from Agent.execute"
----
-
-# Retro: #53 — extract model resolution from Agent.execute
-
-## Final Retrospective (2026-05-17T21:00:00Z)
-
-### Session summary
-
-Planned and executed the extraction of inline model-resolution logic from `Agent.execute` in `index.ts` into a new `resolveInvocationModel()` function in `model-resolver.ts`.
-Released as `pi-subagents-v4.1.0` with +10 new unit tests and no behavior change.
-Also fixed a pre-existing `rumdl` glob-quoting bug in `package.json` discovered during the lint step.
-
-### Observations
-
-#### What went well
-
-- Pre-existing lint bug surfaced and fixed: the `rumdl check '*.md' 'docs/**/*.md'` command in `package.json` used single-quoted globs that prevented shell expansion.
-  Verified as pre-existing (reproduced on prior commit via `git stash`), cleanly isolated into its own `fix:` commit.
-  This was a genuine find — the lint had been silently broken.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In step 6 (refactoring `index.ts`), replaced the `resolveModel` import with `resolveInvocationModel` without first checking whether `resolveModel` was still used elsewhere in the file.
-  Two other call sites (`createSubagentsService` at line 386 and `getModelLabel` at line 1043) still needed it.
-  The plan explicitly listed `getModelLabel` as a non-goal that continues using `resolveModel`, so the information was available.
-  Caught immediately via `grep` after the edit and fixed in the same commit.
-  Impact: one extra edit + grep cycle, no rework.
-
-- `missing-context` — The plan's type definitions specified `model: unknown` for `ModelResolutionResult`, but downstream code in `index.ts` accesses `.id` and `.name` on the model and passes it where `Model<any>` is expected.
-  The plan's risk section flagged this ("reducing but not eliminating the `any`"), yet the implementation went with `unknown` first, requiring a correction after `pnpm run check` failed with 4 type errors.
-  Changed to `model: any` to match the existing `resolveModel` return type.
-  Impact: one extra edit cycle within the same commit, no rework.
-
-#### What caused friction (user side)
-
-- None observed.
-  The issue was well-scoped with clear acceptance criteria, making planning and execution straightforward.