@gotgenes/pi-subagents 6.0.0 → 6.1.0

package/docs/plans/0098-extract-agent-record-state-machine.md

@@ -0,0 +1,435 @@
+---
+issue: 98
+issue_title: "Extract AgentRecord state machine from scattered status transitions"
+---
+
+# Extract AgentRecord state machine
+
+## Problem Statement
+
+`AgentRecord` status transitions are scattered across 6 locations in `agent-manager.ts`: `startAgent()` `.then()`, `startAgent()` `.catch()`, `resume()`, `abort()`, `abortAll()`, and `drainQueue()` catch.
+Each site sets `record.status` plus associated fields (`completedAt`, `result`, `error`) in ad-hoc combinations, with repeated guards like `if (record.status !== "stopped")`.
+
+There are 15 direct `record.status = ...` writes and 17 associated field writes (`result`, `error`, `completedAt`, `startedAt`) — ~32 scattered mutation sites total.
+`startAgent()` is ~130 lines partly because it manages these transitions inline.
+
+## Goals
+
+- Convert `AgentRecord` from a plain interface to a class that owns and encapsulates its transition state.
+- Extract status-transition methods that centralize the "don't overwrite stopped" guard.
+- Reduce scattered field writes in `agent-manager.ts` to method calls.
+- Encapsulate transition fields (`status`, `result`, `error`, `startedAt`, `completedAt`) behind private backing fields with getters — external code can read but not write.
+- Use lift-and-shift to migrate incrementally: introduce the class alongside the interface, migrate construction sites, switch the re-export, replace writes, then encapsulate.
+
+## Non-Goals
+
+- Parent snapshot extraction (architecture.md Step 2) — separate issue.
+- Session-event observation / callback threading removal (architecture.md Step 3) — separate issue.
+- Stat accumulation methods (`toolUses++`, `addUsage()`, `compactionCount++`) — these are running counters, not status transitions.
+  They could become methods in a follow-up but are out of scope here.
+- Encapsulating non-transition field writes (`session`, `outputFile`, `worktree`, `worktreeResult`, `promise`, `toolCallId`, `resultConsumed`, `pendingSteers`) — these are data capture, not status transitions.
+
+## Prerequisites
+
+- Issue #102 (shared test record factory) — shipped.
+  All 8 test files construct `AgentRecord` objects through `createTestRecord()` in `test/helpers/make-record.ts`.
+  Converting the interface to a class requires updating only this one factory (plus `agent-manager.ts` construction).
+
+## Background
+
+### Relevant modules
+
+| Module                        | Role                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `src/types.ts`                | Defines `AgentRecord` interface — 20+ consumers read from it                   |
+| `src/agent-manager.ts`        | Only file that writes status-transition fields                                 |
+| `src/service.ts`              | Defines `SubagentRecord` (serializable snapshot) — unchanged                   |
+| `src/service-adapter.ts`      | Converts `AgentRecord` → `SubagentRecord` via `toSubagentRecord()` — unchanged |
+| `test/helpers/make-record.ts` | Shared test factory — single construction site for all tests (#102)            |
+
+### External writes to `AgentRecord` (not status transitions)
+
+Several files outside `agent-manager.ts` write non-transition fields:
+
+- `tools/get-result-tool.ts` — `record.resultConsumed = true` (2 sites)
+- `tools/steer-tool.ts` / `service-adapter.ts` — `record.pendingSteers` (push messages)
+- `tools/agent-tool.ts` — `record.toolCallId = toolCallId`
+
+These are data-capture writes, not status transitions, and remain public fields.
+
+### Code-style constraints
+
+The code-style skill's "output arguments" rule applies directly: "If a function sets a field on a received object, it is doing work that belongs inside the owning object.
+Encapsulate the mutation behind a method."
+The "scattered resets" rule also applies: "When the same set of fields is reset to the same values in multiple places, extract a single method."
+
+## Design Overview
+
+### `AgentRecord` becomes a class
+
+`AgentRecord` moves from an interface in `types.ts` to a class in a new `src/agent-record.ts` module.
+`types.ts` re-exports the class so existing `import type { AgentRecord } from "./types.js"` across the codebase continues to work with no import-path changes.
+
+The class encapsulates the 5 transition fields behind private backing fields with getters.
+All other fields remain public (identity fields are `readonly`; non-transition mutable fields stay public).
+
+```typescript
+export type AgentRecordStatus =
+  | "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+export class AgentRecord {
+  // Identity — readonly, set once at construction
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly invocation?: AgentInvocation;
+
+  // Transition state — private backing fields, public getters
+  private _status: AgentRecordStatus;
+  get status(): AgentRecordStatus { return this._status; }
+
+  private _result?: string;
+  get result(): string | undefined { return this._result; }
+
+  private _error?: string;
+  get error(): string | undefined { return this._error; }
+
+  private _startedAt: number;
+  get startedAt(): number { return this._startedAt; }
+
+  private _completedAt?: number;
+  get completedAt(): number | undefined { return this._completedAt; }
+
+  // Non-transition mutable state — public fields
+  toolUses: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  session?: AgentSession;
+  abortController?: AbortController;
+  promise?: Promise<string>;
+  resultConsumed?: boolean;
+  pendingSteers?: string[];
+  worktree?: { path: string; branch: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+  toolCallId?: string;
+  outputFile?: string;
+
+  constructor(init: AgentRecordInit) { /* ... */ }
+
+  // Transition methods — see below
+}
+```
+
+### Constructor and `AgentRecordInit`
+
+The constructor accepts a wide init bag that covers all fields.
+Required fields: `id`, `type`, `description`.
+All others are optional with sensible defaults (`status` defaults to `"queued"`, `toolUses` to 0, etc.).
+
+This wide init bag serves two purposes:
+
+1. Production use (`agent-manager.ts`): passes the 7 fields it needs at spawn time.
+2. Test use (`createTestRecord`): sets arbitrary state (e.g., `status: "completed"`, `result: "done"`) without going through transition methods.
+
+```typescript
+export interface AgentRecordInit {
+  id: string;
+  type: SubagentType;
+  description: string;
+  status?: AgentRecordStatus;
+  startedAt?: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+  toolUses?: number;
+  lifetimeUsage?: LifetimeUsage;
+  compactionCount?: number;
+  abortController?: AbortController;
+  invocation?: AgentInvocation;
+  session?: AgentSession;
+  promise?: Promise<string>;
+  resultConsumed?: boolean;
+  pendingSteers?: string[];
+  worktree?: { path: string; branch: string };
+  worktreeResult?: { hasChanges: boolean; branch?: string };
+  toolCallId?: string;
+  outputFile?: string;
+}
+```
+
+### Transition methods
+
+7 methods covering all 6 transition sites plus the resume-reset:
+
+#### `markRunning(startedAt: number): void`
+
+Sets `status = "running"` and `startedAt`.
+Called in `startAgent()` when transitioning from queued to running.
+
+#### `markCompleted(result: string, completedAt?: number): void`
+
+Always sets `result` and `completedAt` (via `??=`).
+Only changes `status` to `"completed"` if not already `"stopped"`.
+Called in the `.then()` success path and in `resume()` try block.
+
+#### `markAborted(result: string, completedAt?: number): void`
+
+Same guard as `markCompleted` — preserves stopped status.
+Sets `status = "aborted"`.
+Called in `.then()` when runner returns `aborted: true`.
+
+#### `markSteered(result: string, completedAt?: number): void`
+
+Same guard as `markCompleted` — preserves stopped status.
+Sets `status = "steered"`.
+Called in `.then()` when runner returns `steered: true`.
+
+#### `markError(error: unknown, completedAt?: number): void`
+
+Always sets `error` (formatted: `Error` → `.message`, otherwise `String(...)`) and `completedAt` (via `??=`).
+Only changes `status` to `"error"` if not already `"stopped"`.
+Called in `.catch()`, `resume()` catch block, and `drainQueue()` catch.
+
+#### `markStopped(completedAt?: number): void`
+
+Always sets `status = "stopped"` and `completedAt`.
+No guard — stopping is always valid.
+Called in `abort()` (2 sites) and `abortAll()` (2 sites).
+
+#### `resetForResume(startedAt: number): void`
+
+Sets `status = "running"`, `startedAt`.
+Clears `completedAt`, `result`, `error` to `undefined`.
+Called in `resume()` before re-running.
+
+### Guard semantics: preserve current behavior
+
+The current `.then()` and `.catch()` blocks guard only the `status` field but always set `result`/`error` and `completedAt`:
+
+```typescript
+// Current .then() — result and completedAt are set even when stopped
+if (record.status !== "stopped") {
+  record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+}
+record.result = responseText;
+record.completedAt ??= Date.now();
+```
+
+This is intentional — `get-result-tool.ts` reads `record.result` from stopped records.
+The transition methods preserve this behavior: data fields are always set, status is only changed when not stopped.
+The `??=` on `completedAt` preserves the abort timestamp when `markStopped()` fires before `.then()`.
+
+### Worktree result-append: reorder, don't add a method
+
+The `.then()` block currently appends worktree branch text to `record.result` after the transition.
+With encapsulated fields, direct writes to `result` are forbidden.
+
+Instead of adding an `appendToResult()` method, reorder the `.then()` block to compute the final result (including worktree text) before calling the transition method:
+
+```typescript
+.then(({ responseText, session, aborted, steered, sessionFile }) => {
+  // Worktree cleanup first — compute final result
+  let finalResult = responseText;
+  if (record.worktree) {
+    const wtResult = this.worktrees.cleanup(record.worktree, options.description);
+    record.worktreeResult = wtResult;
+    if (wtResult.hasChanges && wtResult.branch) {
+      finalResult += `\n\n---\nChanges saved to branch ...`;
+    }
+  }
+
+  // Transition with complete result
+  if (aborted) record.markAborted(finalResult);
+  else if (steered) record.markSteered(finalResult);
+  else record.markCompleted(finalResult);
+
+  record.session = session;
+  if (sessionFile) record.outputFile = sessionFile;
+
+  detach();
+  // ...
+})
+```
+
+The worktree cleanup reads `record.worktree` (a public field set before the promise) and writes `record.worktreeResult` (a public field).
+It does not depend on `record.status` or `record.result`, so the reorder is safe.
+
+### Correctness improvement in `resume()`
+
+The current `resume()` method lacks the "don't overwrite stopped" guard:
+
+```typescript
+// Current — no guard against abort race
+record.status = "completed";
+record.result = responseText;
+record.completedAt = Date.now();
+```
+
+After migration, `record.markCompleted(responseText)` includes the guard.
+This closes a latent race where `abort()` sets status to `"stopped"` between `resetForResume()` and the runner returning.
+The current code would overwrite `"stopped"` back to `"completed"` — the method call does not.
+
+### Circular import avoidance
+
+`agent-record.ts` imports types from `types.ts` (`SubagentType`, `AgentInvocation`).
+`types.ts` re-exports the class from `agent-record.ts`.
+
+This is safe because `agent-record.ts` uses `import type` for its `types.ts` imports — these are erased at runtime, so no runtime circular dependency exists.
+
+## Module-Level Changes
+
+### New files
+
+1. `src/agent-record.ts` — `AgentRecord` class, `AgentRecordInit` interface, `AgentRecordStatus` type.
+2. `test/agent-record.test.ts` — unit tests for constructor and all 7 transition methods.
+
+### Changed files
+
+1. `src/types.ts` — remove `AgentRecord` interface; add re-export: `export { AgentRecord, type AgentRecordInit, type AgentRecordStatus } from "./agent-record.js"`.
+2. `src/agent-manager.ts` — import `AgentRecord` as a value from `./agent-record.js`; replace object literal construction with `new AgentRecord(...)`; replace ~32 scattered field writes with 11 transition method calls.
+3. `test/helpers/make-record.ts` — import `AgentRecord` from `../../src/agent-record.js`; construct with `new AgentRecord(...)` instead of plain object.
+
+### Unchanged files
+
+All other source and test files — they use `import type { AgentRecord } from "./types.js"` and only read fields.
+The re-export from `types.ts` means zero import-path changes.
+
+## Test Impact Analysis
+
+### New tests enabled by the extraction
+
+The state machine is currently untestable in isolation — transitions are buried inside `agent-manager.ts`.
+After extraction:
+
+- Guard logic tested directly (e.g., `markCompleted` on a stopped record preserves status but sets result).
+- Invalid transition sequences tested without mocking the runner.
+- Error formatting (`Error` vs string) tested in isolation.
+- `resetForResume` field clearing tested without the full resume flow.
+
+### Existing tests that stay as-is
+
+`agent-manager.test.ts` tests verify end-to-end behavior (spawn, complete, abort, resume, queue drain, worktree).
+They remain unchanged — they verify the wiring between `AgentManager` and the `AgentRecord` class.
+
+### No test files need updating (except the shared factory)
+
+Issue #102 consolidated all test record construction into `createTestRecord()`.
+Only that one factory changes.
+All 8 consumer test files are untouched.
+
+## TDD Order
+
+### Cycle 1: AgentRecord class tests
+
+Test surface: `test/agent-record.test.ts` (new file).
+
+Tests cover:
+
+- Constructor: defaults (`status` → `"queued"`, `toolUses` → 0, `lifetimeUsage` → zeros, `compactionCount` → 0), passthrough of init values (including optional transition fields like `result`, `completedAt`).
+- `markRunning`: sets status and startedAt.
+- `markCompleted`: sets status/result/completedAt when not stopped; preserves status but still sets result/completedAt when stopped; `completedAt` uses `??=` semantics (does not overwrite existing value).
+- `markAborted` and `markSteered`: same guard behavior as `markCompleted`.
+- `markError`: sets status/error/completedAt when not stopped; preserves status but still sets error/completedAt when stopped; formats `Error` objects to `.message`, non-Error to `String(...)`.
+- `markStopped`: always sets status and completedAt, no guard.
+- `resetForResume`: sets status to `"running"` and startedAt; clears completedAt, result, error.
+
+Commit: `test: add AgentRecord class tests (#98)`
+
+### Cycle 2: AgentRecord class implementation
+
+Source: `src/agent-record.ts` (new file).
+Exports: `AgentRecord` class, `AgentRecordInit` interface, `AgentRecordStatus` type.
+All fields public initially (encapsulation deferred to cycle 6).
+
+All cycle 1 tests pass.
+
+Commit: `feat: create AgentRecord class with transition methods (#98)`
+
+### Cycle 3: Lift — migrate construction sites
+
+Changed files: `test/helpers/make-record.ts`, `src/agent-manager.ts`.
+
+`createTestRecord`: import `AgentRecord` from `agent-record.ts`; construct with `new AgentRecord(...)`.
+`agent-manager.ts`: import `AgentRecord` from `agent-record.ts` (value import); replace object literal in `spawn()` with `new AgentRecord(...)`.
+
+At this point, both the interface (in `types.ts`) and the class (in `agent-record.ts`) coexist.
+`agent-manager.ts` uses the class; all other consumers use the interface.
+Scattered field writes still work because fields are public.
+
+Run: full test suite + `pnpm run check`.
+
+Commit: `refactor: construct AgentRecord class in agent-manager and test factory (#98)`
+
+### Cycle 4: Shift — switch `types.ts` from interface to re-export
+
+Changed file: `src/types.ts`.
+
+Remove the `AgentRecord` interface definition.
+Add re-exports:
+
+```typescript
+export { AgentRecord } from "./agent-record.js";
+export type { AgentRecordInit, AgentRecordStatus } from "./agent-record.js";
+```
+
+All `import type { AgentRecord } from "./types.js"` across the codebase now resolve to the class.
+No consumer constructs `AgentRecord` as a plain object (construction was migrated in cycle 3).
+
+Run: `pnpm run check` (catches any structural incompatibilities).
+
+Commit: `refactor: replace AgentRecord interface with class re-export in types.ts (#98)`
+
+### Cycle 5: Replace scattered field writes with transition methods
+
+Changed file: `src/agent-manager.ts`.
+
+Replace all 11 transition sites:
+
+| Location               | Before                                                             | After                                                               |
+| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `startAgent()` running | `record.status = "running"; record.startedAt = ...`                | `record.markRunning(Date.now())`                                    |
+| `.then()` success      | `if (!stopped) status = ...; result = ...; completedAt ??= ...`    | `record.markCompleted(finalResult)` / `markAborted` / `markSteered` |
+| `.catch()` error       | `if (!stopped) status = "error"; error = ...; completedAt ??= ...` | `record.markError(err)`                                             |
+| `resume()` reset       | `status = ...; startedAt = ...; clear 3 fields`                    | `record.resetForResume(Date.now())`                                 |
+| `resume()` try         | `status = "completed"; result = ...; completedAt = ...`            | `record.markCompleted(responseText)`                                |
+| `resume()` catch       | `status = "error"; error = ...; completedAt = ...`                 | `record.markError(err)`                                             |
+| `abort()` queued       | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abort()` running      | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abortAll()` queued    | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `abortAll()` running   | `status = "stopped"; completedAt = ...`                            | `record.markStopped()`                                              |
+| `drainQueue()` catch   | `status = "error"; error = ...; completedAt = ...`                 | `record.markError(err)`                                             |
+
+Also reorder the `.then()` block: worktree cleanup moves before the transition call so the final result includes worktree branch text (see Design Overview).
+
+Run: full test suite.
+
+Commit: `refactor: replace scattered status transitions with AgentRecord methods (#98)`
+
+### Cycle 6: Encapsulate transition fields
+
+Changed file: `src/agent-record.ts`.
+
+Make `status`, `result`, `error`, `startedAt`, `completedAt` private (`_status`, `_result`, etc.) with public getters.
+Make `id`, `type`, `description`, `invocation` readonly.
+
+Run: `pnpm run check` — verifies no remaining direct writes to encapsulated fields anywhere in `src/` or `test/`.
+Run: full test suite.
+
+Commit: `refactor: encapsulate AgentRecord transition state (#98)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                   | Mitigation                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Guard semantics drift: transition methods might not exactly match scattered guards                                     | Each method's guard logic has dedicated tests (cycle 1); full agent-manager test suite runs after each cycle    |
+| Data fields on stopped records: `markCompleted` etc. must still set `result`/`completedAt` even when status is guarded | Explicit "stopped guard" test cases verify data fields are set; mirrors current `.then()` / `.catch()` behavior |
+| Worktree result-append after encapsulation: direct `record.result = ...` no longer compiles                            | `.then()` block reordered to compute full result before calling transition method (cycle 5)                     |
+| `types.ts` re-export introduces type-only circular dependency                                                          | `agent-record.ts` → `types.ts` imports are `import type` only (erased at runtime); no runtime cycle             |
+| `resume()` gains a "stopped" guard it didn't have before                                                               | This is a correctness improvement: closes a latent abort race; noted explicitly in design                       |
+
+## Open Questions
+
+- The `markCompleted`/`markAborted`/`markSteered` split is not in the original issue's 5-method list (which only shows `markCompleted`).
+  The split is needed because the `.then()` block dispatches to 3 distinct terminal statuses.
+- Stat accumulation (`toolUses++`, `addUsage(lifetimeUsage, ...)`, `compactionCount++`) is left as direct field writes on public fields.
+  These could become methods in a follow-up if the callback-threading removal (architecture.md Step 3) makes it natural.

package/docs/plans/0102-consolidate-test-record-factory.md

@@ -0,0 +1,176 @@
+---
+issue: 102
+issue_title: "Consolidate test AgentRecord construction into a shared factory"
+---
+
+# Consolidate test AgentRecord construction into a shared factory
+
+## Problem Statement
+
+Eight test files independently construct `AgentRecord` objects using three different patterns: copy-pasted `makeRecord()`/`mockRecord()` factory functions (5 files), inline `const baseRecord: AgentRecord = { ... }` literals (2 files), and `as AgentRecord` casts.
+When issue #98 converts `AgentRecord` from an interface to a class, every object-literal construction site breaks.
+A shared factory confines that future breakage to a single file.
+
+## Goals
+
+- Create a shared `createTestRecord()` factory in `test/helpers/make-record.ts`.
+- Migrate all 7 affected test files to import the shared factory.
+- No production code changes.
+- No behavior changes — purely mechanical.
+
+## Non-Goals
+
+- Converting `AgentRecord` to a class — that is issue #98, which depends on this change.
+- Adding new test coverage — this is a refactoring of test infrastructure only.
+- Touching `test/agent-manager.test.ts` — it constructs records via `manager.spawn()`, not literals.
+- Consolidating other test helpers (mock sessions, mock TUI, etc.).
+
+## Background
+
+### Relevant modules
+
+| Module                               | Role                                                                                                           |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `src/types.ts`                       | Defines the `AgentRecord` interface (20+ fields)                                                               |
+| `test/tools/agent-tool.test.ts`      | `makeRecord()` factory — 12 default fields, status "completed"                                                 |
+| `test/tools/get-result-tool.test.ts` | `makeRecord()` factory — 10 default fields, status "completed"                                                 |
+| `test/tools/steer-tool.test.ts`      | `makeRecord()` factory — 9 default fields, status "running", includes mock session, uses `as AgentRecord` cast |
+| `test/ui/agent-menu.test.ts`         | `makeRecord()` factory — 10 default fields, status "completed"                                                 |
+| `test/conversation-viewer.test.ts`   | `mockRecord()` factory — 6 default fields, status "running", uses `as AgentRecord` cast                        |
+| `test/notification.test.ts`          | 4 inline `baseRecord` literals, status "completed"                                                             |
+| `test/service-adapter.test.ts`       | 4 inline `baseRecord` / `minimal` literals, mixed statuses                                                     |
+
+### Convention from sibling packages
+
+`packages/pi-autoformat/test/helpers/rpc.ts` is the only existing shared test helper in the monorepo.
+The pattern is a plain module under `test/helpers/` with named exports — no class, no framework.
+
+### Relationship to issue #98
+
+Issue #98 plans to extract `MutableAgentRecord` as a class implementing the `AgentRecord` interface.
+That plan explicitly notes: "All test files that construct `AgentRecord` literals — they create interface-compatible objects, not class instances" and lists them as unchanged.
+Once this consolidation lands, issue #98's "unchanged" assumption becomes trivially true: only the shared factory needs updating if the construction API changes.
+
+## Design Overview
+
+### Shared factory: `createTestRecord()`
+
+A single function in `test/helpers/make-record.ts` with the `Partial<AgentRecord>` override pattern already used by 5 of the 7 files:
+
+```typescript
+import type { AgentRecord } from "../../src/types.js";
+
+export function createTestRecord(
+  overrides: Partial<AgentRecord> = {},
+): AgentRecord {
+  return {
+    id: "agent-1",
+    type: "general-purpose",
+    description: "Test task",
+    status: "completed",
+    result: "All done.",
+    toolUses: 3,
+    startedAt: 1000,
+    completedAt: 2000,
+    compactionCount: 0,
+    lifetimeUsage: { input: 500, output: 500, cacheWrite: 0 },
+    ...overrides,
+  };
+}
+```
+
+### Default-value decisions
+
+The defaults match the majority pattern (6 of 7 files default to a "completed" record).
+The two files that need "running" records (`steer-tool`, `conversation-viewer`) pass `{ status: "running" }` as overrides — a one-field change.
+
+The `as AgentRecord` cast used by `steer-tool.test.ts` and `conversation-viewer.test.ts` is no longer needed: the shared factory returns a full `AgentRecord` with all required fields populated, so TypeScript is satisfied without casting.
+
+### Migration strategy for inline-literal files
+
+`notification.test.ts` and `service-adapter.test.ts` construct multiple distinct inline literals — they don't have a single factory.
+Each inline literal becomes a `createTestRecord({ ...specific overrides })` call.
+The `baseRecord` variable declared in each `describe` block is replaced with a call to `createTestRecord()`.
+
+For `service-adapter.test.ts`, the top-level `baseRecord` with custom values (`id: "abc-123"`, `type: "Explore"`, etc.) becomes `createTestRecord({ id: "abc-123", type: "Explore", ... })`.
+
+## Module-Level Changes
+
+### New files
+
+1. `test/helpers/make-record.ts` — exports `createTestRecord()`.
+
+### Changed files
+
+1. `test/tools/agent-tool.test.ts` — remove local `makeRecord()`, import `createTestRecord` from helpers.
+2. `test/tools/get-result-tool.test.ts` — remove local `makeRecord()`, import `createTestRecord` from helpers.
+3. `test/tools/steer-tool.test.ts` — remove local `makeRecord()`, import `createTestRecord` from helpers.
+   Replace default `status: "running"` and `session` with overrides in each call site.
+4. `test/ui/agent-menu.test.ts` — remove local `makeRecord()`, import `createTestRecord` from helpers.
+5. `test/conversation-viewer.test.ts` — remove local `mockRecord()`, import `createTestRecord` from helpers.
+   Replace default `status: "running"` and `startedAt: Date.now()` with overrides in each call site.
+6. `test/notification.test.ts` — replace 4 inline `baseRecord` literals with `createTestRecord()` calls.
+7. `test/service-adapter.test.ts` — replace inline `baseRecord` / `minimal` / per-test literals with `createTestRecord()` calls.
+
+### Unchanged files
+
+1. `test/agent-manager.test.ts` — constructs records via `manager.spawn()`, not literals.
+2. All production source files — no changes.
+
+## Test Impact Analysis
+
+### New tests enabled
+
+1. A small sanity test in `test/helpers/make-record.test.ts` verifying that `createTestRecord()` returns a valid `AgentRecord` with expected defaults and that overrides are applied.
+   This is optional — the factory is exercised transitively by every consumer — but it documents the contract for future maintainers (especially when #98 changes construction).
+
+### Existing tests that become redundant
+
+None.
+This is a pure refactoring of test infrastructure; no production behavior changes.
+
+### Existing tests that stay as-is
+
+All existing test assertions stay unchanged.
+Only the construction of `AgentRecord` objects in test setup code changes; the assertions that read those records are untouched.
+
+## TDD Order
+
+1. **Create shared factory and its test.**
+   Add `test/helpers/make-record.ts` with `createTestRecord()`.
+   Add `test/helpers/make-record.test.ts` verifying defaults and override behavior.
+   Commit: `test: add shared createTestRecord factory (#102)`
+
+2. **Migrate tool test files.**
+   Update `agent-tool.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts` to import `createTestRecord` and remove local `makeRecord()` functions.
+   Run `pnpm vitest run test/tools/agent-tool.test.ts test/tools/get-result-tool.test.ts test/tools/steer-tool.test.ts` to verify.
+   Commit: `test: migrate tool tests to shared createTestRecord (#102)`
+
+3. **Migrate UI test files.**
+   Update `agent-menu.test.ts` and `conversation-viewer.test.ts` to import `createTestRecord` and remove local `makeRecord()`/`mockRecord()` functions.
+   Run `pnpm vitest run test/ui/agent-menu.test.ts test/conversation-viewer.test.ts` to verify.
+   Commit: `test: migrate UI tests to shared createTestRecord (#102)`
+
+4. **Migrate notification and service-adapter tests.**
+   Update `notification.test.ts` and `service-adapter.test.ts` to replace inline literals with `createTestRecord()` calls.
+   Run `pnpm vitest run test/notification.test.ts test/service-adapter.test.ts` to verify.
+   Commit: `test: migrate notification and service-adapter tests to shared createTestRecord (#102)`
+
+5. **Final verification.**
+   Run full test suite (`pnpm vitest run`) and type check (`pnpm run check`) to confirm no regressions.
+   Commit: not needed if steps 2–4 are clean; otherwise a fix-up commit.
+
+## Risks and Mitigations
+
+| Risk                                                                                                                   | Mitigation                                                                                                                               |
+| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Shared defaults don't match a test's assumptions, causing silent false-passes                                          | Each migration step runs the affected test file immediately; review each test's overrides to ensure they still express the test's intent |
+| `steer-tool.test.ts` relies on `session: { fake: true }` in its factory default, which the shared factory omits        | Pass `session` as an override at each call site; the mock session is test-specific and doesn't belong in shared defaults                 |
+| `conversation-viewer.test.ts` uses `startedAt: Date.now()` which the shared factory replaces with `1000`               | Replace with `createTestRecord({ status: "running" })`; `startedAt` value is not asserted in any conversation-viewer test                |
+| `service-adapter.test.ts` uses custom `id`, `type`, `description` values that carry semantic meaning in its assertions | Pass those values explicitly as overrides to `createTestRecord()`                                                                        |
+| The `as AgentRecord` cast removal changes type-checking strictness                                                     | The shared factory returns a complete object satisfying all required fields, so removing the cast is strictly safer                      |
+
+## Open Questions
+
+- The factory name `createTestRecord` vs `makeRecord` vs `makeAgentRecord`: the plan uses `createTestRecord` to distinguish it from the production `AgentRecord` constructor that #98 will introduce.
+  If #98 names its constructor differently, this can be revisited.

package/docs/retro/0061-session-format-transcript.md

@@ -0,0 +1,41 @@
+---
+issue: 61
+issue_title: "feat: port subagent transcript logging to Pi's official JSONL session format"
+---
+
+# Retro: #61 — port subagent transcript logging to Pi's official JSONL session format
+
+## Final Retrospective (2026-05-20T17:15:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped a migration from the bespoke `output-file.ts` transcript format to Pi's official JSONL session format via `SessionManager.create()`.
+The change replaced 143 lines of manual streaming code with 3 lines leveraging the SDK's native persistence, nested subagent sessions under the parent session directory with `parentSession` header linking.
+Released as `pi-subagents-v6.0.0` (major version bump due to breaking transcript format change).
+
+### Observations
+
+#### What went well
+
+- The plan-to-implementation translation was clean: 6 TDD steps mapped to 7 commits (one extra `fix:` for biome lint).
+  No steps needed reordering or merging.
+- The `ask_user` design decision gates during planning (persistence strategy, file location) produced clear answers that avoided rework during implementation.
+- Research into nicobailon/pi-subagents, edxeth/pi-subagents, and HazAT/pi-interactive-subagents provided useful reference for the session directory layout, confirming the parent-relative nesting pattern.
+- The biome lint catch on the unused `cwd` parameter led to a better design — incorporating `cwd` into the temp fallback path for project namespacing — rather than a mechanical underscore prefix.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan listed test impact for `agent-runner.test.ts` but didn't grep for other test files mocking `SessionManager` or `ctx.sessionManager`.
+  Three additional files needed updating: `agent-runner-extension-tools.test.ts`, `print-mode.test.ts`, and `test/tools/agent-tool.test.ts`.
+  The testing skill explicitly says "grep for ALL test files that construct a compatible mock — not just factory helpers."
+  Impact: ~5 minutes of reactive fixes during Step 4.
+  Self-identified at implementation time.
+
+- `missing-context` — The plan didn't account for the timing difference between the old synchronous `record.outputFile` assignment (immediately after `spawn()`) and the new asynchronous availability (after `SessionManager.create()` runs inside `runAgent()`).
+  This required adding `session.sessionManager.getSessionFile()` in the `onSessionCreated` callback — a design decision made during implementation.
+  Impact: minor within-step rework, no extra commit needed.
+
+#### What caused friction (user side)
+
+- The dependency update to 0.75.4 was a reasonable pre-plan request, but it added ~10 minutes of tangential work (diagnosing `pnpm update` resolution behavior, normalizing version specifiers).
+  This could have been a separate commit/session, though batching it was pragmatic since it gave the plan access to the latest SDK types.