@gotgenes/pi-subagents 18.0.0 → 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/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.

package/docs/retro/0054-decompose-index-into-modules.md

@@ -1,53 +0,0 @@
----
-issue: 54
-issue_title: "refactor: decompose src/index.ts into tool + menu modules"
----
-
-# Retro: #54 — decompose index.ts into tool + menu modules
-
-## Final Retrospective (2026-05-18T02:20:00Z)
-
-### Session summary
-
-Decomposed `src/index.ts` from 1,619 lines to 265 lines across 8 commits.
-Extracted 7 new modules (`tools/helpers.ts`, `renderer.ts`, `notification.ts`, `tools/agent-tool.ts`, `tools/get-result-tool.ts`, `tools/steer-tool.ts`, `ui/agent-menu.ts`) with 66 new tests (379 → 445 total).
-Released as `pi-subagents-v4.1.1`.
-Filed follow-up #66 (replace `as any` casts with proper SDK types) and #67 (flaky `pi-autoformat` acceptance test).
-
-### Observations
-
-#### What went well
-
-- Leaf-first extraction order worked cleanly — helpers, then renderer, then notification, then tools, then menu.
-  Each step left the repo green with no cascading breakage.
-- The `createNotificationSystem` factory pattern with arrow-closure capture of `widget` (assigned after `AgentManager` construction) preserved the existing deferred-reference semantics without restructuring initialization order.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Applied the code-style skill's "keep Pi SDK imports out of business-logic modules" rule to tool/menu modules, which are SDK consumers, not business logic.
-  Used `unknown` for `ExtensionContext`, `AgentSession`, `ModelRegistry` in factory dep interfaces, requiring 9 `as any` casts in `index.ts`.
-  User caught this post-ship.
-  Impact: filed #66 as a follow-up cleanup; the casts are cosmetic (no runtime effect) but degrade type safety.
-  Fixed the code-style skill to clarify the boundary. (user-caught)
-
-- `missing-context` — Four test files (`notification.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts`, `agent-tool.test.ts`) omitted `compactionCount: 0` from `AgentRecord` factories.
-  Caught at the final `pnpm run check` step, not during test writing.
-  The testing skill already says "grep for ALL test files that construct a compatible mock."
-  Impact: one extra fix cycle delegated to a subagent, no rework beyond that step. (self-identified)
-
-- `other` — `Edit` tool failed 3 times matching the UTF-8 middle dot (`·`, U+00B7) in the steer tool's `stateParts.join(" · ")` line.
-  The third attempt produced a partial match that left the file in a broken state (dangling orphan code after the replacement anchor).
-  Required `git restore` and a fallback to `python3` line-range replacement.
-  The same `python3` approach for the menu extraction lost the closing `}` of the default export function.
-  Impact: ~5 minutes of rework across the two extraction steps, plus one `git restore`.
-
-#### What caused friction (user side)
-
-- The `as any` casts could have been caught earlier if the user had flagged the `unknown` types during the planning phase.
-  However, the plan didn't prescribe exact interface types — that was an implementation decision.
-  The user's post-ship review ("Why did we have to cast `as any`?
-  Take a look at `packages/pi-permission-system/` as a model") was an efficient redirect that immediately scoped the investigation.
-
-### Changes made
-
-1. `.pi/skills/code-style/SKILL.md` — Clarified SDK-boundary guidance: tool definitions, event handlers, and command handlers may import SDK types directly; the restriction targets pure helpers and domain modules.

package/docs/retro/0057-structured-debug-logging.md

