@gotgenes/pi-subagents 7.6.0 → 7.8.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.8.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.7.0...pi-subagents-v7.8.0) (2026-05-26)
+
+
+### Features
+
+* inject agentDir into SettingsManager and loadSettings to remove SDK dependency ([7dcb986](https://github.com/gotgenes/pi-packages/commit/7dcb9868c8ac52c86a3eac0b6fc6648c8d57fc7c))
+* wire agentDir from SDK boundary in index.ts ([#218](https://github.com/gotgenes/pi-packages/issues/218)) ([17e9fc5](https://github.com/gotgenes/pi-packages/commit/17e9fc5f7880ae92168a6bb30e6fbc82748b7b2a))
+
+
+### Documentation
+
+* plan push SDK boundary in settings.ts ([#218](https://github.com/gotgenes/pi-packages/issues/218)) ([19f7cd6](https://github.com/gotgenes/pi-packages/commit/19f7cd6ddfa28290f7e61e6273d966c946868cf6))
+* **retro:** add planning stage notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([80be50e](https://github.com/gotgenes/pi-packages/commit/80be50e1b6ddf19f743010bd4c3cdf232d901cf1))
+* **retro:** add retro notes for issue [#217](https://github.com/gotgenes/pi-packages/issues/217) ([2140655](https://github.com/gotgenes/pi-packages/commit/21406555e34fbe0d41f48206e3208e1cb7326633))
+* **retro:** add TDD stage notes for issue [#218](https://github.com/gotgenes/pi-packages/issues/218) ([86b4f94](https://github.com/gotgenes/pi-packages/commit/86b4f946d7498e96dbb2b4c513d0ea6331fc5f8c))
+
+## [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
 
@@ -583,7 +584,10 @@ The IO boundary was split into two focused interfaces:
 export interface EnvironmentIO {
   detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
   getAgentDir: () => string;
-  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+  deriveSessionDir: (
+    parentSessionFile: string | undefined,
+    effectiveCwd: string,
+  ) => string;
 }
 
 /** Session factory — create SDK objects for a child agent session. */
@@ -591,7 +595,9 @@ export interface SessionFactoryIO {
   createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
   createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
-  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  createSession: (
+    opts: CreateSessionOptions,
+  ) => Promise<{ session: AgentSession }>;
   assemblerIO: AssemblerIO;
 }
 
@@ -642,7 +648,7 @@ Three closure factories converted to classes in [#214].
 - Smell: C (coupling — deps hidden in closure scope instead of explicit on class)
 - Outcome: 0 remaining closure factories (excluding pure-function factories), deps visible as constructor parameters
 
-### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215]
+### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215] ✓
 
 `buildParentContext` in `session/context.ts` is the only remaining fallow refactoring target.
 The function loops over branch entries with 3 type-check branches, each with sub-branches for role or summary.
@@ -670,7 +676,7 @@ Extracted:
 - Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
 - 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]
+### Step 4: Extract overwrite guard from UI — [#217] ✓
 
 The 20-line pattern duplicated between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` checks file existence, prompts for confirmation, writes the file, reloads the registry, and notifies the user.
 Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, label)` function.
@@ -679,7 +685,7 @@ Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, lab
 - Smell: A (production duplication)
 - Outcome: 0 production clone groups
 
-### Step 5: Push SDK boundary in `settings.ts` — [#218]
+### Step 5: Push SDK boundary in `settings.ts` — [#218] ✓
 
 `globalPath()` calls `getAgentDir()` (a Pi SDK function) at invocation time.
 This hides a platform dependency inside a module that is otherwise pure configuration logic.
@@ -727,6 +733,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 +876,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.
 
@@ -782,7 +895,6 @@ The upstream test suite is run periodically as a regression canary for the agent
 [earendil-works/pi#4207]: https://github.com/earendil-works/pi/issues/4207
 [gotgenes/pi-packages]: https://github.com/gotgenes/pi-packages
 [tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents
-
 [166]: https://github.com/gotgenes/pi-packages/issues/166
 [167]: https://github.com/gotgenes/pi-packages/issues/167
 [168]: https://github.com/gotgenes/pi-packages/issues/168

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/plans/0218-push-sdk-boundary-in-settings.md

@@ -0,0 +1,172 @@
+---
+issue: 218
+issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
+---
+
+# Push SDK boundary in settings.ts
+
+## Problem Statement
+
+`settings.ts` imports `getAgentDir` from the Pi SDK (`@earendil-works/pi-coding-agent`) and calls it inside `globalPath()` at invocation time.
+This hides a platform dependency inside a module that is otherwise pure configuration logic — violating the project's SDK-boundary rule that pure helpers and domain modules should remain SDK-independent.
+The SDK call also forces tests to redirect the env var `PI_CODING_AGENT_DIR` to control `getAgentDir()` output, rather than passing the value directly.
+
+## Goals
+
+- Remove the `getAgentDir` import from `settings.ts` (0 Pi SDK imports).
+- Inject `agentDir: string` into `SettingsManager` constructor deps.
+- Make `loadSettings` accept `agentDir` as an explicit parameter.
+- Eliminate `PI_CODING_AGENT_DIR` env var manipulation from all settings tests.
+
+## Non-Goals
+
+- Removing `process.cwd()` defaults from `loadSettings`/`saveSettings` — that's a separate concern (Node.js API, not Pi SDK).
+- Pushing SDK boundaries in other files (`skill-loader.ts`, `custom-agents.ts`, `agent-runner.ts`) — tracked separately in the Phase 13 roadmap.
+- Changing the `saveSettings` signature — it only calls `projectPath(cwd)` and has no SDK dependency.
+
+## Background
+
+`settings.ts` exports a `SettingsManager` class and two free functions (`loadSettings`, `saveSettings`).
+The only SDK import is `getAgentDir`, used in the private `globalPath()` helper to compute the global settings file path (`~/.pi/agent/subagents.json`).
+
+The `SettingsManager` constructor already accepts a deps bag `{ emit, cwd, onMaxConcurrentChanged? }`.
+Adding `agentDir` to this bag follows the established injection pattern.
+
+In `index.ts`, `getAgentDir` is already imported for several other call sites (agent runner IO, agent tool, `/agents` menu).
+Adding one more usage to the `SettingsManager` construction is zero new imports.
+
+### Relevant AGENTS.md constraints
+
+- **Pi SDK boundaries:** Keep Pi SDK imports out of business-logic modules; accept the value as a parameter or callback.
+- **Code-design skill, DIP:** Default to dependency injection for non-trivial dependencies.
+
+## Design Overview
+
+### Change to `globalPath()`
+
+Currently:
+
+```typescript
+function globalPath(): string {
+  return join(getAgentDir(), "subagents.json");
+}
+```
+
+After:
+
+```typescript
+function globalPath(agentDir: string): string {
+  return join(agentDir, "subagents.json");
+}
+```
+
+### Change to `loadSettings()`
+
+Currently:
+
+```typescript
+export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+}
+```
+
+After:
+
+```typescript
+export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
+}
+```
+
+### Change to `SettingsManager` constructor
+
+Add `agentDir: string` to the deps bag:
+
+```typescript
+constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
+  this.emit = deps.emit;
+  this.cwd = deps.cwd;
+  this.agentDir = deps.agentDir;
+  this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
+}
+```
+
+`SettingsManager.load()` passes `this.agentDir` to `loadSettings`:
+
+```typescript
+load(): SubagentsSettings {
+  const settings = loadSettings(this.agentDir, this.cwd);
+  // ... rest unchanged
+}
+```
+
+### Wiring in `index.ts`
+
+```typescript
+const settings = new SettingsManager({
+  emit: (event, payload) => pi.events.emit(event, payload),
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
+});
+```
+
+## Module-Level Changes
+
+### `src/settings.ts`
+
+1. Remove `import { getAgentDir } from "@earendil-works/pi-coding-agent"`.
+2. Add `agentDir: string` field to the `SettingsManager` constructor deps interface.
+3. Store `this.agentDir = deps.agentDir` as a private readonly field.
+4. Change `globalPath()` signature to `globalPath(agentDir: string)`.
+5. Change `loadSettings` signature to `loadSettings(agentDir: string, cwd?: string)`.
+6. Update `SettingsManager.load()` to call `loadSettings(this.agentDir, this.cwd)`.
+7. Update the header comment to reflect the new injection pattern.
+
+### `src/index.ts`
+
+1. Add `agentDir: getAgentDir()` to the `SettingsManager` constructor deps object.
+
+### `test/settings.test.ts`
+
+1. Remove all `PI_CODING_AGENT_DIR` env manipulation (`originalAgentDirEnv`, `beforeEach`/`afterEach` stubs).
+2. Pass `globalDir` directly to `loadSettings(globalDir, projectDir)` in free-function tests.
+3. Add `agentDir: globalDir` (or a dummy string for non-load tests) to all `new SettingsManager(...)` calls.
+4. In `SettingsManager.load()` tests, pass `agentDir: globalDir` to the constructor.
+5. In tests that don't exercise `load()`, use `agentDir: "/nonexistent"` or similar — the value is unused.
+
+## Test Impact Analysis
+
+1. **New capability:** Free-function tests (`loadSettings`, `saveSettings`) become pure — pass `globalDir` directly instead of manipulating `PI_CODING_AGENT_DIR`.
+   This is simpler and more reliable.
+2. **Redundant cleanup:** The `originalAgentDirEnv` save/restore pattern in `beforeEach`/`afterEach` can be removed from all `describe` blocks that use it.
+3. **Existing tests stay:** All existing test scenarios remain valid; only their setup mechanics change.
+
+## TDD Order
+
+1. **Red → Green:** Change `loadSettings` signature to accept `agentDir` parameter; update `globalPath` to accept it.
+   Update all free-function tests to pass `globalDir` directly instead of env var.
+   Remove env-var manipulation from the `settings persistence` describe block.
+   Commit: `feat: inject agentDir into loadSettings to remove SDK dependency`
+
+2. **Red → Green:** Add `agentDir` to `SettingsManager` constructor deps; store as private field; thread into `load()`.
+   Update all `new SettingsManager(...)` call sites in tests.
+   Remove env-var manipulation from `SettingsManager` describe blocks.
+   Remove `getAgentDir` import from `settings.ts`.
+   Commit: `feat: inject agentDir into SettingsManager constructor`
+
+3. **Green:** Wire `agentDir: getAgentDir()` into `SettingsManager` construction in `index.ts`.
+   Run `pnpm run check` to confirm no type errors across the package.
+   Commit: `feat: wire agentDir from SDK boundary in index.ts (#218)`
+
+## Risks and Mitigations
+
+| Risk                                                                                  | Mitigation                                                                                                   |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Breaking the `loadSettings` export signature for hypothetical external callers        | The function is only called from `SettingsManager.load()` and tests; no external consumers exist.            |
+| Test count is high (~35 constructor sites) — mechanical updates could introduce typos | Steps 1 and 2 are focused; run `pnpm vitest run test/settings.test.ts` after each to confirm.                |
+| Forgetting a test site that still manipulates `PI_CODING_AGENT_DIR`                   | Grep for `PI_CODING_AGENT_DIR` after step 2 to confirm zero remaining references in `test/settings.test.ts`. |
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and follows the established injection pattern used in prior Phase 13 steps.

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,63 @@
+---
+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.
+
+## Stage: Final Retrospective (2026-05-26T21:00:00Z)
+
+### Session summary
+
+Full plan → TDD → ship → release lifecycle completed in a single continuous session.
+Released as `pi-subagents-v7.7.0`.
+Zero rework, zero test failures, zero CI issues.
+
+### Observations
+
+#### What went well
+
+- The Phase 13 roadmap's step-level issue decomposition produced an issue (#217) that was right-sized for fully autonomous execution — the entire lifecycle completed without any blocking questions or scope surprises.
+- ISP-narrow interfaces (`FileWriter`, `WriterUI`, `Reloadable`) structurally satisfied both consumer types without casts, confirming the plan's design.
+- Existing tests in both consumer files passed without modification after the refactors, validating that the extraction preserved exact behavior.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan split TDD steps 1 (happy-path tests) and 2 (overwrite-guard tests) for a ~10-line function with a single conditional.
+  Writing all 8 tests at once and implementing the full function body in one pass was natural; splitting them would have been artificial.
+  Self-corrected by folding into one commit.
+  Impact: added friction but no rework — the plan said "implementation should already pass" for step 2, acknowledging the fold was expected.
+
+#### What caused friction (user side)
+
+- Nothing notable — the issue was well-scoped with clear target files, a concrete smell label, and an explicit dependency chain.

package/docs/retro/0218-push-sdk-boundary-in-settings.md

@@ -0,0 +1,35 @@
+---
+issue: 218
+issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
+---
+
+# Retro: #218 — Push SDK boundary in settings.ts
+
+## Stage: Planning (2026-05-26T17:01:55Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to inject `agentDir: string` into `SettingsManager` and `loadSettings`, removing the only Pi SDK import from `settings.ts`.
+The change is straightforward — a single parameter addition threading through constructor, free function, and boundary wiring.
+
+### Observations
+
+- The change is entirely mechanical: no design ambiguity, no new abstractions, no breaking public API.
+- The main implementation effort is in test updates (~35 `new SettingsManager(...)` call sites plus ~15 `loadSettings(...)` calls), all requiring an `agentDir` argument.
+- All test `describe` blocks that manipulate `PI_CODING_AGENT_DIR` env var can drop that scaffolding entirely, simplifying setup/teardown.
+- `saveSettings` has no SDK dependency and needs no signature change — only `loadSettings` calls `globalPath()`.
+
+## Stage: Implementation — TDD (2026-05-26T17:13:26Z)
+
+### Session summary
+
+Completed all 3 plan steps across 2 commits plus 1 doc commit.
+All 970 tests pass; `settings.ts` now has 0 Pi SDK imports and all `PI_CODING_AGENT_DIR` env var manipulation is gone from `settings.test.ts`.
+
+### Observations
+
+- **Steps 1+2 combined:** Changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` forced updating `SettingsManager.load()` in the same commit — they were inseparable (esbuild skips type checks, so the old call compiled but produced wrong runtime behavior).
+  The two production changes landed in one commit with a note in the body.
+- **Test simplification was significant:** Removed `originalAgentDirEnv` save/restore scaffolding from 5 `describe` blocks; the test code shrank by 32 lines net.
+- **`/nonexistent` sentinel:** Tests that construct `SettingsManager` but never call `load()` pass `agentDir: "/nonexistent"` — a clear signal the field is unused in that scope.
+- Architecture doc Step 5 heading marked `✓` and folded into the last `feat:` commit by `pi-autoformat`.

package/package.json

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

package/src/index.ts

@@ -70,6 +70,7 @@ export default function (pi: ExtensionAPI) {
   const settings = new SettingsManager({
     emit: (event, payload) => pi.events.emit(event, payload),
     cwd: process.cwd(),
+    agentDir: getAgentDir(),
     onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
   });
   settings.load();

package/src/settings.ts

@@ -1,10 +1,9 @@
 // Persistence for pi-subagents operational settings.
-// - Global:  ~/.pi/agent/subagents.json (via getAgentDir()) — manual defaults, never written here
+// - Global:  ~/.pi/agent/subagents.json (agentDir injected at construction) — manual defaults, never written here
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -34,11 +33,13 @@ export class SettingsManager {
 
   private readonly emit: SettingsEmit;
   private readonly cwd: string;
+  private readonly agentDir: string;
   private readonly onMaxConcurrentChanged: (() => void) | undefined;
 
-  constructor(deps: { emit: SettingsEmit; cwd: string; onMaxConcurrentChanged?: () => void }) {
+  constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
     this.emit = deps.emit;
     this.cwd = deps.cwd;
+    this.agentDir = deps.agentDir;
     this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
   }
 
@@ -84,7 +85,7 @@ export class SettingsManager {
    * Returns the raw loaded settings object.
    */
   load(): SubagentsSettings {
-    const settings = loadSettings(this.cwd);
+    const settings = loadSettings(this.agentDir, this.cwd);
     if (typeof settings.maxConcurrent === "number") this.maxConcurrent = settings.maxConcurrent;
     if (typeof settings.defaultMaxTurns === "number") this.defaultMaxTurns = settings.defaultMaxTurns;
     if (typeof settings.graceTurns === "number") this.graceTurns = settings.graceTurns;
@@ -180,8 +181,8 @@ function sanitize(raw: unknown): SubagentsSettings {
   return out;
 }
 
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
+function globalPath(agentDir: string): string {
+  return join(agentDir, "subagents.json");
 }
 
 function projectPath(cwd: string): string {
@@ -205,8 +206,8 @@ function readSettingsFile(path: string): SubagentsSettings {
 }
 
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
+export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
+  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
 }
 
 /**

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