@gotgenes/pi-subagents 7.5.1 → 7.7.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.6.0...pi-subagents-v7.7.0) (2026-05-26)
+
+
+### Features
+
+* extract writeAgentFile overwrite-guard function ([#217](https://github.com/gotgenes/pi-packages/issues/217)) ([141df78](https://github.com/gotgenes/pi-packages/commit/141df784ea5cf6c5286a1a6e9861daa259fa4e1c))
+
+
+### Documentation
+
+* add Phase 14 roadmap — Agent domain model, scheduling extraction ([#227](https://github.com/gotgenes/pi-packages/issues/227)–[#232](https://github.com/gotgenes/pi-packages/issues/232)) ([089d9e0](https://github.com/gotgenes/pi-packages/commit/089d9e0becde693c2795ca590d987a4d2b169edc))
+* plan extract overwrite guard from UI ([#217](https://github.com/gotgenes/pi-packages/issues/217)) ([89de32c](https://github.com/gotgenes/pi-packages/commit/89de32c6a1bbb84fb0e252fecaa6edf79dc9b5b3))
+* **retro:** add planning stage notes for issue [#217](https://github.com/gotgenes/pi-packages/issues/217) ([b1a854f](https://github.com/gotgenes/pi-packages/commit/b1a854f18ad133542c5f3e3ab4400ed753ba7c8c))
+* **retro:** add retro notes for issue [#216](https://github.com/gotgenes/pi-packages/issues/216) ([dcb86ea](https://github.com/gotgenes/pi-packages/commit/dcb86eace93d2f68acf39d6f0b8e7d64aaf982d1))
+* **retro:** add TDD stage notes for issue [#217](https://github.com/gotgenes/pi-packages/issues/217) ([7305a28](https://github.com/gotgenes/pi-packages/commit/7305a281f89258d8898fb13f02ba051b58513a71))
+* update architecture for writeAgentFile extraction ([#217](https://github.com/gotgenes/pi-packages/issues/217)) ([298a819](https://github.com/gotgenes/pi-packages/commit/298a8196de5b8dc507bb08ead57a6c712a50c3f0))
+
+## [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)
 
 

package/docs/architecture/architecture.md

@@ -294,6 +294,7 @@ src/
 │   ├── message-formatters.ts       pure per-message-type formatters (extracted from conversation-viewer)
 │   ├── agent-activity-tracker.ts   live activity state tracker
 │   ├── agent-file-ops.ts           filesystem abstraction
+│   ├── agent-file-writer.ts        overwrite-guard + write + reload + notify helper
 │   ├── ui-observer.ts              session-event observer for streaming
 │   └── display.ts                  pure formatters and shared types
 │
@@ -491,7 +492,7 @@ Once structural work stabilizes, these are expected to cool.
 ### Production duplication
 
 The prior clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
-One 20-line clone group remains between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` — both implement the same overwrite-guard + write + reload + notify pattern.
+The 20-line clone group between `agent-config-editor.ts` and `agent-creation-wizard.ts` was resolved in #217 — extracted into `ui/agent-file-writer.ts` (`writeAgentFile`). 0 production clone groups remain.
 
 ### Proposed bag decompositions
 
@@ -652,20 +653,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]
 
@@ -724,6 +728,112 @@ flowchart LR
 2. **Track B — Complexity and coupling** (Steps 2, 5): independent, can proceed in parallel with Track A.
 3. **Track C — Duplication** (Steps 4, 6): Step 4 depends on Step 1 (overwrite guard lives in files being converted); Step 6 depends on Steps 1 and 3 (production code they test changes first).
 
+## Improvement roadmap (Phase 14)
+
+Phase 14 addresses the anemic domain model in the lifecycle layer.
+`AgentRecord` is a data bag — identity, status transitions, and stats — but no behavior.
+`AgentManager` reaches into records 37 times, doing work that belongs on the agent.
+Per-agent state (pending steers, abort logic, run lifecycle) is scattered across the manager, `RunHandle`, and a manager-level Map.
+
+The scheduling concern (queue, concurrency counter, drain) is tangled into `AgentManager` alongside collection management and run orchestration.
+`notifyConcurrencyChanged()` is a scheduling method exposed as a public API so settings can poke the queue — a cross-concern leak.
+
+### Findings summary
+
+| Finding                                                       | Category     | Impact | Risk | Priority |
+| ------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
+| `AgentRecord` is anemic — no behavior, manager reaches in 37× | B: Oversized | 5      | 3    | 15       |
+| Scheduling tangled into `AgentManager` (3 fields, 3 methods)  | A: Coupling  | 4      | 2    | 12       |
+| `startAgent` uses `.then()`/`.catch()` instead of async/await | C: Callbacks | 3      | 2    | 10       |
+| `onSessionCreated` callback flows through 3 layers            | C: Callbacks | 3      | 2    | 10       |
+| `resume()` duplicates observer subscribe/unsubscribe pattern  | A: Redundant | 2      | 1    | 8        |
+| `exec`/`registry` relay-only deps on `AgentManager`           | C: Coupling  | 2      | 1    | 6        |
+
+### Step 1: Evolve AgentRecord into Agent with behavior — [#227]
+
+Rename `AgentRecord` → `Agent` (or wrap it).
+Move per-agent behavior from `AgentManager` into the agent:
+
+1. `Agent.abort()` — absorbs status-check + controller.abort + markStopped.
+2. `Agent.queueSteer(message)` / `Agent.flushPendingSteers(session)` — moves pending steers from manager map to per-agent array.
+3. `Agent.setupWorktree(worktrees, isolation)` — moves worktree creation into the agent.
+
+- Target: `src/lifecycle/agent-record.ts` → `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`
+- Smell: B (anemic domain model) + C (manager reaching into records)
+- Outcome: `AgentManager` delegates via Tell-Don't-Ask; per-agent state lives on the agent
+
+### Step 2: Convert startAgent to async/await — [#228]
+
+Convert `startAgent` from synchronous (returns void, assigns `record.promise` to a `.then()`/`.catch()` chain) to `async` (returns `Promise<void>`, uses try/catch).
+`spawn()` assigns `record.promise = this.startAgent(...)` instead of calling `startAgent()` synchronously.
+
+- Depends on: #227
+- Target: `src/lifecycle/agent-manager.ts`
+- Smell: C (raw promise callbacks)
+- Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`
+
+### Step 3: Replace onSessionCreated callback with observer method — [#229]
+
+Add `onSessionCreated(agent, session)` to `AgentManagerObserver`.
+Remove the `onSessionCreated` callback from `AgentSpawnConfig`.
+Tool-layer code subscribes via the observer pattern instead of passing callbacks through the spawn config.
+
+- Target: `src/lifecycle/agent-manager.ts`, `src/tools/background-spawner.ts`, `src/tools/foreground-runner.ts`
+- Smell: C (callback flowing through 3 layers)
+- Outcome: `AgentSpawnConfig` loses one callback field; session notification uses the observer pattern
+
+### Step 4: Extract ConcurrencyQueue from AgentManager — [#230]
+
+Extract `queue[]`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()` into a `ConcurrencyQueue` class.
+`SettingsManager` talks to the queue directly — `notifyConcurrencyChanged()` is eliminated from `AgentManager`.
+
+- Target: new `src/lifecycle/concurrency-queue.ts`, `src/lifecycle/agent-manager.ts`, `src/index.ts`
+- Smell: A (tangled concerns) + C (cross-concern leak via `notifyConcurrencyChanged`)
+- Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable
+
+### Step 5: Push exec/registry relay deps to runner construction — [#231]
+
+`AgentManager` receives `exec` and `registry` in its constructor but only relays them to `runner.run()` via `context`.
+Move them to `ConcreteAgentRunner` construction.
+
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent-runner.ts`, `src/index.ts`
+- Smell: C (relay-only dependencies)
+- Outcome: `AgentManager` loses 2 fields; `AgentManagerOptions` shrinks from 7 to 5 fields
+
+### Step 6: Unify resume() with RunHandle pattern — [#232]
+
+After #227 moves `RunHandle` ownership to the `Agent`, `resume()` on `AgentManager` becomes a 4-line delegation to `agent.resume(runner, prompt, signal)`.
+The agent manages its own observer subscription lifecycle.
+
+- Depends on: #227, #228
+- Target: `src/lifecycle/agent-manager.ts`
+- Smell: A (duplicated observer subscribe/unsubscribe pattern)
+- Outcome: no manual `subscribeRecordObserver` / try-finally in the manager
+
+### Step dependency diagram
+
+```mermaid
+flowchart LR
+    S1["Step 1\nAgent with behavior"]
+    S2["Step 2\nasync startAgent"]
+    S3["Step 3\nonSessionCreated observer"]
+    S4["Step 4\nConcurrencyQueue"]
+    S5["Step 5\nrelay deps"]
+    S6["Step 6\nresume unification"]
+
+    S1 --> S2
+    S1 --> S6
+    S2 --> S6
+    S3 ~~~ S4
+    S4 ~~~ S5
+```
+
+### Tracks
+
+1. **Track A — Domain model** (Steps 1, 2, 6): Agent with behavior, async runs, resume unification.
+   Sequential — each depends on the previous.
+2. **Track B — Decoupling** (Steps 3, 4, 5): independent, can proceed in parallel with Track A.
+
 ## Refactoring history
 
 Phases 1–5 and 7–12 are complete.
@@ -761,6 +871,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 11           | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                         |
 | Phase 12           | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                  |
 | Phase 13           | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                 |
+| Phase 14           | #227, #228, #229, #230, #231, #232                         | Agent domain model, async startAgent, onSessionCreated observer, ConcurrencyQueue, relay deps, resume unification                                        |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 

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/plans/0217-extract-overwrite-guard.md

@@ -0,0 +1,176 @@
+---
+issue: 217
+issue_title: "Extract overwrite guard from UI (Phase 13, Step 4)"
+---
+
+# Extract overwrite guard from UI
+
+## Problem Statement
+
+The overwrite-guard + write + reload + notify pattern is duplicated between `AgentConfigEditor.ejectAgent` and `AgentCreationWizard.showManualWizard`.
+Both sites check file existence, prompt for overwrite confirmation, write the file, reload the agent registry, and notify the user — identical logic with only the content and notification label differing.
+This is the last remaining production clone group in the package.
+
+## Goals
+
+- Extract a shared `writeAgentFile` function into a new `src/ui/agent-file-writer.ts` module.
+- Replace both call sites (`ejectAgent`, `showManualWizard`) with calls to the shared function.
+- Achieve 0 production clone groups.
+- Unit-test the extracted function in isolation.
+
+## Non-Goals
+
+- Extracting the partial overwrite guard in `showGenerateWizard` — that flow has different lifecycle semantics (the spawned agent does the write, and the post-write check is conditional on file existence).
+  The guard-only overlap is 5 lines, not worth a separate abstraction.
+- Reducing test duplication in `agent-config-editor.test.ts` or `agent-creation-wizard.test.ts` — tracked in #219 (Phase 13, Step 6).
+- Changing the `disableAgent` write path — it has no overwrite guard and different notification semantics.
+
+## Background
+
+### Existing modules
+
+| Module                            | Role                                                                |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `src/ui/agent-config-editor.ts`   | Agent detail view with edit/delete/eject/disable/enable transitions |
+| `src/ui/agent-creation-wizard.ts` | AI-generation and manual-form agent creation flows                  |
+| `src/ui/agent-file-ops.ts`        | Filesystem abstraction (`AgentFileOps` interface + production impl) |
+| `src/ui/agent-menu.ts`            | `/agents` slash command menu; defines `MenuUI` interface            |
+
+### Duplicated pattern
+
+Both sites execute this sequence:
+
+```typescript
+if (this.fileOps.exists(targetPath)) {
+  const overwrite = await ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+  if (!overwrite) return;
+}
+this.fileOps.write(targetPath, content);
+this.registry.reload();
+ui.notify(`${label} ${targetPath}`, "info");
+```
+
+The only differences are the `content` argument and the notification `label`.
+
+### Dependency
+
+Issue #214 (closure-to-class conversion) is closed — both consumer files are already class-based.
+
+## Design Overview
+
+### Extracted function
+
+`writeAgentFile` is a free async function — not a class method — because both consumers are classes with different constructor signatures and no shared base.
+The function takes narrow interface parameters following ISP: each parameter type declares only the methods the function calls.
+
+```typescript
+/** Minimal file operations for the overwrite-guard-and-write pattern. */
+interface FileWriter {
+  exists(filePath: string): boolean;
+  write(filePath: string, content: string): void;
+}
+
+/** Minimal UI for the overwrite-guard-and-write pattern. */
+interface WriterUI {
+  confirm(title: string, message: string): Promise<boolean>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+}
+
+/** Registry that can be reloaded after file changes. */
+interface Reloadable {
+  reload(): void;
+}
+
+/**
+ * Write an agent file with an overwrite guard.
+ *
+ * Returns true if the file was written, false if the user declined to overwrite.
+ */
+export async function writeAgentFile(
+  fileOps: FileWriter,
+  ui: WriterUI,
+  registry: Reloadable,
+  targetPath: string,
+  content: string,
+  label: string,
+): Promise<boolean>;
+```
+
+### Consumer call sites
+
+In `AgentConfigEditor.ejectAgent`:
+
+```typescript
+await writeAgentFile(this.fileOps, ui, this.registry, targetPath, buildEjectContent(cfg), `Ejected ${name} to`);
+```
+
+In `AgentCreationWizard.showManualWizard`:
+
+```typescript
+await writeAgentFile(this.fileOps, ui, this.registry, targetPath, content, "Created");
+```
+
+Both callers already hold `this.fileOps` and `this.registry` as private fields, and receive `ui` as a method parameter — no wiring changes needed.
+
+### ISP verification
+
+The `FileWriter` interface uses 2 of `AgentFileOps`'s 6 methods (`exists`, `write`).
+The `WriterUI` interface uses 2 of `MenuUI`'s 6 methods (`confirm`, `notify`).
+The `Reloadable` interface uses 1 method (`reload`).
+All three are structurally satisfied by the existing types without adapter code.
+
+## Module-Level Changes
+
+1. **New `src/ui/agent-file-writer.ts`** — exports `writeAgentFile` function and the three narrow interfaces (`FileWriter`, `WriterUI`, `Reloadable`).
+2. **`src/ui/agent-config-editor.ts`** — `ejectAgent` method: replace the inline overwrite-guard + write + reload + notify block with a call to `writeAgentFile`.
+   The `join(targetDir, ...)` and `buildEjectContent(cfg)` calls remain in the caller.
+3. **`src/ui/agent-creation-wizard.ts`** — `showManualWizard` method: replace the inline overwrite-guard + write + reload + notify block with a call to `writeAgentFile`.
+   The `join(targetDir, ...)` and content-assembly calls remain in the caller.
+4. **New `test/ui/agent-file-writer.test.ts`** — unit tests for `writeAgentFile`.
+5. **`docs/architecture/architecture.md`** — add `agent-file-writer.ts` to the `ui/` layout listing and update the production-duplication section to mark the clone group as resolved.
+
+## Test Impact Analysis
+
+1. The new `agent-file-writer.test.ts` enables focused unit tests for the overwrite-guard + write + reload + notify sequence — previously this logic was only testable through the higher-level `ejectAgent` and `showManualWizard` flows.
+2. Existing tests in `agent-config-editor.test.ts` (eject overwrite prompt, eject write) and `agent-creation-wizard.test.ts` (manual wizard overwrite prompt, manual wizard write) remain as integration-level tests that verify the full flow still works end-to-end.
+   They should not be removed — they test the caller's orchestration, not just the write logic.
+3. No existing tests become redundant with this extraction.
+
+## TDD Order
+
+1. **Red → Green: `writeAgentFile` writes when target does not exist**
+   - New `test/ui/agent-file-writer.test.ts` with tests: writes file, reloads registry, notifies user, returns `true`.
+   - New `src/ui/agent-file-writer.ts` with the extracted function.
+   - Commit: `feat: extract writeAgentFile overwrite-guard function (#217)`
+
+2. **Red → Green: `writeAgentFile` overwrite guard**
+   - Add tests: prompts for overwrite when file exists; writes and returns `true` when confirmed; does not write and returns `false` when declined.
+   - Implementation should already pass (the guard is part of the function body from step 1).
+   - Commit: `test: add overwrite-guard tests for writeAgentFile (#217)`
+
+3. **Refactor: wire `ejectAgent` to use `writeAgentFile`**
+   - Replace the inline overwrite-guard block in `AgentConfigEditor.ejectAgent` with a call to `writeAgentFile`.
+   - Existing tests in `agent-config-editor.test.ts` must continue to pass.
+   - Commit: `refactor: use writeAgentFile in AgentConfigEditor.ejectAgent (#217)`
+
+4. **Refactor: wire `showManualWizard` to use `writeAgentFile`**
+   - Replace the inline overwrite-guard block in `AgentCreationWizard.showManualWizard` with a call to `writeAgentFile`.
+   - Existing tests in `agent-creation-wizard.test.ts` must continue to pass.
+   - Commit: `refactor: use writeAgentFile in AgentCreationWizard.showManualWizard (#217)`
+
+5. **Docs: update architecture**
+   - Add `agent-file-writer.ts` to the `ui/` layout listing in `docs/architecture/architecture.md`.
+   - Update the production-duplication section to mark the clone group as resolved.
+   - Commit: `docs: update architecture for writeAgentFile extraction (#217)`
+
+## Risks and Mitigations
+
+1. **Notification message format drift** — The extracted function uses `${label} ${targetPath}` for the notification.
+   Both current callers produce messages matching this pattern (`"Ejected ${name} to ${targetPath}"` and `"Created ${targetPath}"`).
+   The label parameter gives callers full control over the prefix, so no format is baked in.
+2. **Existing test fragility** — Tests use `expect.stringContaining("already exists")` for the overwrite prompt, which is stable across the extraction.
+   No test rewrites needed.
+
+## Open Questions
+
+None — the issue's proposed change section is unambiguous and the dependency (#214) is resolved.

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

@@ -33,3 +33,29 @@ All checks green: full suite, `pnpm run check`, `pnpm run lint`, `pnpm fallow de
 - 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,80 @@
+---
+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.
+
+## Stage: Final Retrospective (2026-05-26T15:10:00Z)
+
+### Session summary
+
+Issue #216 was planned, implemented via 4 TDD steps (5 commits), shipped, CI verified (after a GitHub Actions outage), and released as `pi-subagents-v7.6.0`.
+The final design replaced the original mechanical-extraction proposal with a `RunHandle` lifecycle object that eliminated mutable closure state from `startAgent`.
+
+### Observations
+
+#### What went well
+
+- The user's two design redirections during planning ("What collaborators are still missing?"
+  and "Make the change that makes the change easy") transformed a mechanical extraction plan into a structural improvement.
+  The resulting `RunHandle` eliminated the root cause (mutable closure state) rather than just shortening the method.
+- The prep-step pattern worked exactly as intended: `WorktreeState.performCleanup` (step 1) and `finalizeBackgroundRun` (step 3) made the `RunHandle` rewrite (step 4) straightforward.
+  Step 4's large edit landed cleanly with all 962 tests passing on the first run.
+- Two Explore subagents dispatched during planning (reading collaborator files and checking `WorktreeState` details) gathered the right context efficiently — `RunResult` being already exported and `record.description` being available at cleanup time were both discovered this way and shaped the `RunHandle` interface.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — accepted the issue's proposed mechanical extraction (3 methods) at face value and spent analysis time on LOC arithmetic before the user redirected toward structural thinking.
+  Impact: two user redirections needed; no rework since no code was committed yet.
+- `instruction-violation` (self-identified) — the testing skill says "run `pnpm run check` immediately after" changing a shared interface, but step 1 added `performCleanup` to `WorktreeState` without running `pnpm run check`.
+  The type error in the test helper (`makeWorktrees` default parameter needing `WorktreeCleanupResult` annotation) went undetected for 3 commits until step 4's `pnpm run check`.
+  Impact: added friction but no rework — fixed in the same commit.
+
+#### What caused friction (user side)
+
+- The user's design redirections were necessary and well-timed.
+  No friction from the user side — the two interventions were strategic and saved significant implementation effort.
+
+### Diagnostic details
+
+- **Model-performance correlation** — two Explore subagents ran on `claude-haiku-4-5`; appropriate for read-only codebase search (reading collaborator files, checking types and test patterns).
+- **Feedback-loop gap analysis** — `pnpm run check` ran only after step 4 (the `RunHandle` commit); should have run after step 1 (`WorktreeState.performCleanup` is a shared interface change per the testing skill).
+  The gap allowed a type annotation error to persist for 3 commits.

package/docs/retro/0217-extract-overwrite-guard.md

@@ -0,0 +1,36 @@
+---
+issue: 217
+issue_title: "Extract overwrite guard from UI (Phase 13, Step 4)"
+---
+
+# Retro: #217 — Extract overwrite guard from UI
+
+## Stage: Planning (2026-05-26T20:00:00Z)
+
+### Session summary
+
+Produced a 5-step TDD plan to extract the duplicated overwrite-guard + write + reload + notify pattern from `AgentConfigEditor.ejectAgent` and `AgentCreationWizard.showManualWizard` into a shared `writeAgentFile` function in a new `src/ui/agent-file-writer.ts` module.
+Confirmed dependency #214 (closure-to-class conversion) is already closed.
+
+### Observations
+
+- The `showGenerateWizard` overwrite guard was explicitly scoped out — it has different lifecycle semantics (spawned agent writes the file, post-write check is conditional).
+  This avoids a leaky abstraction with a discriminator parameter.
+- Narrow ISP interfaces (`FileWriter`, `WriterUI`, `Reloadable`) keep the extracted function decoupled from the full `AgentFileOps` and `MenuUI` interfaces — 2/6 and 2/6 methods respectively.
+- Both consumer call sites hold `this.fileOps` and `this.registry` as private fields and receive `ui` as a method parameter, so no constructor or wiring changes are needed.
+- Existing tests in both consumer test files use `expect.stringContaining("already exists")` for overwrite prompts, which is stable across the extraction.
+
+## Stage: Implementation — TDD (2026-05-26T20:40:00Z)
+
+### Session summary
+
+Implemented `writeAgentFile` in new `src/ui/agent-file-writer.ts`, replaced the inline overwrite-guard blocks in `AgentConfigEditor.ejectAgent` and `AgentCreationWizard.showManualWizard`, and updated the architecture doc.
+All 5 plan steps completed across 4 commits (plan steps 1 and 2 folded into one).
+Test count: 962 → 970 (+8 new tests in `test/ui/agent-file-writer.test.ts`).
+
+### Observations
+
+- Plan steps 1 and 2 naturally collapsed into a single commit — writing all 8 tests at once and implementing the full function body (including the guard) in one pass was cleaner than splitting them artificially.
+- Both consumer refactors were straightforward one-import-add + one-block-replace edits; all existing tests passed without modification, confirming the extraction preserved exact behavior.
+- The notification label `"Ejected ${name} to"` (with trailing space absorbed by `${targetPath}`) matched the pre-existing message format `"Ejected test-agent to /path"` exactly — no test assertions changed.
+- `FileWriter`, `WriterUI`, and `Reloadable` narrow interfaces are exported from `agent-file-writer.ts`; both consumer files import the concrete types from their original sources, satisfying TypeScript's structural checker without any casts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.5.1",
+  "version": "7.7.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/ui/agent-config-editor.ts

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import type { AgentTypeRegistry } from "#src/config/agent-types";
 import type { AgentConfig } from "#src/types";
 import type { AgentFileOps } from "#src/ui/agent-file-ops";
+import { writeAgentFile } from "#src/ui/agent-file-writer";
 import type { MenuUI } from "#src/ui/agent-menu";
 
 // ---- Pure helpers ----
@@ -142,17 +143,14 @@ export class AgentConfigEditor {
       : this.personalAgentsDir;
 
     const targetPath = join(targetDir, `${name}.md`);
-    if (this.fileOps.exists(targetPath)) {
-      const overwrite = await ui.confirm(
-        "Overwrite",
-        `${targetPath} already exists. Overwrite?`,
-      );
-      if (!overwrite) return;
-    }
-
-    this.fileOps.write(targetPath, buildEjectContent(cfg));
-    this.registry.reload();
-    ui.notify(`Ejected ${name} to ${targetPath}`, "info");
+    await writeAgentFile(
+      this.fileOps,
+      ui,
+      this.registry,
+      targetPath,
+      buildEjectContent(cfg),
+      `Ejected ${name} to`,
+    );
   }
 
   private async disableAgent(ui: MenuUI, name: string): Promise<void> {

package/src/ui/agent-creation-wizard.ts

@@ -11,6 +11,7 @@ import { BUILTIN_TOOL_NAMES } from "#src/config/agent-types";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentRecord } from "#src/types";
 import type { AgentFileOps } from "#src/ui/agent-file-ops";
+import { writeAgentFile } from "#src/ui/agent-file-writer";
 import type { MenuUI } from "#src/ui/agent-menu";
 
 // ---- Deps interface ----
@@ -233,16 +234,6 @@ ${systemPrompt}
 
     const targetPath = join(targetDir, `${name}.md`);
 
-    if (this.fileOps.exists(targetPath)) {
-      const overwrite = await ui.confirm(
-        "Overwrite",
-        `${targetPath} already exists. Overwrite?`,
-      );
-      if (!overwrite) return;
-    }
-
-    this.fileOps.write(targetPath, content);
-    this.registry.reload();
-    ui.notify(`Created ${targetPath}`, "info");
+    await writeAgentFile(this.fileOps, ui, this.registry, targetPath, content, "Created");
   }
 }

package/src/ui/agent-file-writer.ts

@@ -0,0 +1,55 @@
+/**
+ * agent-file-writer.ts — Shared overwrite-guard + write + reload + notify helper.
+ *
+ * Extracted from AgentConfigEditor.ejectAgent and AgentCreationWizard.showManualWizard
+ * to eliminate the duplicated 20-line pattern. Uses narrow interfaces (ISP) so callers
+ * are not forced to depend on the full AgentFileOps or MenuUI shapes.
+ */
+
+// ---- Narrow interfaces ----
+
+/** Minimal file operations needed by the overwrite-guard-and-write pattern. */
+export interface FileWriter {
+	exists(filePath: string): boolean;
+	write(filePath: string, content: string): void;
+}
+
+/** Minimal UI needed by the overwrite-guard-and-write pattern. */
+export interface WriterUI {
+	confirm(title: string, message: string): Promise<boolean>;
+	notify(message: string, level: "info" | "warning" | "error"): void;
+}
+
+/** Registry that can be reloaded after file changes. */
+export interface Reloadable {
+	reload(): void;
+}
+
+// ---- Function ----
+
+/**
+ * Write an agent `.md` file with an overwrite guard.
+ *
+ * If `targetPath` already exists, prompts the user for confirmation before writing.
+ * On write: reloads the registry and notifies the user as `"${label} ${targetPath}"`.
+ *
+ * Returns `true` if the file was written, `false` if the user declined to overwrite.
+ */
+export async function writeAgentFile(
+	fileOps: FileWriter,
+	ui: WriterUI,
+	registry: Reloadable,
+	targetPath: string,
+	content: string,
+	label: string,
+): Promise<boolean> {
+	if (fileOps.exists(targetPath)) {
+		const overwrite = await ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+		if (!overwrite) return false;
+	}
+
+	fileOps.write(targetPath, content);
+	registry.reload();
+	ui.notify(`${label} ${targetPath}`, "info");
+	return true;
+}