@gotgenes/pi-subagents 18.0.0 → 18.0.2

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

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

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

@@ -1,255 +0,0 @@
----
-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

@@ -1,176 +0,0 @@
----
-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.