@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0230-extract-concurrency-queue.md

@@ -1,265 +0,0 @@
----
-issue: 230
-issue_title: "Extract ConcurrencyQueue from AgentManager (Phase 15, Step 5)"
----
-
-# Extract ConcurrencyQueue from AgentManager
-
-## Problem Statement
-
-`AgentManager` tangles two concerns: agent collection management and scheduling.
-The scheduling concern — `queue[]`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()`, `notifyConcurrencyChanged()` — is 3 fields + 3 methods of cohesive, separable logic.
-`notifyConcurrencyChanged()` is a scheduling method exposed as a public API on the wrong object so that `SettingsManager` can poke the queue after a concurrency limit change.
-This cross-concern leak violates SRP and prevents independent testing of the queue.
-
-## Goals
-
-- Extract scheduling logic into a `ConcurrencyQueue` class in `src/lifecycle/concurrency-queue.ts`.
-- Delete `notifyConcurrencyChanged()` from `AgentManager` — settings triggers drain on the queue directly via the existing callback wiring.
-- Make scheduling independently testable with fast, focused unit tests.
-- `AgentManager` becomes a pure collection manager (agents Map, lookup, cleanup, iteration) + observer wiring.
-
-## Non-Goals
-
-- Changing `SettingsManager` internals — `onMaxConcurrentChanged` callback stays; only the wiring target changes (queue.drain instead of manager.notifyConcurrencyChanged).
-- Extracting `Agent.resume()` — tracked in #232.
-- Changing the concurrency semantics (limits, drain order, foreground bypass).
-
-## Background
-
-### Dependencies
-
-Both dependencies are implemented:
-
-- Issue #229 (Agent.run()) — ✅ closed.
-  Agent owns its full execution lifecycle; `startAgent` and `SpawnArgs` are gone.
-- Issue #231 (runner self-contained) — ✅ closed.
-  Agent holds the runner at construction.
-
-### Current queue surface in AgentManager
-
-| Member                            | Kind   | Purpose                                          |
-| --------------------------------- | ------ | ------------------------------------------------ |
-| `queue: string[]`                 | field  | IDs of background agents waiting to start        |
-| `runningBackground: number`       | field  | Count of currently running background agents     |
-| `_getMaxConcurrent: () => number` | field  | Injected getter for the concurrency limit        |
-| `drainQueue()`                    | method | Start queued agents up to the limit              |
-| `finalizeBackgroundRun()`         | method | Decrement counter, notify observer, drain        |
-| `notifyConcurrencyChanged()`      | method | Public entry point for settings to trigger drain |
-
-These 6 members form a cohesive unit — they only reference each other and the agents Map (for status checks during drain).
-
-### Callers of queue logic in AgentManager
-
-- `spawn()` — checks `runningBackground >= getMaxConcurrent()`, pushes to `queue` or starts.
-- `buildObserver().onStarted` — increments `runningBackground`.
-- `buildObserver().onRunFinished` — calls `finalizeBackgroundRun()`.
-- `abort()` — filters `queue` to remove an aborted ID.
-- `abortAll()` — iterates `queue`, clears it.
-- `waitForAll()` — calls `drainQueue()`.
-- `dispose()` — clears `queue`.
-
-### Agent comment to update
-
-`agent.ts` line 366 has a comment: "Queue removal stays on AgentManager until #230 extracts ConcurrencyQueue."
-This comment should be updated to remove the forward reference.
-
-## Design Overview
-
-### ConcurrencyQueue class
-
-```typescript
-export class ConcurrencyQueue {
-  private queue: string[] = [];
-  private running = 0;
-
-  constructor(
-    private readonly getMaxConcurrent: () => number,
-    private readonly startAgent: (id: string) => void,
-  ) {}
-
-  isFull(): boolean;
-  enqueue(id: string): void;
-  dequeue(id: string): boolean;
-  markStarted(): void;
-  markFinished(): void;   // running--, drain()
-  drain(): void;
-  get queuedIds(): readonly string[];
-  clear(): void;
-}
-```
-
-### Design decision: stored start callback
-
-The issue proposes `drain(start: (id: string) => void)` with the callback as a parameter.
-However, the issue also proposes `markFinished()` as no-arg with "running--, drain()" semantics — which contradicts `drain` requiring a callback parameter.
-
-Resolution: store the `startAgent` callback at construction.
-This makes `drain()` and `markFinished()` both no-arg, follows Tell-Don't-Ask (the queue is a self-contained unit), and avoids requiring callers to pass the same callback repeatedly.
-
-The `startAgent` callback is provided by the wiring layer (`index.ts`) using the established forward-reference-via-closure pattern already used for `onMaxConcurrentChanged`:
-
-```typescript
-// index.ts
-const queue = new ConcurrencyQueue(
-  () => settings.maxConcurrent,
-  (id) => {
-    const agent = manager.getRecord(id);
-    if (agent?.status !== "queued") return;
-    agent.promise = agent.run();
-  },
-);
-```
-
-### Ordering note
-
-`markFinished()` calls `drain()` internally.
-The current `finalizeBackgroundRun()` order is: decrement → observer notification → drain.
-After extraction: `queue.markFinished()` (decrement + drain) → observer notification.
-Drain fires before the observer notification.
-
-This reordering is safe: `drain()` only starts promises (no await), and the observer notification (`onAgentCompleted`) processes the completed agent's data without referencing queue state.
-
-### AgentManager after extraction
-
-```typescript
-export interface AgentManagerOptions {
-  runner: AgentRunner;
-  worktrees: WorktreeManager;
-  queue: ConcurrencyQueue;         // was: getMaxConcurrent
-  getRunConfig?: () => RunConfig;
-  observer?: AgentManagerObserver;
-}
-```
-
-`AgentManager` loses `queue`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()`, `notifyConcurrencyChanged()`.
-
-### Settings wiring
-
-Before:
-
-```typescript
-onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
-```
-
-After:
-
-```typescript
-onMaxConcurrentChanged: () => queue.drain(),
-```
-
-`SettingsManager` itself does not change — it still invokes the stored callback.
-The callback wiring in `index.ts` targets the queue directly instead of the manager.
-
-### Consumer call site (AgentManager.buildObserver)
-
-```typescript
-private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
-  return {
-    onStarted: (agent) => {
-      if (options.isBackground) this.queue.markStarted();
-      this.observer?.onAgentStarted(agent);
-    },
-    onRunFinished: (agent) => {
-      if (options.isBackground) {
-        this.queue.markFinished();
-        try { this.observer?.onAgentCompleted(agent); }
-        catch (err) { debugLog("onAgentCompleted observer", err); }
-      }
-    },
-    // onSessionCreated, onCompacted unchanged
-  };
-}
-```
-
-### Test helper (createManager)
-
-```typescript
-function createManager(overrides?: { ...; getMaxConcurrent?: () => number; }) {
-  let mgr: AgentManager;
-  const queue = new ConcurrencyQueue(
-    overrides?.getMaxConcurrent ?? (() => 4),
-    (id) => {
-      const record = mgr.getRecord(id);
-      if (record?.status !== "queued") return;
-      record.promise = record.run();
-    },
-  );
-  mgr = new AgentManager({ ..., queue });
-  return { manager: mgr, ..., queue };
-}
-```
-
-The forward-reference-via-closure is safe because `drain()` is never called during construction.
-The `getMaxConcurrent` parameter name stays in the test helper for readability; it's passed to `ConcurrencyQueue`.
-
-## Module-Level Changes
-
-| File                                       | Change                                                                                                                                                           |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/lifecycle/concurrency-queue.ts`       | **Add** — new `ConcurrencyQueue` class                                                                                                                           |
-| `src/lifecycle/agent-manager.ts`           | **Change** — remove 3 fields, 3 methods; add `queue: ConcurrencyQueue` to options; update `buildObserver`, `spawn`, `abort`, `abortAll`, `waitForAll`, `dispose` |
-| `src/lifecycle/agent.ts`                   | **Change** — update comment on `abort()` (remove #230 forward reference)                                                                                         |
-| `src/index.ts`                             | **Change** — create `ConcurrencyQueue`, pass to manager, wire settings to `queue.drain()`                                                                        |
-| `test/lifecycle/concurrency-queue.test.ts` | **Add** — unit tests for ConcurrencyQueue                                                                                                                        |
-| `test/lifecycle/agent-manager.test.ts`     | **Change** — update `createManager` helper to construct ConcurrencyQueue; no queue-behavior tests removed (they remain as integration tests)                     |
-| `docs/architecture/architecture.md`        | **Change** — add `concurrency-queue.ts` to layout listing; update agent-manager description                                                                      |
-
-## Test Impact Analysis
-
-### New unit tests enabled by extraction
-
-1. `isFull()` boundary — returns false when running < max, true when running >= max.
-2. `enqueue()` / `dequeue()` — add/remove from queue, dequeue returns false for missing ID.
-3. `markStarted()` / `markFinished()` — increment/decrement running count.
-4. `drain()` — calls `startAgent` for each queued ID until full; skips when already full; handles empty queue.
-5. `markFinished()` auto-drain — decrement triggers drain of next queued agent.
-6. `clear()` — empties queue without starting agents.
-7. `queuedIds` — snapshot of queue for iteration.
-
-These tests were previously impossible because queue logic was interleaved with agent creation, observer notifications, and session management in `AgentManager`.
-
-### Existing tests that stay as-is
-
-- "queueing and concurrency with injected stubs" — integration tests verifying end-to-end spawn→queue→drain through the full AgentManager stack.
-  They still provide value as wiring tests.
-- All observer notification tests — test observer wiring which stays in AgentManager.
-- Bug race condition tests, worktree tests, execution state tests, lifecycle observer forwarding tests — independent of queue.
-
-### Existing tests that need updating
-
-- `createManager` helper — accepts `getMaxConcurrent` but passes it to `ConcurrencyQueue` constructor instead of `AgentManagerOptions`.
-
-## TDD Order
-
-1. **Red→Green: ConcurrencyQueue class + tests.**
-   New `src/lifecycle/concurrency-queue.ts` with `isFull`, `enqueue`, `dequeue`, `markStarted`, `markFinished`, `drain`, `clear`, `queuedIds`.
-   New `test/lifecycle/concurrency-queue.test.ts` covering: full boundary, enqueue/dequeue, start/finish counting, drain ordering, markFinished auto-drain, clear, empty-queue no-op.
-   Commit: `feat(pi-subagents): add ConcurrencyQueue class (#230)`
-
-2. **Red→Green: Migrate AgentManager to use ConcurrencyQueue.**
-   Update `AgentManagerOptions`: replace `getMaxConcurrent` with `queue: ConcurrencyQueue`.
-   Update constructor, `buildObserver`, `spawn`, `abort`, `abortAll`, `waitForAll`, `dispose`.
-   Delete: `queue` field, `runningBackground` field, `_getMaxConcurrent` field, `notifyConcurrencyChanged()`, `drainQueue()`, `finalizeBackgroundRun()`.
-   Update `test/lifecycle/agent-manager.test.ts`: revise `createManager` helper to construct `ConcurrencyQueue` internally.
-   Update `src/index.ts`: construct `ConcurrencyQueue`, pass to `AgentManager`, wire `onMaxConcurrentChanged` to `queue.drain()`.
-   Update `src/lifecycle/agent.ts`: remove #230 forward-reference comment on `abort()`.
-   Run `pnpm run check` after this step.
-   Commit: `refactor(pi-subagents): replace inline queue with ConcurrencyQueue (#230)`
-
-3. **Docs: Update architecture.**
-   Update `docs/architecture/architecture.md`: add `concurrency-queue.ts` to layout listing under `lifecycle/`, update `agent-manager.ts` description from "collection manager + concurrency controller" to "collection manager + observer wiring".
-   Commit: `docs(pi-subagents): update architecture for ConcurrencyQueue extraction (#230)`
-
-## Risks and Mitigations
-
-| Risk                                                                                                         | Mitigation                                                                                                                                                                                               |
-| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Forward-reference-via-closure in test helper and index.ts could break if drain is called during construction | ConcurrencyQueue constructor does not call drain; drain is only called after agents exist. Same pattern already used for `onMaxConcurrentChanged`.                                                       |
-| `markFinished()` auto-drain changes ordering (drain before observer notification)                            | Verified: observer notification only processes the completed agent's data and does not reference queue state. Drain starts promises without awaiting — no observable behavior change.                    |
-| `markStarted()` called synchronously inside drain loop could miscount                                        | Verified: `Agent.run()` calls `observer.onStarted()` synchronously before the first await, so `markStarted()` fires before control returns to the drain while-loop. The running count is always current. |
-| Integration tests in agent-manager.test.ts break after migration                                             | Tests continue to work because the `createManager` helper constructs the ConcurrencyQueue internally with the same `getMaxConcurrent` semantics. Queue behavior is preserved.                            |
-
-## Open Questions
-
-None — the issue's proposed change is unambiguous and both dependencies are implemented.

package/docs/plans/0231-push-exec-registry-to-runner.md

@@ -1,245 +0,0 @@
----
-issue: 231
-issue_title: "Push exec/registry relay deps to runner construction (Phase 15, Step 3)"
----
-
-# Push exec/registry relay deps to runner construction
-
-## Problem Statement
-
-`AgentManager` receives `exec` and `registry` in its constructor but never uses them directly.
-They are stored as fields solely to relay them into `runner.run()` via the `RunContext` parameter.
-This makes `AgentManager` wider than necessary and prevents the runner from being self-contained — a prerequisite for #229 (Agent.run() absorbs startAgent).
-
-## Goals
-
-- Move `exec` and `registry` from `AgentManager` construction to `ConcreteAgentRunner` construction.
-- Remove `exec` and `registry` from `AgentManagerOptions` (7 → 5 fields).
-- Remove `exec` and `registry` from `RunContext` (4 → 2 fields).
-- Group runner-owned dependencies in a `RunnerDeps` interface: `{ io, exec, registry }`.
-- Replace `runAgent()`'s `io: RunnerIO` parameter with `deps: RunnerDeps`.
-
-## Non-Goals
-
-- Dissolving `RunContext` entirely — it shrinks to `{ cwd?, parentSession? }`, which is still a coherent per-call grouping.
-  Issue #229 will likely dissolve it when `Agent.run()` calls the runner directly.
-- Changing the `AgentRunner` interface's `run()` signature — callers continue to pass `RunOptions` with `context: RunContext`.
-  `ConcreteAgentRunner` merges its stored deps before calling `runAgent()`.
-- Touching `resume()` or `resumeAgent()` — they don't use `exec` or `registry`.
-
-## Background
-
-Issue #169 extracted `RunContext` from `RunOptions` to group the 4 parent-context fields: `exec`, `registry`, `cwd`, `parentSession`.
-The doc comment describes them as "parent environment and identity" fields.
-However, 2 of the 4 fields (`exec`, `registry`) are static — identical across every `run()` call — while the other 2 (`cwd`, `parentSession`) vary per spawn.
-The static pair are relay-only dependencies on `AgentManager`: stored at construction, never read, only forwarded.
-
-From the code-design skill, this is a **parameter relay** smell: intermediaries (`AgentManager`) carry fields they never use, only to thread them to the endpoint (`runAgent`).
-The fix: put them on the object the endpoint owns — the runner.
-
-### Key references
-
-- `src/lifecycle/agent-manager.ts` — stores `exec` and `registry`, relays them at lines 193–194.
-- `src/lifecycle/agent-runner.ts` — `RunContext` interface (line 125), `ConcreteAgentRunner` class (line 189), `runAgent()` free function (line 236).
-- `src/index.ts` — constructs both `ConcreteAgentRunner` and `AgentManager` (lines 148–157).
-- Phase 15 roadmap in `docs/architecture/architecture.md` § Step 3.
-
-## Design Overview
-
-### RunnerDeps — grouping runner-owned dependencies
-
-A new `RunnerDeps` interface groups the three dependencies that the runner owns:
-
-```typescript
-export interface RunnerDeps {
-  io: RunnerIO;
-  exec: ShellExec;
-  registry: AgentConfigLookup;
-}
-```
-
-`ConcreteAgentRunner` takes `RunnerDeps` at construction:
-
-```typescript
-export class ConcreteAgentRunner implements AgentRunner {
-  constructor(private readonly deps: RunnerDeps) {}
-
-  run(snapshot, type, prompt, options) {
-    return runAgent(snapshot, type, prompt, options, this.deps);
-  }
-}
-```
-
-`runAgent()` changes its last parameter from `io: RunnerIO` to `deps: RunnerDeps`:
-
-```typescript
-export async function runAgent(
-  snapshot: ParentSnapshot,
-  type: SubagentType,
-  prompt: string,
-  options: RunOptions,
-  deps: RunnerDeps,
-): Promise<RunResult> {
-  const effectiveCwd = options.context?.cwd ?? snapshot.cwd;
-  const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
-  // ...
-  const cfg = assembleSessionConfig(type, ..., deps.registry, deps.io.assemblerIO);
-  // ...
-}
-```
-
-### RunContext shrinks
-
-`RunContext` loses `exec` and `registry`:
-
-```typescript
-export interface RunContext {
-  /** Override working directory (e.g. for worktree isolation). */
-  cwd?: string;
-  /** Parent session identity (file path + session ID). */
-  parentSession?: ParentSessionInfo;
-}
-```
-
-The `AgentRunner.run()` interface is unchanged — callers still pass `RunOptions` with `context: RunContext`.
-`ConcreteAgentRunner.run()` reads `exec` and `registry` from its own `deps` instead of from `options.context`.
-
-### AgentManager loses 2 fields
-
-`AgentManagerOptions` removes `exec` and `registry`.
-`AgentManager` removes the corresponding private fields and the `this.exec` / `this.registry` relay in `startAgent()`.
-The `context` object constructed in `startAgent()` shrinks from 4 fields to 2:
-
-```typescript
-context: {
-  cwd: record.worktreeState?.path,
-  parentSession: options.parentSession,
-},
-```
-
-### Wiring in index.ts
-
-```typescript
-const runner = new ConcreteAgentRunner({
-  io: runnerIO,
-  exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
-  registry,
-});
-
-const manager = new AgentManager({
-  runner,
-  worktrees: new GitWorktreeManager(process.cwd()),
-  observer,
-  getMaxConcurrent: () => settings.maxConcurrent,
-  getRunConfig: () => settings,
-});
-```
-
-## Module-Level Changes
-
-### `src/lifecycle/agent-runner.ts`
-
-1. Add `RunnerDeps` interface (exported): `{ io: RunnerIO; exec: ShellExec; registry: AgentConfigLookup }`.
-2. Remove `exec` and `registry` from `RunContext`.
-   Update doc comment to reflect the 2 remaining per-call fields.
-3. Update `ConcreteAgentRunner` constructor: accept `RunnerDeps` instead of `RunnerIO`.
-4. Update `ConcreteAgentRunner.run()`: pass `this.deps` to `runAgent()`.
-5. Update `runAgent()`: change last parameter from `io: RunnerIO` to `deps: RunnerDeps`.
-   Replace `io.` references with `deps.io.`, `options.context.exec` with `deps.exec`, `options.context.registry` with `deps.registry`.
-
-### `src/lifecycle/agent-manager.ts`
-
-1. Remove `exec: ShellExec` and `registry: AgentTypeRegistry` from `AgentManagerOptions`.
-2. Remove `private readonly exec` and `private readonly registry` fields from `AgentManager`.
-3. Remove assignment of `this.exec` and `this.registry` in the constructor.
-4. Remove `exec: this.exec` and `registry: this.registry` from the `context` object in `startAgent()`.
-5. Remove `ShellExec` and `AgentTypeRegistry` imports (verify no other references first).
-
-### `src/index.ts`
-
-1. Move `exec` and `registry` from the `AgentManager` constructor call to `ConcreteAgentRunner`:
-   `new ConcreteAgentRunner({ io: runnerIO, exec: ..., registry })`.
-2. Remove `exec` and `registry` from the `AgentManager({...})` constructor argument.
-
-### `test/lifecycle/agent-runner.test.ts`
-
-1. Update all `runAgent(..., io)` calls to `runAgent(..., { io, exec, registry: mockAgentLookup })`.
-2. Remove `exec` and `registry` from `context:` objects in `RunOptions`.
-   `context: { exec, registry: mockAgentLookup }` → `context: {}` or `{}`.
-
-### `test/lifecycle/agent-runner-extension-tools.test.ts`
-
-1. Same pattern as `agent-runner.test.ts`: update `runAgent(..., io)` last param and strip `exec`/`registry` from `context:`.
-
-### `test/lifecycle/concrete-agent-runner.test.ts`
-
-1. Update `new ConcreteAgentRunner(io)` → `new ConcreteAgentRunner({ io, exec: vi.fn(), registry })`.
-2. Remove `exec` and `registry` from the `context:` in `runner.run()` call options.
-
-### `test/lifecycle/agent-manager.test.ts`
-
-1. Remove `exec: vi.fn()` and `registry: testRegistry` from `createManager()` factory.
-2. Remove the `testRegistry` construction and `AgentTypeRegistry` import if no other references exist.
-
-### `test/helpers/runner-io.ts`
-
-1. No structural changes needed — `createRunnerIO()` returns the `RunnerIO` shape, which is unchanged.
-   However, add a `createRunnerDeps()` convenience factory that bundles `{ io: createRunnerIO(), exec: vi.fn(), registry: createAgentLookup() }` for runner test files.
-
-### `docs/architecture/architecture.md`
-
-1. Update the `RunContext` code block in § "RunOptions (12 fields → extract RunContext)" to show only `cwd` and `parentSession`.
-2. Update the field-count description (4 → 2 per-call fields).
-3. Mark Step 3 as complete in the Phase 15 roadmap.
-
-## Test Impact Analysis
-
-1. No new test surfaces are needed — this is a pure mechanical refactoring (moving constructor parameters).
-   The existing runner and manager test suites fully cover the behavior.
-2. No existing tests become redundant — all tests exercise the same interactions, just with deps flowing through a different path.
-3. Existing `agent-manager.test.ts` tests remain as-is in coverage scope.
-   They verify `AgentManager` behavior (spawning, queueing, abort, etc.) independent of runner deps.
-4. Existing `agent-runner.test.ts` and `concrete-agent-runner.test.ts` tests remain.
-   They verify `runAgent()` and `ConcreteAgentRunner` behavior.
-   Call-site patterns change but assertions stay the same.
-
-## TDD Order
-
-1. **Add `RunnerDeps` interface and update `runAgent()` parameter** — define `RunnerDeps`, change `runAgent()`'s last param from `io` to `deps`, update internal references.
-   Update `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` call sites.
-   Commit: `refactor: add RunnerDeps and update runAgent parameter (#231)`
-
-2. **Update `ConcreteAgentRunner` to accept `RunnerDeps`** — change constructor from `RunnerIO` to `RunnerDeps`, update `.run()` to pass `this.deps`.
-   Update `concrete-agent-runner.test.ts`.
-   Add `createRunnerDeps()` helper to `test/helpers/runner-io.ts`.
-   Commit: `refactor: ConcreteAgentRunner accepts RunnerDeps (#231)`
-
-3. **Remove `exec` and `registry` from `RunContext`** — shrink the interface to 2 fields, update doc comment.
-   Strip `exec`/`registry` from `context:` in all runner test call sites.
-   Run `pnpm run check` to verify no stale references.
-   Commit: `refactor: remove exec and registry from RunContext (#231)`
-
-4. **Remove `exec` and `registry` from `AgentManager`** — remove from `AgentManagerOptions`, remove class fields, remove relay in `startAgent()`, clean up imports.
-   Update `agent-manager.test.ts` factory.
-   Commit: `refactor: remove relay deps from AgentManager (#231)`
-
-5. **Update wiring in `index.ts`** — move `exec` and `registry` from `AgentManager` construction to `ConcreteAgentRunner` construction.
-   Commit: `refactor: wire exec and registry to ConcreteAgentRunner (#231)`
-
-6. **Update architecture docs** — update `RunContext` description and field counts, mark Step 3 complete.
-   Commit: `docs: update architecture for runner self-contained (#231)`
-
-## Risks and Mitigations
-
-1. **Test churn** — ~20 `runAgent()` call sites change their last parameter pattern.
-   Mitigation: mechanical find-and-replace; assertions stay identical.
-2. **Step ordering** — Steps 3 and 4 both remove `exec`/`registry` from different types.
-   If done in the wrong order, intermediate commits may not type-check.
-   Mitigation: Step 1–2 add the new path (`deps`), Step 3 removes from `RunContext` (runner side), Step 4 removes from `AgentManager` (manager side), Step 5 wires them together.
-   Each commit is independently valid.
-3. **Import cleanup** — removing `exec`/`registry` from `AgentManager` may leave unused imports (`ShellExec`, `AgentTypeRegistry`).
-   Mitigation: grep for other usages before removing; `pnpm run check` catches unused imports.
-
-## Open Questions
-
-- None — the issue scope is narrow and the design is straightforward.