@gotgenes/pi-subagents 7.5.0 → 7.6.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.5.1...pi-subagents-v7.6.0) (2026-05-26)
+
+
+### Features
+
+* add WorktreeState.performCleanup for self-cleanup ([#216](https://github.com/gotgenes/pi-packages/issues/216)) ([ad0583a](https://github.com/gotgenes/pi-packages/commit/ad0583a9c26b6782af2a55ea86e72f3c3474ebe7))
+
+
+### Documentation
+
+* plan decompose startAgent via RunHandle lifecycle object ([#216](https://github.com/gotgenes/pi-packages/issues/216)) ([2689571](https://github.com/gotgenes/pi-packages/commit/268957175c2aaa03da98c99778c6ff67e0bf45e3))
+* **retro:** add planning stage notes for issue [#216](https://github.com/gotgenes/pi-packages/issues/216) ([06daa19](https://github.com/gotgenes/pi-packages/commit/06daa1923d75aae8aec1ddd492486c951e50a23f))
+* **retro:** add retro notes for issue [#215](https://github.com/gotgenes/pi-packages/issues/215) ([57f7cf9](https://github.com/gotgenes/pi-packages/commit/57f7cf9139ce3d77f2ec91541bc67cd78c57bdb8))
+* **retro:** add TDD stage notes for issue [#216](https://github.com/gotgenes/pi-packages/issues/216) ([4001da1](https://github.com/gotgenes/pi-packages/commit/4001da1faecc15d2c2c92e7fd69788d908ef5ad8))
+* update architecture doc for [#216](https://github.com/gotgenes/pi-packages/issues/216) RunHandle decomposition ([8ad4a2a](https://github.com/gotgenes/pi-packages/commit/8ad4a2a2d25acdf7f2cd544f6b3cd3949edbc471))
+
+## [7.5.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.5.0...pi-subagents-v7.5.1) (2026-05-26)
+
+
+### Documentation
+
+* plan decompose buildParentContext ([#215](https://github.com/gotgenes/pi-packages/issues/215)) ([9103609](https://github.com/gotgenes/pi-packages/commit/910360991b50c320927c1457bfef6b7cb5624b7b))
+* **retro:** add planning stage notes for issue [#215](https://github.com/gotgenes/pi-packages/issues/215) ([5c534d5](https://github.com/gotgenes/pi-packages/commit/5c534d5efb640ef1d72d6ccf7bf2e15ac2acf755))
+* **retro:** add TDD stage notes for issue [#215](https://github.com/gotgenes/pi-packages/issues/215) ([79064d0](https://github.com/gotgenes/pi-packages/commit/79064d072c36c2f92013dbfba58ce1de1ab01bce))
+
 ## [7.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.4.0...pi-subagents-v7.5.0) (2026-05-26)
 
 

package/docs/architecture/architecture.md

@@ -652,20 +652,23 @@ Extract per-entry-type formatters: `formatMessageEntry(entry)` and `formatCompac
 - Smell: B (oversized function)
 - Outcome: cognitive complexity < 10, function < 15 LOC
 
-### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216]
+### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216] ✓
 
-`startAgent` is a ~130-line private method that chains worktree setup → state transitions → observer notification → abort-signal wiring → runner invocation → `.then()` completion handler (~35 lines) → `.catch()` error handler (~15 lines).
-Both the `.then()` and `.catch()` blocks share common finalization logic (background counter decrement, observer notification, queue drain, worktree cleanup, detach signal).
+`startAgent` had two mutable closure variables (`unsubRecordObserver`, `detachParentSignal`) shared across three callbacks with duplicated finalization logic in `.then()`/`.catch()`.
+The fix introduced a `RunHandle` lifecycle object (private to `agent-manager.ts`) that owns the per-run cleanup state and exposes `complete()`/`fail()` as Tell-Don't-Ask methods.
+`WorktreeState` gained `performCleanup(worktrees, description)` to eliminate the ask-tell dance at cleanup sites.
 
-Extract:
+Extracted:
 
-1. `handleRunCompletion(record, options, result)` — worktree cleanup, state transition, execution update, observer notification.
-2. `handleRunError(record, options, err)` — error marking, worktree cleanup.
-3. `finalizeBackgroundRun(record)` — shared `runningBackground--`, observer, `drainQueue()`.
+1. `RunHandle` class — owns `unsub`/`detachFn`, `wireSignal()`, `attachObserver()`, `complete()`, `fail()`, idempotent `fireOnFinished()`.
+2. `finalizeBackgroundRun(record)` — shared `runningBackground--`, crash-safe observer notification, `drainQueue()`.
+3. `setupWorktree(id, record, isolation)` — worktree creation with strict failure.
+4. `flushPendingSteers(id, session)` — drain buffered steers on session creation.
+5. `WorktreeState.performCleanup(worktrees, description)` — self-cleanup eliminating ask-tell.
 
-- Target: `src/lifecycle/agent-manager.ts`
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/worktree-state.ts`
 - Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
-- Outcome: no method > 40 LOC, `agent-manager.ts` < 480 LOC
+- Outcome: `startAgent` reduced to ~40 LOC coordinator with zero mutable `let` bindings; `.then()`/`.catch()` are one-liners
 
 ### Step 4: Extract overwrite guard from UI — [#217]
 

package/docs/plans/0215-decompose-build-parent-context.md

@@ -0,0 +1,166 @@
+---
+issue: 215
+issue_title: "Decompose buildParentContext (cognitive 30) (Phase 13, Step 2)"
+---
+
+# Decompose `buildParentContext`
+
+## Problem Statement
+
+`buildParentContext` in `src/session/context.ts` is the only remaining fallow refactoring target in the package.
+The function has a cognitive complexity of 30, driven by a loop with three type-check branches (`message`, `compaction`, default), each with sub-branches for role (`user` vs `assistant`) and content type (`string` vs array).
+The architecture roadmap (Phase 13, Step 2) targets cognitive complexity < 10 and function body < 15 LOC.
+
+## Goals
+
+- Extract per-entry-type formatters: `formatMessageEntry(entry)` and `formatCompactionEntry(entry)`.
+- Reduce `buildParentContext` to a loop + filter + join orchestrator (< 15 LOC).
+- Achieve cognitive complexity < 10 for all functions in the file.
+- Add unit tests for the extracted formatters and the orchestrator.
+
+## Non-Goals
+
+- Changing the public API surface (`buildParentContext`, `extractText`) — signatures stay the same.
+- Moving `extractText` to another module (noted as a follow-up in prior plans but out of scope).
+- Refactoring callers (`parent-snapshot.ts`) — they are already tested via mocks.
+
+## Background
+
+### Current file: `src/session/context.ts`
+
+The file exports two functions:
+
+1. `extractText(content: unknown[]): string` — filters an array of content blocks to `TextContent` items and joins their `.text` values.
+   Used by `agent-runner.ts`, `message-formatters.ts`, and `buildParentContext` itself.
+2. `buildParentContext(ctx: SessionContext): string` — iterates session branch entries, formatting `message` entries (user/assistant) and `compaction` entries into a text representation prefixed with a header.
+
+The file also defines three local types (`MessageEntry`, `CompactionEntry`, `BranchEntry`) and one helper (`isTextContent`).
+
+### Callers
+
+- `buildParentContext` is called only from `parent-snapshot.ts` (where it is mocked in tests).
+- `extractText` is called from `agent-runner.ts`, `message-formatters.ts`, and internally within `buildParentContext`.
+
+### Existing tests
+
+There are no direct unit tests for `context.ts`.
+`parent-snapshot.test.ts` mocks `buildParentContext` entirely, so the formatting logic is currently untested.
+
+## Design Overview
+
+### Extracted formatters
+
+Each formatter takes a typed entry and returns `string | undefined` (undefined when the entry should be skipped):
+
+```typescript
+function formatMessageEntry(entry: MessageEntry): string | undefined {
+  const msg = entry.message;
+  const text =
+    typeof msg.content === "string"
+      ? msg.content
+      : extractText(msg.content);
+  if (!text.trim()) return undefined;
+  if (msg.role === "user") return `[User]: ${text.trim()}`;
+  if (msg.role === "assistant") return `[Assistant]: ${text.trim()}`;
+  return undefined; // skip toolResult and other roles
+}
+
+function formatCompactionEntry(entry: CompactionEntry): string | undefined {
+  return entry.summary ? `[Summary]: ${entry.summary}` : undefined;
+}
+```
+
+### Simplified orchestrator
+
+```typescript
+export function buildParentContext(ctx: SessionContext): string {
+  const entries = ctx.sessionManager.getBranch();
+  if (!entries || entries.length === 0) return "";
+
+  const parts = (entries as BranchEntry[])
+    .map(formatBranchEntry)
+    .filter((p): p is string => p !== undefined);
+
+  if (parts.length === 0) return "";
+
+  return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}
+```
+
+A thin dispatcher (`formatBranchEntry`) routes by `type`:
+
+```typescript
+function formatBranchEntry(entry: BranchEntry): string | undefined {
+  if (entry.type === "message") return formatMessageEntry(entry as MessageEntry);
+  if (entry.type === "compaction") return formatCompactionEntry(entry as CompactionEntry);
+  return undefined;
+}
+```
+
+### Complexity analysis
+
+- `formatMessageEntry`: 3 branches (string-vs-array, empty check, role) — estimated cognitive complexity ~4.
+- `formatCompactionEntry`: 1 branch — estimated cognitive complexity ~1.
+- `formatBranchEntry`: 2 branches — estimated cognitive complexity ~2.
+- `buildParentContext`: 2 branches (empty entries, empty parts) — estimated cognitive complexity ~3.
+
+All well under the < 10 target.
+
+## Module-Level Changes
+
+### `src/session/context.ts`
+
+1. Add `formatMessageEntry(entry: MessageEntry): string | undefined` — private helper.
+2. Add `formatCompactionEntry(entry: CompactionEntry): string | undefined` — private helper.
+3. Add `formatBranchEntry(entry: BranchEntry): string | undefined` — private dispatcher.
+4. Simplify `buildParentContext` body to use `map(formatBranchEntry).filter(...)`.
+5. No changes to exports — `buildParentContext` and `extractText` signatures are unchanged.
+6. No changes to local types (`MessageEntry`, `CompactionEntry`, `BranchEntry`) or `isTextContent`.
+
+### `test/session/context.test.ts` (new)
+
+Unit tests for:
+
+- `extractText` — string extraction from mixed content arrays.
+- `buildParentContext` — end-to-end formatting with user, assistant, compaction, and skipped entries.
+
+The formatters are private, so they are tested indirectly through `buildParentContext`.
+
+## Test Impact Analysis
+
+1. The new `context.test.ts` enables direct testing of formatting logic that was previously untested (mocked away in `parent-snapshot.test.ts`).
+2. No existing tests become redundant — `parent-snapshot.test.ts` tests snapshot assembly, not formatting.
+3. No existing tests need modification — the public API is unchanged.
+
+## TDD Order
+
+1. **Red → Green:** Add `test/session/context.test.ts` with tests for `extractText` — empty array, text-only, mixed content types, no text content.
+   Commit: `test: add extractText unit tests (#215)`
+
+2. **Red → Green:** Add tests for `buildParentContext` — empty branch, user messages, assistant messages, compaction entries with/without summary, mixed entry types, entries with empty text (skipped), non-message/non-compaction entries (skipped), string vs array content.
+   Commit: `test: add buildParentContext unit tests (#215)`
+
+3. **Refactor:** Extract `formatMessageEntry`, `formatCompactionEntry`, and `formatBranchEntry` from `buildParentContext`.
+   Simplify `buildParentContext` to map/filter/join.
+   All tests from steps 1–2 must still pass.
+   Commit: `refactor: decompose buildParentContext into per-entry formatters (#215)`
+
+## Risks and Mitigations
+
+| Risk                                                                                               | Mitigation                                                           |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Behavioral regression in formatting                                                                | Steps 1–2 lock in current behavior with tests before refactoring     |
+| Extracted helpers expose implementation details                                                    | Helpers are private (not exported); tested indirectly via public API |
+| `eslint-disable` comment for `no-unnecessary-condition` on `getBranch()` check may need adjustment | Preserve the comment — runtime nullability is documented             |
+
+## Open Questions
+
+None — the decomposition target and strategy are specified by the architecture roadmap.

package/docs/plans/0216-decompose-start-agent.md

@@ -0,0 +1,255 @@
+---
+issue: 216
+issue_title: "Decompose startAgent in agent-manager.ts (Phase 13, Step 3)"
+---
+
+# Decompose `startAgent` via `RunHandle` lifecycle object
+
+## Problem Statement
+
+`startAgent` in `agent-manager.ts` is a ~125-line method whose complexity comes not from length alone but from **mutable closure state shared across callbacks**.
+Two `let` variables (`unsubRecordObserver`, `detachParentSignal`) are written in one closure (`onSessionCreated` / setup block) and read in two others (`.then()` / `.catch()`).
+The `.then()` and `.catch()` handlers duplicate finalization logic (observer unsubscription, signal detach, worktree cleanup, background counter management).
+
+The original issue proposed extracting three methods (`handleRunCompletion`, `handleRunError`, `finalizeBackgroundRun`).
+This plan replaces that mechanical extraction with a structural fix: introduce a **`RunHandle` lifecycle object** that owns the per-run cleanup state, eliminating the mutable closures and the duplicated finalization.
+
+## Goals
+
+- Eliminate mutable closure state from `startAgent` — all per-run state lives on `RunHandle`.
+- Eliminate duplicated cleanup/finalization logic in `.then()`/`.catch()` via Tell-Don't-Ask on `RunHandle`.
+- Teach `WorktreeState` to self-clean via `performCleanup()`, removing the ask-tell dance from callers.
+- Reduce `startAgent` to a coordinator (~35–40 lines) with zero mutable `let` bindings.
+- Keep all 929 lines of existing `agent-manager.test.ts` passing unchanged.
+
+## Non-Goals
+
+- Extracting `RunHandle` to a separate file — it stays private in `agent-manager.ts` for now.
+- Changing the `runner.run()` options shape or the `RunResult` type.
+- Reducing `agent-manager.test.ts` duplication (tracked in #219).
+- Moving `pendingSteers` state to a different owner (the timing gap between `spawn()` and `startAgent()` makes this non-trivial).
+
+## Background
+
+### Closure tangle in `startAgent`
+
+```text
+unsubRecordObserver  ──written in──▶  onSessionCreated callback
+                     ──read in────▶  .then() handler
+                     ──read in────▶  .catch() handler
+
+detachParentSignal   ──written in──▶  setup block
+                     ──read via───▶  detach closure
+                     ──read in────▶  .then() handler (via detach)
+                     ──read in────▶  .catch() handler (via detach)
+```
+
+Both variables are resource-release handles — acquired at different times, released in the same place.
+They have no owner; they float as mutable `let` bindings shared across closures.
+
+### Duplicated finalization
+
+Both `.then()` and `.catch()` perform:
+
+1. `unsubRecordObserver?.(); detach();` — release listeners
+2. Worktree cleanup via `this.worktrees.cleanup()` + `record.worktreeState.recordCleanup()` — ask-tell dance
+3. Background finalization: `this.runningBackground--`, `this.observer?.onAgentCompleted(record)`, `this.drainQueue()`
+
+### Existing types
+
+- `RunResult` is already exported from `agent-runner.ts` — `RunHandle.complete()` can accept it directly.
+- `WorktreeManager.cleanup()` accepts `WorktreeInfo`, which `WorktreeState` satisfies structurally (has `path` and `branch`).
+- `record.description` is available on `AgentRecord` at cleanup time, so `RunHandle` doesn't need a separate `description` parameter.
+
+## Design Overview
+
+### `WorktreeState.performCleanup(worktrees, description)`
+
+Teach `WorktreeState` to orchestrate its own cleanup instead of requiring callers to do the ask-tell dance:
+
+```typescript
+performCleanup(worktrees: WorktreeManager, description: string): WorktreeCleanupResult {
+  const result = worktrees.cleanup(this, description);
+  this._cleanupResult = result;
+  return result;
+}
+```
+
+This replaces the two-step pattern at both call sites:
+
+```typescript
+// Before (caller orchestrates):
+const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
+record.worktreeState.recordCleanup(wtResult);
+
+// After (Tell-Don't-Ask):
+const wtResult = record.worktreeState.performCleanup(this.worktrees, record.description);
+```
+
+### `RunHandle` lifecycle object
+
+A short-lived object born when a run starts, consumed when it ends.
+Owns the two resource-release handles and exposes `complete()`/`fail()` as the only way to finish a run.
+
+```typescript
+class RunHandle {
+  private unsub?: () => void;
+  private detach?: () => void;
+  private onFinished?: () => void;
+
+  constructor(
+    private readonly record: AgentRecord,
+    private readonly worktrees: WorktreeManager,
+    onFinished?: () => void,
+  ) { this.onFinished = onFinished; }
+
+  wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void;
+  attachObserver(unsub: () => void): void;
+  complete(result: RunResult): string;
+  fail(err: unknown): void;
+
+  private detachListeners(): void;
+  private fireOnFinished(): void;  // idempotent — nulls callback after first call
+}
+```
+
+Key design decisions:
+
+1. **`onFinished` callback** — set once at construction, fires at most once (idempotent guard).
+   For background agents this is `() => this.finalizeBackgroundRun(record)`.
+   For foreground agents it is `undefined`.
+   This eliminates the `if (options.isBackground)` check from both `.then()` and `.catch()`.
+
+2. **`fireOnFinished` is idempotent** — if `complete()` throws (e.g., worktree cleanup fails on the success path) and the promise chain falls through to `.catch()` → `fail()`, the callback fires exactly once.
+   `AgentRecord`'s transition guards (`if (this._status !== "stopped")`) protect against double state transitions.
+
+3. **`complete()` returns `result.responseText`** — the branch-suffix text is stored on the record via `markCompleted(finalResult)` but the promise resolves with the original response text, matching current behavior.
+
+4. **No `worktrees` or `description` parameters on `complete()`/`fail()`** — `RunHandle` gets `worktrees` at construction; `description` comes from `record.description`.
+
+### `finalizeBackgroundRun(record)` on `AgentManager`
+
+Extracts the shared background finalization:
+
+```typescript
+private finalizeBackgroundRun(record: AgentRecord): void {
+  this.runningBackground--;
+  try { this.observer?.onAgentCompleted(record); }
+  catch (err) { debugLog("onAgentCompleted observer", err); }
+  this.drainQueue();
+}
+```
+
+Note: the current `.catch()` handler does not wrap `onAgentCompleted` in try/catch, but `.then()` does.
+The extracted method always wraps it — an observer error must never prevent `drainQueue()` from running.
+
+### Small helpers on `AgentManager`
+
+Two additional extractions to keep `startAgent` focused:
+
+```typescript
+private setupWorktree(
+  id: string, record: AgentRecord, isolation: IsolationMode | undefined,
+): string | undefined;
+
+private flushPendingSteers(id: string, session: AgentSession): void;
+```
+
+### Resulting `startAgent` shape
+
+After all extractions, `startAgent` becomes a coordinator with **zero mutable `let` bindings**:
+
+```typescript
+private startAgent(id: string, record: AgentRecord, { snapshot, type, prompt, options }: SpawnArgs) {
+  const worktreeCwd = this.setupWorktree(id, record, options.isolation);
+
+  record.markRunning(Date.now());
+  if (options.isBackground) this.runningBackground++;
+  this.observer?.onAgentStarted(record);
+
+  const handle = new RunHandle(
+    record, this.worktrees,
+    options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
+  );
+  handle.wireSignal(options.signal, () => this.abort(id));
+
+  const runConfig = this.getRunConfig?.();
+  record.promise = this.runner.run(snapshot, type, prompt, {
+    context: { exec: this.exec, registry: this.registry, cwd: worktreeCwd, parentSession: options.parentSession },
+    model: options.model, maxTurns: options.maxTurns,
+    defaultMaxTurns: runConfig?.defaultMaxTurns, graceTurns: runConfig?.graceTurns,
+    isolated: options.isolated, thinkingLevel: options.thinkingLevel,
+    signal: record.abortController!.signal,
+    onSessionCreated: (session) => {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
+      record.execution = { session, outputFile };
+      this.flushPendingSteers(id, session);
+      handle.attachObserver(subscribeRecordObserver(session, record, {
+        onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+      }));
+      options.onSessionCreated?.(session, record);
+    },
+  })
+    .then((result) => handle.complete(result))
+    .catch((err: unknown) => { handle.fail(err); return ""; });
+}
+```
+
+The `.then()` and `.catch()` are one-liners.
+The `onSessionCreated` callback captures only `const` references (no mutable closure state).
+The `record.promise` assignment moves inline (no intermediate `const promise`).
+
+## Module-Level Changes
+
+| File                                    | Change                                                                                                                                              |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/lifecycle/worktree-state.ts`       | Add `performCleanup(worktrees, description)` method                                                                                                 |
+| `src/lifecycle/agent-manager.ts`        | Add `RunHandle` class (private); add `finalizeBackgroundRun()`, `setupWorktree()`, `flushPendingSteers()` methods; rewrite `startAgent` to use them |
+| `test/lifecycle/worktree-state.test.ts` | Add tests for `performCleanup`                                                                                                                      |
+
+## Test Impact Analysis
+
+1. **New unit tests**: `WorktreeState.performCleanup` — directly testable with a mock `WorktreeManager`.
+   `RunHandle` is tested indirectly through the existing `agent-manager.test.ts` suite (929 lines, comprehensive coverage of success/error/worktree/signal/background paths).
+2. **Redundant tests**: None — all existing tests exercise the same public API (`spawn`, `spawnAndWait`, `abort`, `resume`).
+3. **Tests that must stay as-is**: All of `agent-manager.test.ts` — the refactoring is behavior-preserving and these tests verify every path through `RunHandle.complete()` and `RunHandle.fail()`.
+
+## TDD Order
+
+1. **`WorktreeState.performCleanup`** — red: test that `performCleanup` calls the manager, records the result, and returns it.
+   Green: implement `performCleanup` on `WorktreeState`.
+   Commit: `feat: add WorktreeState.performCleanup for self-cleanup (#216)`
+
+2. **Use `performCleanup` in `startAgent`** — refactor both cleanup sites in `.then()` and `.catch()` to use `record.worktreeState.performCleanup()`.
+   Verify: all existing agent-manager tests pass.
+   Commit: `refactor: use WorktreeState.performCleanup in startAgent (#216)`
+
+3. **Extract `finalizeBackgroundRun`** — extract the shared background finalization block.
+   Add try/catch around `onAgentCompleted` (unifying the asymmetry between `.then()` and `.catch()`).
+   Verify: all existing agent-manager tests pass.
+   Commit: `refactor: extract finalizeBackgroundRun from startAgent (#216)`
+
+4. **Introduce `RunHandle` and rewire `startAgent`** — add `RunHandle` class with `wireSignal`, `attachObserver`, `complete`, `fail`, `detachListeners`, `fireOnFinished`.
+   Extract `setupWorktree` and `flushPendingSteers`.
+   Rewrite `startAgent` to use `RunHandle`, eliminating all mutable `let` bindings.
+   Verify: all existing agent-manager tests pass.
+   Run `pnpm run check` to verify types.
+   Commit: `refactor: introduce RunHandle lifecycle object in startAgent (#216)`
+
+## Risks and Mitigations
+
+1. **`complete()` throws after `fireOnFinished`** — if worktree cleanup succeeds, state transition succeeds, but `fireOnFinished` itself throws (observer error), the `.catch()` handler calls `fail()` which calls `fireOnFinished` again.
+   Mitigation: `fireOnFinished` is idempotent (nulls callback after first call), and `finalizeBackgroundRun` wraps `onAgentCompleted` in try/catch.
+   `AgentRecord` transition guards prevent double state transitions.
+
+2. **`complete()` throws before state transition** — e.g., `worktrees.cleanup()` throws on the success path.
+   The `.catch()` handler calls `fail()`, which marks the record as error and does best-effort worktree cleanup.
+   This matches current behavior (the success-path worktree cleanup is not wrapped in try/catch today).
+
+3. **Subtle behavior change in error-path observer notification** — current `.catch()` does not wrap `onAgentCompleted` in try/catch; `finalizeBackgroundRun` does.
+   This is a minor hardening, not a behavior change — an observer throwing during error finalization would previously have prevented `drainQueue()` from running.
+
+## Open Questions
+
+- None — the design is straightforward and all decisions are driven by eliminating the identified smells.

package/docs/retro/0215-decompose-build-parent-context.md

@@ -0,0 +1,61 @@
+---
+issue: 215
+issue_title: "Decompose buildParentContext (cognitive 30) (Phase 13, Step 2)"
+---
+
+# Retro: #215 — Decompose buildParentContext
+
+## Stage: Planning (2026-05-25T12:00:00Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to decompose `buildParentContext` in `src/session/context.ts`.
+Steps 1–2 add tests locking current behavior for `extractText` and `buildParentContext`; step 3 extracts three private helpers (`formatMessageEntry`, `formatCompactionEntry`, `formatBranchEntry`) and simplifies the orchestrator to map/filter/join.
+
+### Observations
+
+- No existing unit tests cover `context.ts` — `parent-snapshot.test.ts` mocks `buildParentContext` entirely, so the formatting logic is currently untested.
+- The decomposition is straightforward with no design ambiguity; the architecture roadmap specifies the exact extraction targets.
+- All extracted helpers remain private (not exported), keeping the public API surface unchanged.
+- The `eslint-disable` comment on the `getBranch()` nullability check must be preserved through the refactoring step.
+
+## Stage: Implementation — TDD (2026-05-25T22:36:00Z)
+
+### Session summary
+
+Completed all 3 TDD steps: 2 test-only commits locking `extractText` (5 tests) and `buildParentContext` (14 tests) behavior, then a refactor commit extracting `formatMessageEntry`, `formatCompactionEntry`, and `formatBranchEntry`.
+Test count increased from 939 to 958 (+19).
+All checks green: full suite, `pnpm run check`, `pnpm run lint`, `pnpm fallow dead-code`.
+
+### Observations
+
+- Because `extractText` and `buildParentContext` already existed, both test steps passed immediately (no red phase) — this is correct for behavior-locking tests before a refactor.
+- The `makeCtx` helper in the test file creates a minimal `SessionContext` satisfying only `sessionManager.getBranch()`; the extra required fields (`cwd`, `model`, `modelRegistry`, `getSystemPrompt`) are satisfied with stubs.
+- The `eslint-disable` comment on the `getBranch()` nullability check was preserved unchanged through the refactor.
+- No deviations from the plan.
+
+## Stage: Final Retrospective (2026-05-26T02:50:00Z)
+
+### Session summary
+
+Completed the full issue lifecycle (plan → TDD → ship → retro) in a single session with zero rework or user corrections.
+Released as `pi-subagents-v7.5.1`.
+Test count: 939 → 958 (+19 tests in new `test/session/context.test.ts`).
+
+### Observations
+
+#### What went well
+
+- Zero-deviation execution: the architecture roadmap specified exact decomposition targets, the plan translated them into 3 TDD steps, and implementation was a straight transcription.
+- Multi-model cost efficiency: `claude-sonnet-4-6` for planning/TDD, `deepseek-v4-flash` for shipping (~$0.002 for the entire ship workflow), `claude-opus-4-6` for retro synthesis.
+- Incremental verification at every stage: per-file test runs after each TDD step, full suite + `pnpm run check` + `pnpm run lint` + `pnpm fallow dead-code` after the last step, repo-root lint before push.
+
+#### What caused friction (agent side)
+
+None identified.
+The issue was well-scoped, the architecture roadmap was unambiguous, and the existing code had no surprising edge cases.
+
+#### What caused friction (user side)
+
+None identified.
+The user ran four prompt commands in sequence (`/plan-issue`, `/tdd-plan`, `/ship-issue`, `/retro`) with no corrections or redirections needed.

package/docs/retro/0216-decompose-start-agent.md

@@ -0,0 +1,43 @@
+---
+issue: 216
+issue_title: "Decompose startAgent in agent-manager.ts (Phase 13, Step 3)"
+---
+
+# Retro: #216 — Decompose startAgent in agent-manager.ts
+
+## Stage: Planning (2026-05-25T20:00:00Z)
+
+### Session summary
+
+Analyzed the `startAgent` method's structural problems beyond surface-level length.
+The original issue proposed extracting three methods (`handleRunCompletion`, `handleRunError`, `finalizeBackgroundRun`).
+Through design discussion, identified the root cause as **mutable closure state without an owner** — two `let` variables shared across three closures — and proposed a `RunHandle` lifecycle object as the missing collaborator.
+
+### Observations
+
+- The initial mechanical-extraction approach (3 methods) wouldn't have eliminated the mutable closure variables — `.then()`/`.catch()` would still close over `unsubRecordObserver` and `detach`.
+  `RunHandle` eliminates these entirely by owning the resource-release handles.
+- `WorktreeState` has an ask-tell smell: callers call `worktrees.cleanup()` then `worktreeState.recordCleanup()`.
+  Adding `performCleanup()` is a small prep step that simplifies `RunHandle`'s completion/error methods.
+- `record.description` is already available on `AgentRecord`, so `RunHandle` doesn't need `description` as a separate dependency — it can use `record.description` for worktree cleanup.
+- `RunResult` is already exported from `agent-runner.ts`, so `RunHandle.complete()` can accept it directly without a new type.
+- The `.catch()` handler doesn't wrap `onAgentCompleted` in try/catch while `.then()` does — `finalizeBackgroundRun` unifies this by always wrapping, preventing an observer error from blocking `drainQueue()`.
+- `fireOnFinished` idempotency is important: if `complete()` throws after worktree cleanup but before returning, `.catch()` → `fail()` must not double-fire the background finalization.
+  `AgentRecord`'s transition guards (`if (this._status !== "stopped")`) provide a second safety net.
+
+## Stage: Implementation — TDD (2026-05-25T23:20:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps across 5 commits (one extra for the type-annotation fixup caught by `pnpm run check`).
+Added 4 new tests for `WorktreeState.performCleanup`; total test count rose from 958 to 962.
+All 60 test files pass; `pnpm run check`, `pnpm run lint`, and `pnpm fallow dead-code` all clean.
+
+### Observations
+
+- One deviation from the plan: the `makeWorktrees` test helper in `worktree-state.test.ts` needed an explicit `WorktreeCleanupResult` type annotation on its `result` parameter — TypeScript inferred `{ hasChanges: boolean }` (no optional `branch`/`path` fields) from the default argument, which caused a type error on the call site that passed `{ hasChanges: true, branch: "pi-agent-1" }`.
+  Fixed in the same commit as the `RunHandle` step.
+- `RunHandle` landed exactly as designed: `wireSignal`, `attachObserver`, `complete`, `fail`, `releaseListeners`, `fireOnFinished` (idempotent). `startAgent` is now ~40 lines with zero mutable `let` bindings and one-liner `.then()`/`.catch()` handlers.
+- `flushPendingSteers` and `setupWorktree` extracted cleanly — each about 8 lines, no surprises.
+- The `WorktreeCleanupResult` import needed to be added to the test file alongside the existing `WorktreeManager` import for the type annotation fix — minor but worth noting for the next engineer.
+- Architecture doc updated: Step 3 entry now reflects `RunHandle` rather than the original `handleRunCompletion`/`handleRunError` proposal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.5.0",
+  "version": "7.6.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-manager.ts

@@ -12,7 +12,7 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { debugLog } from "#src/debug";
 import { AgentRecord } from "#src/lifecycle/agent-record";
-import type { AgentRunner } from "#src/lifecycle/agent-runner";
+import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 import { WorktreeState } from "#src/lifecycle/worktree-state";
@@ -21,6 +21,95 @@ import { subscribeRecordObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
+/**
+ * RunHandle — per-run lifecycle object that owns cleanup state.
+ *
+ * Owns the observer unsubscribe and parent-signal detach handles acquired during
+ * a run. Exposes `complete()` and `fail()` as the only way to finish a run,
+ * eliminating mutable closure variables from `startAgent`.
+ * `fireOnFinished` is idempotent — safe to call from both success and error paths.
+ */
+class RunHandle {
+  private unsub?: () => void;
+  private detachFn?: () => void;
+  private onFinished?: () => void;
+
+  constructor(
+    private readonly record: AgentRecord,
+    private readonly worktrees: WorktreeManager,
+    onFinished?: () => void,
+  ) {
+    this.onFinished = onFinished;
+  }
+
+  /** Wire a parent AbortSignal so it stops this agent when fired. */
+  wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
+    if (!signal) return;
+    const listener = () => onAbort();
+    signal.addEventListener("abort", listener, { once: true });
+    this.detachFn = () => signal.removeEventListener("abort", listener);
+  }
+
+  /** Store the record-observer unsubscribe handle (called from onSessionCreated). */
+  attachObserver(unsub: () => void): void {
+    this.unsub = unsub;
+  }
+
+  /** Complete a run successfully — clean up, transition record, fire onFinished. */
+  complete(result: RunResult): string {
+    this.releaseListeners();
+
+    let finalResult = result.responseText;
+    if (this.record.worktreeState) {
+      const wtResult = this.record.worktreeState.performCleanup(this.worktrees, this.record.description);
+      if (wtResult.hasChanges && wtResult.branch) {
+        finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+      }
+    }
+
+    if (result.aborted) this.record.markAborted(finalResult);
+    else if (result.steered) this.record.markSteered(finalResult);
+    else this.record.markCompleted(finalResult);
+
+    // Update execution with the final session/outputFile from the runner
+    this.record.execution = {
+      session: result.session,
+      outputFile: result.sessionFile ?? this.record.execution?.outputFile,
+    };
+
+    this.fireOnFinished();
+    return result.responseText;
+  }
+
+  /** Fail a run — mark error, best-effort worktree cleanup, fire onFinished. */
+  fail(err: unknown): void {
+    this.record.markError(err);
+    this.releaseListeners();
+
+    if (this.record.worktreeState) {
+      try {
+        this.record.worktreeState.performCleanup(this.worktrees, this.record.description);
+      } catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
+    }
+
+    this.fireOnFinished();
+  }
+
+  private releaseListeners(): void {
+    this.unsub?.();
+    this.unsub = undefined;
+    this.detachFn?.();
+    this.detachFn = undefined;
+  }
+
+  /** Fire the onFinished callback at most once. */
+  private fireOnFinished(): void {
+    const fn = this.onFinished;
+    this.onFinished = undefined;
+    fn?.();
+  }
+}
+
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
 /** Observer interface for agent lifecycle notifications. */
@@ -192,39 +281,20 @@ export class AgentManager {
 
   /** Actually start an agent (called immediately or from queue drain). */
   private startAgent(id: string, record: AgentRecord, { snapshot, type, prompt, options }: SpawnArgs) {
-    // Worktree isolation: try to create a temporary git worktree. Strict —
-    // fail loud if not possible (no silent fallback to main tree). Done
-    // BEFORE state mutation so a throw doesn't leave the record half-running.
-    let worktreeCwd: string | undefined;
-    if (options.isolation === "worktree") {
-      const wt = this.worktrees.create(id);
-      if (!wt) {
-        throw new Error(
-          'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
-          'Initialize git and commit at least once, or omit `isolation`.',
-        );
-      }
-      record.worktreeState = new WorktreeState(wt);
-      worktreeCwd = wt.path;
-    }
+    const worktreeCwd = this.setupWorktree(id, record, options.isolation);
 
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
     this.observer?.onAgentStarted(record);
 
-    // Wire parent abort signal to stop the subagent when the parent is interrupted
-    let detachParentSignal: (() => void) | undefined;
-    if (options.signal) {
-      const onParentAbort = () => this.abort(id);
-      options.signal.addEventListener("abort", onParentAbort, { once: true });
-      detachParentSignal = () => options.signal!.removeEventListener("abort", onParentAbort);
-    }
-    const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
-
-    let unsubRecordObserver: (() => void) | undefined;
+    const handle = new RunHandle(
+      record, this.worktrees,
+      options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
+    );
+    handle.wireSignal(options.signal, () => this.abort(id));
 
     const runConfig = this.getRunConfig?.();
-    const promise = this.runner.run(snapshot, type, prompt, {
+    record.promise = this.runner.run(snapshot, type, prompt, {
       context: {
         exec: this.exec,
         registry: this.registry,
@@ -243,76 +313,49 @@ export class AgentManager {
         // before the run completes (e.g. in background agent status messages).
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
         const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
-        // Set the execution-state collaborator — born complete at session creation.
         record.execution = { session, outputFile };
-        // Flush any steers that arrived before the session was ready
-        const buffered = this.pendingSteers.get(id);
-        if (buffered?.length) {
-          for (const msg of buffered) {
-            session.steer(msg).catch(() => {});
-          }
-          this.pendingSteers.delete(id);
-        }
-        // Subscribe record observer for stats accumulation
-        unsubRecordObserver = subscribeRecordObserver(session, record, {
+        this.flushPendingSteers(id, session);
+        handle.attachObserver(subscribeRecordObserver(session, record, {
           onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-        });
+        }));
         options.onSessionCreated?.(session, record);
       },
     })
-      .then(({ responseText, session, aborted, steered, sessionFile }) => {
-        unsubRecordObserver?.();
-        detach();
-
-        // Clean up worktree before transition so the final result includes branch text
-        let finalResult = responseText;
-        if (record.worktreeState) {
-          const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
-          record.worktreeState.recordCleanup(wtResult);
-          if (wtResult.hasChanges && wtResult.branch) {
-            finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
-          }
-        }
-
-        // Transition — guards against overwriting externally-stopped status
-        if (aborted) record.markAborted(finalResult);
-        else if (steered) record.markSteered(finalResult);
-        else record.markCompleted(finalResult);
-
-        // Update execution collaborator with final session/outputFile from runner
-        record.execution = { session, outputFile: sessionFile ?? record.execution?.outputFile };
-
-        if (options.isBackground) {
-          this.runningBackground--;
-          try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
-          this.drainQueue();
-        }
-        return responseText;
-      })
-      .catch((err: unknown) => {
-        record.markError(err);
-
-        unsubRecordObserver?.();
-        detach();
-
-        // Best-effort worktree cleanup on error
-        if (record.worktreeState) {
-          try {
-            const wtResult = this.worktrees.cleanup(record.worktreeState, options.description);
-            record.worktreeState.recordCleanup(wtResult);
+      .then((result) => handle.complete(result))
+      .catch((err: unknown) => { handle.fail(err); return ""; });
+  }
 
-          } catch (err) { debugLog("cleanupWorktree on agent error", err); }
-        }
+  /** Create a worktree for isolated agents. Throws (strict) if isolation is requested but impossible. */
+  private setupWorktree(
+    id: string, record: AgentRecord, isolation: IsolationMode | undefined,
+  ): string | undefined {
+    if (isolation !== "worktree") return undefined;
+    const wt = this.worktrees.create(id);
+    if (!wt) {
+      throw new Error(
+        'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+        'Initialize git and commit at least once, or omit `isolation`.',
+      );
+    }
+    record.worktreeState = new WorktreeState(wt);
+    return wt.path;
+  }
 
-        if (options.isBackground) {
-          this.runningBackground--;
-          this.observer?.onAgentCompleted(record);
-          this.drainQueue();
-        }
-        return "";
-      });
+  /** Flush any steers buffered before the session was ready. */
+  private flushPendingSteers(id: string, session: AgentSession): void {
+    const buffered = this.pendingSteers.get(id);
+    if (!buffered?.length) return;
+    for (const msg of buffered) {
+      session.steer(msg).catch(() => {});
+    }
+    this.pendingSteers.delete(id);
+  }
 
-    record.promise = promise;
+  /** Decrement background counter, notify observer (crash-safe), and drain the queue. */
+  private finalizeBackgroundRun(record: AgentRecord): void {
+    this.runningBackground--;
+    try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
+    this.drainQueue();
   }
 
   /** Start queued agents up to the concurrency limit. */

package/src/lifecycle/worktree-state.ts

@@ -6,7 +6,7 @@
  * cleanupResult is recorded once at completion or error — it is not set at construction.
  */
 
-import type { WorktreeCleanupResult, WorktreeInfo } from "#src/lifecycle/worktree";
+import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
 
 export type { WorktreeCleanupResult, WorktreeInfo };
 
@@ -32,4 +32,14 @@ export class WorktreeState {
 	recordCleanup(result: WorktreeCleanupResult): void {
 		this._cleanupResult = result;
 	}
+
+	/**
+	 * Perform worktree cleanup and record the result.
+	 * Tell-Don't-Ask: callers no longer need to orchestrate cleanup + recordCleanup separately.
+	 */
+	performCleanup(worktrees: WorktreeManager, description: string): WorktreeCleanupResult {
+		const result = worktrees.cleanup(this, description);
+		this._cleanupResult = result;
+		return result;
+	}
 }

package/src/session/context.ts

@@ -30,6 +30,28 @@ export function extractText(content: unknown[]): string {
     .join("\n");
 }
 
+/** Format a message entry (user/assistant); returns undefined for roles to skip. */
+function formatMessageEntry(entry: MessageEntry): string | undefined {
+  const msg = entry.message;
+  const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+  if (!text.trim()) return undefined;
+  if (msg.role === "user") return `[User]: ${text.trim()}`;
+  if (msg.role === "assistant") return `[Assistant]: ${text.trim()}`;
+  return undefined; // skip toolResult and other roles
+}
+
+/** Format a compaction entry; returns undefined when no summary is present. */
+function formatCompactionEntry(entry: CompactionEntry): string | undefined {
+  return entry.summary ? `[Summary]: ${entry.summary}` : undefined;
+}
+
+/** Dispatch a branch entry to the appropriate formatter. */
+function formatBranchEntry(entry: BranchEntry): string | undefined {
+  if (entry.type === "message") return formatMessageEntry(entry as MessageEntry);
+  if (entry.type === "compaction") return formatCompactionEntry(entry as CompactionEntry);
+  return undefined;
+}
+
 /**
  * Build a text representation of the parent conversation context.
  * Used when inherit_context is true to give the subagent visibility
@@ -40,30 +62,9 @@ export function buildParentContext(ctx: SessionContext): string {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
   if (!entries || entries.length === 0) return "";
 
-  const parts: string[] = [];
-
-  for (const rawEntry of entries as BranchEntry[]) {
-    if (rawEntry.type === "message") {
-      const entry = rawEntry as MessageEntry;
-      const msg = entry.message;
-      if (msg.role === "user") {
-        const text = typeof msg.content === "string"
-          ? msg.content
-          : extractText(msg.content);
-        if (text.trim()) parts.push(`[User]: ${text.trim()}`);
-      } else if (msg.role === "assistant") {
-        const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
-        if (text.trim()) parts.push(`[Assistant]: ${text.trim()}`);
-      }
-      // Skip toolResult messages — too verbose for context
-    } else if (rawEntry.type === "compaction") {
-      // Include compaction summaries — they're already condensed
-      const entry = rawEntry as CompactionEntry;
-      if (entry.summary) {
-        parts.push(`[Summary]: ${entry.summary}`);
-      }
-    }
-  }
+  const parts = (entries as BranchEntry[])
+    .map(formatBranchEntry)
+    .filter((p): p is string => p !== undefined);
 
   if (parts.length === 0) return "";