@gotgenes/pi-subagents 5.8.2 → 6.0.1

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

@@ -0,0 +1,284 @@
+---
+issue: 61
+issue_title: "feat: port subagent transcript logging to Pi's official JSONL session format"
+---
+
+# Port subagent transcripts to Pi's official session format
+
+## Problem Statement
+
+Subagent conversation transcripts are written as JSONL by `output-file.ts`, but use a bespoke flat format (`{ isSidechain, agentId, type, message, timestamp, cwd }`) that does not conform to Pi's official session file format.
+Pi's `SessionManager` writes tree-structured JSONL with a session header, UUIDv7 entry IDs, `parentId` tree structure, and typed entry discriminants (`"message"`, `"compaction"`, etc.).
+The bespoke format cannot be loaded by Pi's session tooling (session selector, export-html, resume) and requires manual `jq` inspection for debugging.
+
+## Goals
+
+- Subagent transcripts written in Pi's official JSONL session format via `SessionManager`.
+- Transcripts discoverable via the parent session path (nested under a parent-session-relative directory).
+- Parent session linkage via the `parentSession` header field.
+- Delete `output-file.ts` — the SDK's `SessionManager` handles all JSONL writing natively.
+- Existing debugging use case preserved (full turn-by-turn history on disk).
+
+## Non-Goals
+
+- Making subagent sessions resumable via Pi's `/resume` command (future work; requires session selection UX changes).
+- Cross-extension parent-session resolution (issue #22 — separate track).
+- Changing the `SessionManager` usage for the child `AgentSession` itself (the child session already uses `SessionManager.inMemory()`; we replace it with a persisted one).
+
+## Background
+
+### Current flow
+
+1. `agent-tool.ts` calls `createOutputFilePath(cwd, agentId, parentSessionId)` → creates `/tmp/pi-subagents-<uid>/<encoded-cwd>/<parentSessionId>/tasks/<agentId>.output`.
+2. `writeInitialEntry(path, agentId, prompt, cwd)` writes the first user message in the bespoke format.
+3. `streamToOutputFile(session, path, agentId, cwd)` subscribes to `turn_end` events and appends bespoke JSONL entries.
+4. `agent-manager.ts` calls the cleanup function on completion/error to do a final flush and unsubscribe.
+
+### Pi's SessionManager API
+
+`SessionManager` from `@earendil-works/pi-coding-agent` provides:
+
+- `SessionManager.create(cwd, sessionDir?)` — creates a persisted session file in the given directory.
+- `newSession({ parentSession? })` — writes a `SessionHeader` with `parentSession` linking.
+- `appendMessage(message)` — writes a `SessionMessageEntry` with auto-generated UUIDv7 `id` and `parentId` (tree structure).
+- `appendCompaction(...)`, `appendCustomEntry(...)` — first-class support for all entry types.
+- `getSessionFile()` — returns the path to the JSONL file on disk.
+
+The child `AgentSession` (created by `createAgentSession`) accepts a `sessionManager` option.
+Currently set to `SessionManager.inMemory(cwd)`, switching to `SessionManager.create(cwd, sessionDir)` makes the SDK write official-format JSONL automatically — no manual streaming code needed.
+
+### Reference implementations
+
+nicobailon/pi-subagents places subagent sessions under `<parent-session-dir>/<parent-session-basename>/<runId>/`.
+This keeps them discoverable via the parent session path without cluttering the main session list.
+Our approach follows the same pattern: derive a `sessionDir` from the parent session file.
+
+### Constraints
+
+- `agent-runner.ts` already imports `SessionManager` for the `inMemory()` call — switching to `create()` adds no new dependency.
+- `ctx.sessionManager` is `ReadonlySessionManager` and provides `getSessionId()`, `getSessionFile()`, and `getSessionDir()`.
+- The `code-style` skill requires keeping IO at the edges and not hiding dependencies.
+  The session directory derivation should be a pure function that receives the parent session file path.
+
+## Design Overview
+
+### Core change: persisted SessionManager in agent-runner
+
+Replace `SessionManager.inMemory(cwd)` with `SessionManager.create(cwd, sessionDir)` inside `runAgent()`.
+The `sessionDir` is derived from the parent's session file path, and the `parentSession` option links the child to the parent.
+
+The key insight is that the SDK's `createAgentSession` already writes all messages through the `SessionManager` it receives.
+By switching from in-memory to persisted, every message the child agent produces is automatically written in official JSONL format — no manual subscription or streaming code required.
+
+### Session directory derivation
+
+```typescript
+/**
+ * Derive the session directory for a subagent from the parent session file.
+ * Layout: <parent-dir>/<parent-basename>/tasks/
+ *
+ * Example:
+ *   parent: ~/.pi/agent/sessions/--home-user-project--/2026-05-20T12-00-00Z_.jsonl
+ *   result: ~/.pi/agent/sessions/--home-user-project--/2026-05-20T12-00-00Z_/tasks/
+ *
+ * Falls back to a temp directory when the parent session is not persisted.
+ */
+function deriveSubagentSessionDir(
+  parentSessionFile: string | undefined,
+  cwd: string,
+): string;
+```
+
+### Data flow (after)
+
+1. `agent-tool.ts` passes `parentSessionFile` (from `ctx.sessionManager.getSessionFile()`) and `parentSessionId` to `agent-manager.ts` via `SpawnOptions`.
+2. `agent-manager.ts` threads them to `agent-runner.ts` via `RunOptions`.
+3. `agent-runner.ts` calls `deriveSubagentSessionDir(parentSessionFile, cwd)` and creates `SessionManager.create(cwd, sessionDir)` with `{ parentSession: parentSessionId }`.
+4. The `createAgentSession` SDK call receives this persisted `SessionManager`.
+5. All messages are written to disk automatically by the SDK.
+6. `agent-runner.ts` returns the session file path in `RunResult` (via `sessionManager.getSessionFile()`).
+7. `agent-tool.ts` stores the path on `AgentRecord.outputFile` for display in notifications/UI.
+
+### What gets deleted
+
+- `output-file.ts` — entirely replaced by the persisted `SessionManager`.
+- `output-file.test.ts` — the `encodeCwd` tests are no longer needed (Pi's `SessionManager` handles directory encoding internally).
+- `streamToOutputFile`, `writeInitialEntry`, `createOutputFilePath` imports from `agent-tool.ts`.
+- `outputCleanup` field from `AgentRecord` (no manual cleanup needed; the `SessionManager` is append-only).
+- The `onSessionCreated` wrapper in `agent-tool.ts` that wires output-file streaming.
+
+### What changes
+
+- `RunOptions` gains `parentSessionFile?: string` and `parentSessionId?: string`.
+- `RunResult` gains `sessionFile?: string` (path to the persisted session JSONL).
+- `SpawnOptions` gains `parentSessionFile?: string` and `parentSessionId?: string`.
+- `AgentRecord.outputCleanup` is removed (no manual flush/unsubscribe lifecycle).
+- `agent-manager.ts` removes the `outputCleanup` calls in completion/error paths.
+- `agent-tool.ts` sets `record.outputFile` from the `RunResult.sessionFile` instead of calling `createOutputFilePath`.
+- `notification.ts`, `renderer.ts`, `types.ts` — `outputFile` field semantics unchanged (still a path string); only the source changes.
+
+### Edge cases
+
+1. **Parent session not persisted** (e.g., API/headless mode where the parent uses `SessionManager.inMemory()`): `ctx.sessionManager.getSessionFile()` returns `undefined`.
+   Fallback: use a temp directory under `/tmp/pi-subagents-<uid>/` (similar to current behavior) so transcripts are still written to disk.
+2. **Worktree isolation**: `effectiveCwd` differs from `ctx.cwd`.
+   The `SessionManager.create()` call uses `effectiveCwd` (same as current `inMemory` call), but the `sessionDir` is still derived from the parent session — the session header's `cwd` field correctly records the worktree path.
+
+## Module-Level Changes
+
+### New file: `src/session-dir.ts`
+
+Pure function `deriveSubagentSessionDir(parentSessionFile, cwd)`.
+Extracts the parent session basename, constructs `<parent-dir>/<parent-basename>/tasks/`.
+Falls back to a temp directory when `parentSessionFile` is undefined.
+
+### Modified: `src/agent-runner.ts`
+
+- Import `deriveSubagentSessionDir` from `session-dir.ts`.
+- Add `parentSessionFile?: string` and `parentSessionId?: string` to `RunOptions`.
+- Add `sessionFile?: string` to `RunResult`.
+- Replace `SessionManager.inMemory(cfg.effectiveCwd)` with:
+
+```typescript
+const sessionDir = deriveSubagentSessionDir(options.parentSessionFile, cfg.effectiveCwd);
+const sessionManager = SessionManager.create(cfg.effectiveCwd, sessionDir);
+sessionManager.newSession({ parentSession: options.parentSessionId });
+```
+
+- After `session.prompt()`, capture `sessionManager.getSessionFile()` into `RunResult.sessionFile`.
+
+### Modified: `src/agent-manager.ts`
+
+- Add `parentSessionFile?: string` and `parentSessionId?: string` to `SpawnOptions`.
+- Thread them to `RunOptions` in the `runner.run()` call.
+- Remove `outputCleanup` calls from the completion and error handlers.
+
+### Modified: `src/tools/agent-tool.ts`
+
+- Remove import of `createOutputFilePath`, `streamToOutputFile`, `writeInitialEntry`.
+- Remove the `onSessionCreated` wrapper that wired output-file streaming.
+- Pass `parentSessionFile: ctx.sessionManager.getSessionFile()` and `parentSessionId: ctx.sessionManager.getSessionId()` in `SpawnOptions`.
+- After spawn, set `record.outputFile` from the returned session file path (available via `onSessionCreated` callback which gives access to the session's `sessionManager`).
+
+### Modified: `src/types.ts`
+
+- Remove `outputCleanup?: () => void` from `AgentRecord`.
+
+### Deleted: `src/output-file.ts`
+
+Entire file removed.
+
+### Deleted: `test/output-file.test.ts`
+
+Entire file removed.
+
+### Unchanged: `src/notification.ts`, `src/renderer.ts`
+
+These read `record.outputFile` (a path string) — the field still exists, just populated differently.
+The `NotificationDetails.outputFile` field is unchanged.
+
+## Test Impact Analysis
+
+### New tests enabled by extraction
+
+1. `test/session-dir.test.ts` — unit tests for `deriveSubagentSessionDir`:
+   - Parent session file present → derives correct nested path.
+   - Parent session file undefined → falls back to temp directory.
+   - Various path shapes (POSIX, Windows-like).
+
+2. `test/agent-runner.test.ts` — updated tests verifying:
+   - `SessionManager.create` is called (not `inMemory`) when `parentSessionFile` is provided.
+   - `newSession({ parentSession })` is called with the parent session ID.
+   - `RunResult.sessionFile` is populated from the session manager.
+
+### Tests that become redundant
+
+- `test/output-file.test.ts` (`encodeCwd` tests) — the directory encoding is now handled by `deriveSubagentSessionDir` with a different layout.
+  The `encodeCwd` function is deleted.
+
+### Tests that stay as-is
+
+- All `agent-manager.test.ts` tests that mock the runner — they don't depend on `output-file` internals.
+- All `notification.test.ts` and `renderer.test.ts` tests — they read `record.outputFile` which remains a string.
+- The `onSessionCreated` callback tests in `agent-tool.test.ts` need updating to remove the output-file wiring expectations.
+
+## TDD Order
+
+### Step 1: Add `deriveSubagentSessionDir` with tests
+
+1. Create `src/session-dir.ts` with the pure function.
+2. Create `test/session-dir.test.ts` with tests for parent-present and fallback cases.
+3. Commit: `feat: add deriveSubagentSessionDir for session directory derivation (#61)`
+
+### Step 2: Thread parent session info through SpawnOptions and RunOptions
+
+1. Add `parentSessionFile?: string` and `parentSessionId?: string` to `SpawnOptions` in `agent-manager.ts`.
+2. Add `parentSessionFile?: string` and `parentSessionId?: string` to `RunOptions` in `agent-runner.ts`.
+3. Add `sessionFile?: string` to `RunResult` in `agent-runner.ts`.
+4. Thread the new fields from `SpawnOptions` → `RunOptions` in `agent-manager.ts`.
+5. Update tests to verify the new fields are threaded.
+6. Commit: `feat: thread parent session info through spawn and run options (#61)`
+
+### Step 3: Switch agent-runner to persisted SessionManager
+
+1. In `runAgent()`, replace `SessionManager.inMemory(cfg.effectiveCwd)` with the persisted variant using `deriveSubagentSessionDir`.
+2. Call `sessionManager.newSession({ parentSession: options.parentSessionId })`.
+3. Capture `sessionManager.getSessionFile()` into `RunResult.sessionFile`.
+4. Update `agent-runner.test.ts` mocks to expect `SessionManager.create` instead of `SessionManager.inMemory`.
+5. Commit: `feat: use persisted SessionManager for subagent sessions (#61)`
+
+### Step 4: Remove output-file wiring from agent-tool and agent-manager
+
+1. Remove the `onSessionCreated` output-file wrapper in `agent-tool.ts`.
+2. Remove `createOutputFilePath`, `writeInitialEntry`, `streamToOutputFile` imports.
+3. Set `record.outputFile` from the session manager's file path (via `onSessionCreated` callback).
+4. Pass `parentSessionFile` and `parentSessionId` in spawn options.
+5. Remove `outputCleanup` calls from `agent-manager.ts` completion/error handlers.
+6. Remove `outputCleanup` from `AgentRecord` in `types.ts`.
+7. Update agent-tool and agent-manager tests.
+8. Commit: `feat: wire session file path through agent-tool, remove output-file streaming (#61)`
+
+### Step 5: Delete output-file.ts and its tests
+
+1. Delete `src/output-file.ts`.
+2. Delete `test/output-file.test.ts`.
+3. Run full test suite to verify no remaining references.
+4. Commit: `feat!: remove bespoke output-file transcript format (#61)`
+
+### Step 6: Documentation update
+
+1. Update `docs/architecture/architecture.md` — remove `output-file.ts` from the module listing, add `session-dir.ts`, mark #61 as complete.
+2. Commit: `docs: update architecture for session format migration (#61)`
+
+## Risks and Mitigations
+
+### Risk: SessionManager.create may fail in environments without a writable home directory
+
+The temp-directory fallback in `deriveSubagentSessionDir` handles this case.
+When the parent session file is unavailable (headless/API mode), we fall back to a temp directory just like the current implementation.
+
+### Risk: Persisted sessions accumulate disk space over time
+
+Pi's session tooling already manages session storage.
+Subagent sessions nested under the parent session directory are cleaned up when the parent session is deleted.
+This is an improvement over the current `/tmp` location where files persist until system cleanup.
+
+### Risk: Tests that mock SessionManager.inMemory need updating
+
+Step 3 explicitly plans for updating these mocks.
+The change is localized to `agent-runner.ts` and its direct test file.
+
+### Risk: Breaking change for consumers that read outputFile paths
+
+The `outputFile` field changes from `/tmp/pi-subagents-<uid>/.../tasks/<agentId>.output` to `~/.pi/agent/sessions/.../<timestamp>_<uuid>.jsonl`.
+Consumers that parse the path (unlikely) would break, but the field is internal to the extension and only used for display.
+The format of the file content changes from bespoke JSONL to Pi's official format — this is the intentional breaking change.
+
+## Open Questions
+
+1. Should the plan add a `sessionDir` field to `AgentRecord` alongside `outputFile`, or is the session file path sufficient for all use cases?
+   Deferred — start with `outputFile` pointing to the session file; add `sessionDir` if needed later.
+2. Should foreground agents also get persisted sessions, or only background agents?
+   The current `output-file` code only runs for background agents.
+   Persisted sessions are valuable for both — the plan applies the change in `agent-runner.ts` which serves both paths.
+   If this proves too noisy, a follow-up can gate it behind a setting.

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.

package/docs/retro/0077-inject-project-agents-dir.md

@@ -0,0 +1,33 @@
+---
+issue: 77
+issue_title: "refactor: add projectAgentsDir to AgentMenuDeps instead of reading process.cwd() inline"
+---
+
+# Retro: #77 — inject projectAgentsDir into AgentMenuDeps
+
+## Final Retrospective (2026-05-20T16:15:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped a refactoring that adds `projectAgentsDir: string` to `AgentMenuDeps`, replacing the inline `process.cwd()` lambda in `createAgentsMenuHandler`.
+The change mirrors the existing `personalAgentsDir` injection pattern.
+Released as `pi-subagents-v5.8.2`.
+
+### Observations
+
+#### What went well
+
+- Clean end-to-end execution: plan → TDD → ship with zero corrections or rework.
+- The Red test was well-targeted: exercised `findAgentFile` through the menu navigation path and naturally failed because `process.cwd()` produced a different path than the injected `/test-project/.pi/agents`.
+- Correctly identified at execution time that the plan's two-step TDD split was impractical (interface change is atomic) and combined into a single `refactor:` commit.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` — The plan listed two TDD commits (step 1: `test:`, step 2: `refactor:`) but adding a required field to `AgentMenuDeps` is an atomic change — the test references the new field, so both must land together.
+  The testing skill's shared-type-definition rule ("changing that type in step N breaks steps N+1…N+k — fold them into one step") should have been applied during planning.
+  Impact: added friction but no rework — the deviation was self-identified at execution time and the steps were combined.
+  Self-identified.
+
+#### What caused friction (user side)
+
+- None observed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.8.2",
+  "version": "6.0.1",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -43,10 +43,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@earendil-works/pi-ai": "0.75.4",
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
+    "rumdl": "^0.1.93",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "rumdl": "^0.1.93"
+    "vitest": "^4.1.5"
   },
   "pi": {
     "extensions": [

package/src/agent-manager.ts

@@ -74,6 +74,10 @@ export interface SpawnOptions {
   onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void;
+  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+  parentSessionFile?: string;
+  /** Session ID of the parent agent (stored in the child session's parentSession header). */
+  parentSessionId?: string;
 }
 
 export class AgentManager {
@@ -205,6 +209,8 @@ export class AgentManager {
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
       cwd: worktreeCwd,
+      parentSessionFile: options.parentSessionFile,
+      parentSessionId: options.parentSessionId,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -223,6 +229,10 @@ export class AgentManager {
       },
       onSessionCreated: (session) => {
         record.session = session;
+        // Capture the session file path early so it's available for display
+        // before the run completes (e.g. in background agent status messages).
+        const file = session.sessionManager?.getSessionFile?.();
+        if (file) record.outputFile = file;
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
@@ -233,7 +243,7 @@ export class AgentManager {
         options.onSessionCreated?.(session);
       },
     })
-      .then(({ responseText, session, aborted, steered }) => {
+      .then(({ responseText, session, aborted, steered, sessionFile }) => {
         // Don't overwrite status if externally stopped via abort()
         if (record.status !== "stopped") {
           record.status = aborted ? "aborted" : steered ? "steered" : "completed";
@@ -241,15 +251,10 @@ export class AgentManager {
         record.result = responseText;
         record.session = session;
         record.completedAt ??= Date.now();
+        if (sessionFile) record.outputFile = sessionFile;
 
         detach();
 
-        // Final flush of streaming output file
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup", err); }
-          record.outputCleanup = undefined;
-        }
-
         // Clean up worktree if used
         if (record.worktree) {
           const wtResult = this.worktrees.cleanup(record.worktree, options.description);
@@ -277,11 +282,7 @@ export class AgentManager {
 
         detach();
 
-        // Final flush of streaming output file on error
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup on error", err); }
-          record.outputCleanup = undefined;
-        }
+
 
         // Best-effort worktree cleanup on error
         if (record.worktree) {