@gotgenes/pi-subagents 7.6.0 → 7.7.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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)
 
 

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
 
@@ -727,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.
@@ -764,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/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/0216-decompose-start-agent.md

@@ -41,3 +41,40 @@ All 60 test files pass; `pnpm run check`, `pnpm run lint`, and `pnpm fallow dead
 - `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.6.0",
+  "version": "7.7.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

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;
+}