@@ -1,77 +0,0 @@
----
-issue: 57
-issue_title: "feat: structured debug logging for silenced catch blocks"
----
-
-# Retro: #57 — structured debug logging for silenced catch blocks
-
-## Final Retrospective (2026-05-19T10:30:00Z)
-
-### Session summary
-
-Added `src/debug.ts` with `debugLog` and `isDebug()`, then threaded `debugLog` into ~20 silent `catch` blocks across 9 files.
-All 7 TDD cycles went green on the first pass with no rework.
-Shipped as `pi-subagents-v5.1.0`, then followed up with a `refactor:` commit converting `DEBUG` (module-level constant) to `isDebug()` (function getter) during the retro.
-
-### Observations
-
-#### What went well
-
-- The plan's "Non-Goals" section correctly excluded `usage.ts` and `settings.ts` before implementation started, and a post-TDD `grep -rn 'catch\s*{'` confirmed only those two in-scope-excluded files remained.
-  Closing the loop with a verification query is worth repeating.
-- The scope of the change was so well-defined (the issue listed exact file names) that no `ask_user` call was needed during planning.
-
-#### What caused friction (agent side)
-
-- `missing-context` — When loading the `ask-user` skill I guessed `.pi/skills/ask-user/SKILL.md` before reading the actual `<location>` tag in `AGENTS.md`, triggering an ENOENT error and a follow-up `find` call.
-  Impact: 2 extra tool calls, no rework. (self-identified)
-
-- `other` — The plan's TDD Order step 1 stated *"the test skill documents this pattern"* for `vi.resetModules()` + dynamic import when testing module-level env constants — but the testing skill does not have that entry.
-  The aspiration was recorded rather than verified.
-  During the retro, the user's question ("should that be a function getter instead?") led to a better outcome: replace the module-level constant with `isDebug()` so `vi.stubEnv()` alone works, consistent with how every other `process.env` read in this codebase is structured.
-  Impact: one retro-phase `refactor:` commit; the approach shipped in `v5.1.0` was technically correct but unnecessarily complex to test.
-
-#### What caused friction (user side)
-
-- The initial issue proposal chose the module-level-constant pattern (common in Node.js tooling like the `debug` package).
-  A note in the issue or plan about preferring function-based env reads for testability would have caught this at design time rather than post-ship.
-  That said, the retro question was efficient — a single targeted redirect resolved it cleanly.
-
-### Changes made
-
-1. `packages/pi-subagents/src/debug.ts` — replaced `export const DEBUG` with `export function isDebug()`.
-2. `packages/pi-subagents/test/debug.test.ts` — simplified to static import + `vi.stubEnv()` only; removed all `vi.resetModules()` + dynamic `import()` calls.
-3. `.pi/skills/testing/SKILL.md` — added bullet: prefer reading `process.env` inside functions; `vi.stubEnv()` alone is insufficient for module-level constants.
-
-## Follow-up Retrospective (2026-05-19T11:15:00Z)
-
-### Session summary
-
-The user asked how many `process.*` reads exist in `pi-subagents`.
-Audit found 9 sites: 4 acceptable (wiring layer, detection functions, injectable defaults), 2 genuine injection gaps, and 1 mild case.
-Filed #76 (`AgentManager.dispose()` reads `process.cwd()` without a stored `cwd`) and #77 (`createAgentsMenuHandler` hardcodes `process.cwd()` when `AgentMenuDeps` already injects the personal-side equivalent).
-
-### Observations
-
-#### What went well
-
-- The `isDebug()` refactor naturally led the user to ask a broader design question about `process.*` access patterns, producing two well-scoped follow-up issues without manual triage.
-- The audit categorization (genuinely problematic vs. acceptable) was clean — presenting a table with verdicts per site let the user decide scope without re-reading source.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — The original plan accepted the module-level `DEBUG` constant without checking how the rest of the codebase reads `process.env`.
-  The code-style skill said "keep IO at the edges" but didn't name `process.*` specifically, so the rule wasn't applied.
-  Impact: one post-ship `refactor:` commit to replace `DEBUG` with `isDebug()`; the pattern was technically correct but inconsistent with codebase conventions. (user-caught)
-
-#### What caused friction (user side)
-
-- Nothing notable.
-  The user's two redirecting questions ("should that be a function?"
-  and "how many places access `process.*`?") were well-timed interventions that broadened scope productively.
-
-### Changes made
-
-1. `.pi/skills/code-style/SKILL.md` — added bullet: do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions; accept the value as a parameter.
-2. Filed #76 — inject `cwd` into `AgentManager` constructor.
-3. Filed #77 — add `projectAgentsDir` to `AgentMenuDeps`.