@gotgenes/pi-subagents 11.0.1 → 11.2.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [11.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.1.0...pi-subagents-v11.2.0) (2026-05-28)
+
+
+### Features
+
+* add Agent.resume() with internal observer lifecycle ([6cffb47](https://github.com/gotgenes/pi-packages/commit/6cffb47079e385b0ccd12e358c12357291be2ef0))
+
+
+### Bug Fixes
+
+* release abort-signal listener when worktree setup fails ([ce2cac6](https://github.com/gotgenes/pi-packages/commit/ce2cac6788ffc90316f759e40e4df29576a70128))
+
+## [11.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.0.1...pi-subagents-v11.1.0) (2026-05-28)
+
+
+### Features
+
+* **pi-subagents:** add ConcurrencyQueue class ([#230](https://github.com/gotgenes/pi-packages/issues/230)) ([9fff9b7](https://github.com/gotgenes/pi-packages/commit/9fff9b7fc318ad8bf5ac3a218ee7bf1c5e11104b))
+
+
+### Documentation
+
+* **pi-subagents:** update architecture for ConcurrencyQueue extraction ([#230](https://github.com/gotgenes/pi-packages/issues/230)) ([4bd69e1](https://github.com/gotgenes/pi-packages/commit/4bd69e16164132400c7e0f9e4ecfd9f41842247a))
+
 ## [11.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.0.0...pi-subagents-v11.0.1) (2026-05-28)
 
 

package/docs/architecture/architecture.md

@@ -53,7 +53,8 @@ flowchart TB
 
     subgraph lifecycle["Lifecycle domain"]
         direction TB
-        AgentManager["AgentManager<br/>(spawn, queue, abort)"]
+        AgentManager["AgentManager<br/>(spawn, abort, collection)"]
+        ConcurrencyQueue["ConcurrencyQueue<br/>(scheduling, drain)"]
         AgentRunner["agent-runner<br/>(session, turns, results)"]
         Agent["Agent<br/>(status, behavior: abort/steer/worktree/run lifecycle)"]
         ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
@@ -120,6 +121,8 @@ classDiagram
         +markError()
         +markStopped()
         +resetForResume()
+        +run()
+        +resume(prompt, signal)
         +abort(): boolean
         +queueSteer(message)
         +flushPendingSteers(session)
@@ -135,7 +138,7 @@ classDiagram
     class AgentManager {
         +spawn(snapshot, type, prompt, config)
         +spawnAndWait(snapshot, type, prompt, config)
-        +resume(id, snapshot, exec)
+        +resume(id, prompt, signal)
         +getRecord(id): Agent
         +listAgents(): Agent[]
         +abort(id)
@@ -266,9 +269,10 @@ src/
 │   └── session-dir.ts              session directory derivation
 │
 ├── lifecycle/                      agent execution and state tracking
-│   ├── agent-manager.ts            collection manager + concurrency controller
+│   ├── agent-manager.ts            collection manager + observer wiring
 │   ├── agent-runner.ts             session creation, turn loop, tool filtering
 │   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, worktree)
+│   ├── concurrency-queue.ts        background agent scheduling with configurable concurrency limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
 │   ├── permission-bridge.ts        optional bridge to pi-permission-system registry
@@ -346,7 +350,8 @@ They declare this package as an optional peer dependency and use dynamic import
 ### What the core owns
 
 - The three tools: `subagent` (née `Agent`), `get_subagent_result`, `steer_subagent`.
-- `AgentManager` — spawn, queue, abort, resume, concurrency control.
+- `AgentManager` — spawn, abort, resume, collection management, observer wiring.
+- `ConcurrencyQueue` — background agent scheduling with configurable concurrency limit.
 - `agent-runner` — session creation, turn loop, extension binding.
 - `permission-bridge` — optional cross-extension bridge to `@gotgenes/pi-permission-system`; registers each child session with `SubagentSessionRegistry` before `bindExtensions()` so the permission system detects in-process children deterministically.
   Scheduled for removal in Phase 16 — replaced by lifecycle events that consumers listen for.
@@ -712,7 +717,7 @@ Agent receives three concerns at construction:
 5. Clean up worktree on completion or error.
 6. Transition status.
 
-`AgentManager` becomes a collection manager + concurrency controller:
+`AgentManager` becomes a collection manager + observer wiring:
 
 - Creates complete Agent objects, stores them in the map.
 - Decides when to run (immediate or queue) and calls `agent.run()`.
@@ -735,15 +740,15 @@ The scheduling concern (queue, concurrency counter, drain) is tangled into `Agen
 
 ### Findings summary
 
-| Finding                                                            | Category     | Impact | Risk | Priority |
-| ------------------------------------------------------------------ | ------------ | ------ | ---- | -------- |
-| ~~`AgentRecord` is anemic — no behavior, manager reaches in 37×~~  | B: Oversized | 5      | 3    | ✅       |
-| Agent cannot run itself — manager orchestrates 10 external touches | C: Coupling  | 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    | ✅       |
-| ~~`onSessionCreated` callback flows through 3 layers~~             | C: Callbacks | 3      | 2    | subsumed |
-| `resume()` duplicates observer subscribe/unsubscribe pattern       | A: Redundant | 2      | 1    | 8        |
-| `exec`/`registry` relay-only deps on `AgentManager`                | C: Coupling  | 2      | 1    | 6        |
+| Finding                                                                | Category     | Impact | Risk | Priority |
+| ---------------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
+| ~~`AgentRecord` is anemic — no behavior, manager reaches in 37×~~      | B: Oversized | 5      | 3    | ✅       |
+| ~~Agent cannot run itself — manager orchestrates 10 external touches~~ | C: Coupling  | 5      | 3    | ✅       |
+| ~~Scheduling tangled into `AgentManager` (3 fields, 3 methods)~~       | A: Coupling  | 4      | 2    | ✅       |
+| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~      | C: Callbacks | 3      | 2    | ✅       |
+| ~~`onSessionCreated` callback flows through 3 layers~~                 | C: Callbacks | 3      | 2    | subsumed |
+| ~~`resume()` duplicates observer subscribe/unsubscribe pattern~~       | A: Redundant | 2      | 1    | ✅       |
+| ~~`exec`/`registry` relay-only deps on `AgentManager`~~                | C: Coupling  | 2      | 1    | ✅       |
 
 ### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
 
@@ -809,7 +814,7 @@ Drain calls `agent.run()` directly — no worktree setup, no args threading.
 - Smell: A (tangled concerns) + C (cross-concern leak via `notifyConcurrencyChanged`)
 - Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable; queue interface is trivial (agent has everything)
 
-### Step 6: Agent.resume() with internal observer lifecycle — [#232]
+### Step 6: Agent.resume() with internal observer lifecycle — [#232] ✅
 
 Agent has the runner from construction.
 `Agent.resume(prompt, signal)` manages its own observer subscription lifecycle using the same internal wiring as `run()`.

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

@@ -0,0 +1,265 @@
+---
+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/0232-agent-resume-internal-observer-lifecycle.md

@@ -0,0 +1,180 @@
+---
+issue: 232
+issue_title: "Agent.resume() with internal observer lifecycle (Phase 15, Step 6)"
+---
+
+# Agent.resume() with internal observer lifecycle
+
+## Problem Statement
+
+After #229 (`Agent.run()` absorbs `startAgent`), the agent owns its entire run lifecycle but `AgentManager.resume()` still duplicates the observer subscribe/use/release pattern that `run()` handles internally.
+The manager manually calls `subscribeAgentObserver`, wraps `runner.resume()` in a try/catch/finally, marks completion/error, and unsubscribes — the same acquire → use → release resource shape `Agent.run()` already encapsulates.
+This is the last "manager reaches into Agent" duplication in the Phase 15 roadmap (priority 8, smell A: redundant pattern).
+
+## Goals
+
+- Add `Agent.resume(prompt, signal?)` that owns its observer subscription lifecycle, mirroring `run()`'s internal wiring.
+- Reduce `AgentManager.resume()` to a guard-plus-delegation method (no `subscribeAgentObserver`, no try/finally).
+- Preserve the existing public contract of `AgentManager.resume()` exactly: same signature, same `Agent | undefined` return, same behavior when the record or session is missing.
+- Keep the change non-breaking (`feat:`, not `feat!:`).
+
+## Non-Goals
+
+- No change to `runner.resume()` / `resumeAgent()` in `agent-runner.ts`.
+- No change to the abort semantics of resume — the parent `signal` continues to flow straight through to `runner.resume({ signal })` (resume does not route through the agent's `abortController`, matching today's behavior).
+- No queue interaction on resume — resume is not subject to the concurrency queue, so `onStarted`/`onRunFinished` are not fired (unchanged from today).
+- No full rewrite of the stale `AgentManager`/`Agent` class diagram in `architecture.md` — that diagram already diverged in #229 (missing `run()`, stale `setupWorktree`/`completeRun`/`setOnRunFinished` signatures); a comprehensive diagram refresh is out of scope here.
+
+## Background
+
+Relevant modules (all under `packages/pi-subagents/src/`):
+
+- `lifecycle/agent.ts` — the `Agent` class.
+  Already owns the per-run listener state (`_unsub`, `_detachFn`), the `attachObserver(unsub)` / `releaseListeners()` pair, `resetForResume(startedAt)` (which calls `releaseListeners()`), and `markCompleted` / `markError`.
+  Holds `_runner` and `observer` (an `AgentLifecycleObserver`) from construction (#229).
+  `Agent.run()` is the template to follow: it wires the observer via `attachObserver(subscribeAgentObserver(session, this, { onCompact: (r, info) => this.observer?.onCompacted?.(r, info) }))`.
+- `lifecycle/agent-manager.ts` — `AgentManager.resume()` currently does the manual subscribe/try-finally dance and imports `subscribeAgentObserver` solely for that.
+- `observation/record-observer.ts` — `subscribeAgentObserver(session, record, options)` returns an unsubscribe function; observes `tool_execution_end`, `message_end`, `compaction_end`.
+- `lifecycle/agent-runner.ts` — `AgentRunner.resume(session, prompt, options?)` returns `Promise<string>` (the response text).
+
+Constraint from AGENTS.md / `package-pi-subagents` skill: pi-subagents is a narrow core; this is a pure internal refactor (Tell-Don't-Ask, "state owns its mutations") with no policy or API-surface change.
+
+### Observer routing equivalence
+
+The manager's old resume wired compaction to the `AgentManagerObserver`:
+
+```typescript
+subscribeAgentObserver(session, record, {
+  onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+});
+```
+
+`Agent.resume()` instead routes through the per-agent `AgentLifecycleObserver` (`this.observer?.onCompacted?.`), exactly as `run()` does.
+That lifecycle observer is built by `AgentManager.buildObserver()`, whose `onCompacted` forwards to `this.observer?.onAgentCompacted(agent, info)`.
+Net routing is identical — compaction events still reach the manager-level `AgentManagerObserver.onAgentCompacted`.
+
+## Design Overview
+
+### `Agent.resume()`
+
+```typescript
+async resume(prompt: string, signal?: AbortSignal): Promise<void> {
+  if (!this._runner) {
+    throw new Error("Agent not configured for execution — missing runner");
+  }
+  const session = this.session;
+  if (!session) {
+    throw new Error("Agent not configured for resume — missing session");
+  }
+
+  this.resetForResume(Date.now()); // sets running, clears result/error, releases stale listeners
+  this.attachObserver(subscribeAgentObserver(session, this, {
+    onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+  }));
+
+  try {
+    const responseText = await this._runner.resume(session, prompt, { signal });
+    this.markCompleted(responseText);
+  } catch (err) {
+    this.markError(err);
+  } finally {
+    this.releaseListeners();
+  }
+}
+```
+
+Decision model:
+
+- `resetForResume()` already calls `releaseListeners()`, so any leftover handle from a prior run/resume is cleared before the new subscription is attached.
+- The new subscription handle is stored via `attachObserver()` (reusing the `_unsub` slot shared with `run()`), and released in `finally` via `releaseListeners()`.
+- Errors are captured (`markError`) rather than rethrown — `resume()` resolves like `run()`.
+- The two guards (missing runner, missing session) mirror `run()`'s guard style.
+  They are defensive: the manager guards `agent?.session` before delegating, so the session guard is unreachable in normal flow but protects the invariant for direct `Agent.resume()` callers/tests.
+
+### `AgentManager.resume()` (delegation)
+
+```typescript
+async resume(id: string, prompt: string, signal?: AbortSignal): Promise<Agent | undefined> {
+  const agent = this.agents.get(id);
+  if (!agent?.session) return undefined;
+  await agent.resume(prompt, signal);
+  return agent;
+}
+```
+
+Edge cases preserved:
+
+- Missing record → `undefined` (no throw).
+- Record present but no session → `undefined` (no throw).
+- Session present → delegate, return the agent.
+
+After this change `agent-manager.ts` no longer references `subscribeAgentObserver` — that import must be removed.
+`this.runner` is still used by `spawn()` (passed to the `Agent` constructor), so the `runner` field stays.
+
+## Module-Level Changes
+
+- `src/lifecycle/agent.ts`
+  - Add the public async method `resume(prompt: string, signal?: AbortSignal): Promise<void>` (placed near `run()` per the stepdown rule).
+  - No new imports — `subscribeAgentObserver` is already imported for `run()`.
+- `src/lifecycle/agent-manager.ts`
+  - Replace the body of `resume()` with the guard-plus-delegation form above.
+  - Remove the now-unused `import { subscribeAgentObserver } from "#src/observation/record-observer";`.
+  - No other methods change.
+- `src/lifecycle/agent-runner.ts` — unchanged.
+- `src/observation/record-observer.ts` — unchanged.
+- `docs/architecture/architecture.md` — light doc touch:
+  - In the class diagram, update `AgentManager.resume(id, snapshot, exec)` → `resume(id, prompt, signal)` and add `Agent.resume(prompt, signal)` (and, while there, `Agent.run()`, which #229 omitted).
+  - Mark Step 6 in the Phase 15 roadmap table/section as complete (`✅`).
+  - Note: the class diagram has pre-existing staleness from #229; this touch only corrects the resume-related entries, not the whole diagram.
+
+Symbol-removal check: the only removed symbol is the `subscribeAgentObserver` import in `agent-manager.ts`.
+`grep` confirms `subscribeAgentObserver` is still imported and used in `agent.ts` and defined in `record-observer.ts`, so the export stays live.
+
+No file in Module-Level Changes is claimed unchanged in Non-Goals (the Non-Goals list `agent-runner.ts` and `record-observer.ts`, which are genuinely untouched).
+
+## Test Impact Analysis
+
+This is an extraction/relocation of behavior from the manager into the agent.
+
+1. New unit tests enabled — `Agent.resume()` can now be tested directly on `Agent` (file `test/lifecycle/agent.test.ts`), which was previously impossible because resume logic lived only in the manager.
+   New direct coverage:
+   - `resume()` transitions to `completed` and sets `result` from the runner's response text.
+   - `resume()` transitions to `error` (and does not throw) when `runner.resume()` rejects.
+   - `resume()` subscribes the record-observer to the session (usage/compaction events accumulate on the agent) and releases the subscription in `finally` (handle cleared after completion and after error).
+   - `resume()` throws on missing runner / missing session (guard symmetry with `run()`).
+   - Compaction during resume forwards through `this.observer?.onCompacted?.`.
+
+2. Existing tests that become redundant — none should be deleted.
+   The two manager-level resume tests in `test/lifecycle/agent-manager.test.ts` (`resume() also accumulates usage and increments compactions on the same record` and `calls injected runner.resume when resuming an agent`) now exercise the delegation + observer-forwarding integration rather than the inlined logic.
+   They stay as integration coverage of `AgentManager.resume()` → `Agent.resume()` and the `onCompacted` → `onAgentCompacted` routing.
+   `test/helpers/make-deps.test.ts` (calls `manager.resume(...)`) stays.
+
+3. Existing tests that must stay as-is — the manager-level resume tests above genuinely exercise the manager's guard + delegation seam and the observer routing through `buildObserver`, which the agent-level tests do not cover.
+
+## TDD Order
+
+1. `test/lifecycle/agent.test.ts` — add `Agent.resume()` happy-path + error + guard tests, then implement `Agent.resume()` in `agent.ts`.
+   Covers: completed/result on success, error (no throw) on rejection, observer subscribe + `releaseListeners()` in `finally`, compaction forwarding via `onCompacted`, and the missing-runner / missing-session guards.
+   At this point both the new `Agent.resume()` and the old `AgentManager.resume()` body coexist (lift-and-shift: introduce the new method alongside the old logic).
+   Commit: `feat: add Agent.resume() with internal observer lifecycle`
+2. `test/lifecycle/agent-manager.test.ts` — keep the existing resume tests green, then collapse `AgentManager.resume()` to the guard-plus-delegation form and remove the unused `subscribeAgentObserver` import in the same commit.
+   Removing the import and rewriting the body must land together — the type checker flags the unused import immediately, and the existing manager-level resume tests verify the delegation still satisfies the same contract.
+   Commit: `refactor: delegate AgentManager.resume() to Agent.resume()`
+3. `docs/architecture/architecture.md` — update the class diagram resume entries (and add `Agent.run()`/`Agent.resume()`), mark Step 6 complete.
+   Commit: `docs: mark Phase 15 Step 6 (Agent.resume) complete`
+
+## Risks and Mitigations
+
+- Risk: observer routing diverges (compaction events stop reaching `onAgentCompacted`).
+  Mitigation: the existing manager-level test `resume() also accumulates usage and increments compactions on the same record` asserts `compactionCount` after resume; it stays green only if routing is preserved.
+- Risk: listener leak if `releaseListeners()` is missed on the error path.
+  Mitigation: `releaseListeners()` is in `finally`; a dedicated agent-level test asserts the unsub handle is released after both success and error.
+- Risk: behavior change in abort handling if resume is rerouted through `abortController`.
+  Mitigation: explicitly keep `signal` flowing straight to `runner.resume({ signal })` (Non-Goal), identical to today.
+- Risk: removing the `subscribeAgentObserver` import while another caller still needs it.
+  Mitigation: `grep` confirms `agent.ts` is the only other importer and `record-observer.ts` still exports it.
+
+## Open Questions
+
+- Whether to later refresh the full `AgentManager`/`Agent` class diagram in `architecture.md` (stale since #229).
+  Deferred — out of scope for this issue; a focused follow-up can resync the whole diagram.

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

@@ -0,0 +1,38 @@
+---
+issue: 230
+issue_title: "Extract ConcurrencyQueue from AgentManager (Phase 15, Step 5)"
+---
+
+# Retro: #230 — Extract ConcurrencyQueue from AgentManager
+
+## Stage: Planning (2026-05-28T20:00:00Z)
+
+### Session summary
+
+Produced a 3-step TDD plan for extracting the scheduling concern (3 fields, 3 methods) from `AgentManager` into a new `ConcurrencyQueue` class.
+Both dependencies (#229 Agent.run(), #231 runner self-contained) are confirmed closed.
+
+### Observations
+
+- The issue's proposed API has `drain(start: (id: string) => void)` but also `markFinished()` as no-arg with "running--, drain()" semantics — a contradiction.
+  Resolved by storing the `startAgent` callback at construction, making both `drain()` and `markFinished()` no-arg.
+  This follows Tell-Don't-Ask and matches the established forward-reference-via-closure pattern already used for `onMaxConcurrentChanged`.
+- `markFinished()` auto-drain changes the ordering from "decrement → observer → drain" to "decrement + drain → observer."
+  Verified this is safe: observer notification only processes the completed agent and drain only starts promises without awaiting.
+- `SettingsManager` does not change — only the callback wiring in `index.ts` changes target from `manager.notifyConcurrencyChanged()` to `queue.drain()`.
+- The `agent.ts` `abort()` method has a comment referencing #230 that should be updated in the implementation step.
+
+## Stage: Implementation — TDD (2026-05-28T21:35:00Z)
+
+### Session summary
+
+Implemented all 3 TDD steps: (1) `ConcurrencyQueue` class + 22 unit tests, (2) migrated `AgentManager` to use injected `ConcurrencyQueue` and updated `index.ts` wiring + test helper, (3) architecture docs and SKILL.md updates.
+Test count delta: 1020 → 1042 (+22 new `ConcurrencyQueue` tests, 0 removed).
+
+### Observations
+
+- The `createManager` test helper required the forward-reference-via-closure pattern (`let mgr` then closure then assignment) with a `prefer-const` ESLint suppression — same pattern used in production `index.ts` for `onMaxConcurrentChanged`.
+- Pre-completion reviewer returned WARN for one stale comment (`drainQueue` reference in `waitForAll`) — fixed by amending the docs commit.
+- No plan deviations.
+  All module-level changes matched the plan exactly.
+- Pre-completion reviewer: WARN → fixed (stale comment).

package/docs/retro/0232-agent-resume-internal-observer-lifecycle.md

@@ -0,0 +1,45 @@
+---
+issue: 232
+issue_title: "Agent.resume() with internal observer lifecycle (Phase 15, Step 6)"
+---
+
+# Retro: #232 — Agent.resume() with internal observer lifecycle (Phase 15, Step 6)
+
+## Stage: Planning (2026-05-28T18:00:00Z)
+
+### Session summary
+
+Produced a 3-step plan to move the observer subscribe/use/release pattern out of `AgentManager.resume()` into a new `Agent.resume(prompt, signal?)`, mirroring the `run()` wiring added in #229.
+This is the last "manager reaches into Agent" duplication in the Phase 15 roadmap (Step 6, priority 8).
+Confirmed the prerequisite #229 is closed and `Agent` already holds `_runner`, `observer`, `attachObserver`/`releaseListeners`, and `resetForResume`.
+
+### Observations
+
+- Non-breaking (`feat:`) — `AgentManager.resume()` keeps its signature and `Agent | undefined` contract; `Agent.resume()` is additive.
+  No `ask_user` needed; the issue's proposed change is concrete and unambiguous.
+- Observer routing equivalence verified: old code wired `onCompact` → `AgentManagerObserver.onAgentCompacted`; new code routes through the per-agent `AgentLifecycleObserver.onCompacted`, which `buildObserver()` forwards to `onAgentCompacted`.
+  Net routing identical.
+- Abort semantics intentionally preserved — `signal` flows straight to `runner.resume({ signal })`, not through the agent's `abortController` (resume differs from `run()` here; flagged as a Non-Goal to avoid accidental behavior change).
+- Removing the `subscribeAgentObserver` import from `agent-manager.ts` must land in the same commit as the body rewrite (type checker flags the unused import). `grep` confirmed `agent.ts` remains the importer and `record-observer.ts` keeps the export live.
+- Discovered the `architecture.md` class diagram is stale from #229 (missing `Agent.run()`, stale `setupWorktree`/`completeRun`/`setOnRunFinished` signatures, old `resume(id, snapshot, exec)`).
+  Scoped only a light touch (resume-related entries + Step 6 ✅); full diagram refresh deferred as a follow-up.
+- Lift-and-shift TDD order: step 1 introduces `Agent.resume()` alongside the old manager logic; step 2 collapses the manager method and removes the import together.
+  Existing manager-level resume tests act as the integration safety net and stay.
+
+## Stage: Implementation — TDD (2026-05-28T19:00:00Z)
+
+### Session summary
+
+Completed all 3 TDD steps in 3 commits plus a bonus `fix:` commit, totalling 4 new commits.
+`Agent.resume()` added with full observer lifecycle, `AgentManager.resume()` collapsed to guard-plus-delegation, `subscribeAgentObserver` import removed from `agent-manager.ts`, and `architecture.md` updated.
+Test count: 1042 → 1053 (+11).
+
+### Observations
+
+- **Bonus fix found mid-session:** A user question revealed a listener leak introduced in #229 — `Agent.run()` called `wireSignal()` before `setupWorktree()`, but the worktree-failure catch block returned without `releaseListeners()`, leaving the parent `AbortSignal` holding a reference to the errored agent.
+  Fixed TDD-style: failing test first (`"releases the parent-signal listener when worktree setup fails"` in `agent.test.ts`), then one-line fix adding `this.releaseListeners()` to the catch block in `run()`.
+  Committed as a separate `fix:` commit with a body attributing the regression to #229.
+- **Pre-completion reviewer: WARN** — one non-blocking finding: the Phase 15 findings-summary table in `architecture.md` didn't mark the resolved rows (consistent pre-existing pattern from #229–#231).
+  Fixed by adding strikethrough + ✅ to all four resolved finding rows (#229 "Agent cannot run itself", #230 "Scheduling", #231 "exec/registry", #232 "resume()") in an additional `docs:` commit.
+  All other reviewer checks passed (Mermaid diagrams validated with `mmdc`, fallow clean, code design clean).
+- **Reviewer warning resolved:** The findings table gap was pre-existing across four issues; closing it in this commit makes the table accurate going into Phase 16.

package/package.json

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

package/src/index.ts

@@ -25,6 +25,7 @@ import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
 import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runner";
+import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { GitWorktreeManager } from "#src/lifecycle/worktree";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
@@ -66,12 +67,12 @@ export default function (pi: ExtensionAPI) {
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
-  // onMaxConcurrentChanged is wired after manager is constructed (closure captures by reference).
+  // onMaxConcurrentChanged is wired to the queue directly (closure captures by reference).
   const settings = new SettingsManager({
     emit: (event, payload) => pi.events.emit(event, payload),
     cwd: process.cwd(),
     agentDir: getAgentDir(),
-    onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
+    onMaxConcurrentChanged: () => queue.drain(),
   });
   settings.load();
 
@@ -150,11 +151,22 @@ export default function (pi: ExtensionAPI) {
     registry,
   };
 
+  // ConcurrencyQueue: scheduling extracted from AgentManager.
+  // startAgent callback forward-references manager via closure (safe — drain is never called during construction).
+  const queue = new ConcurrencyQueue(
+    () => settings.maxConcurrent,
+    (id) => {
+      const agent = manager.getRecord(id);
+      if (agent?.status !== "queued") return;
+      agent.promise = agent.run();
+    },
+  );
+
   const manager = new AgentManager({
     runner: new ConcreteAgentRunner(runnerDeps),
     worktrees: new GitWorktreeManager(process.cwd()),
     observer,
-    getMaxConcurrent: () => settings.maxConcurrent,
+    queue,
     getRunConfig: () => settings,
   });
 

package/src/lifecycle/agent-manager.ts

@@ -11,10 +11,10 @@ import type { Model } from "@earendil-works/pi-ai";
 import { debugLog } from "#src/debug";
 import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
 import type { AgentRunner } from "#src/lifecycle/agent-runner";
+import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 
-import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
@@ -27,14 +27,11 @@ export interface AgentManagerObserver {
   onAgentCreated(record: Agent): void;
 }
 
-/** Default max concurrent background agents. */
-const DEFAULT_MAX_CONCURRENT = 4;
-
 export interface AgentManagerOptions {
   runner: AgentRunner;
   worktrees: WorktreeManager;
-  /** Injected getter for the concurrency limit - owned by SettingsManager. */
-  getMaxConcurrent?: () => number;
+  /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
+  queue: ConcurrencyQueue;
   getRunConfig?: () => RunConfig;
   observer?: AgentManagerObserver;
 }
@@ -71,44 +68,35 @@ export class AgentManager {
   private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
-  private readonly _getMaxConcurrent: () => number;
+  private readonly queue: ConcurrencyQueue;
   private getRunConfig?: () => RunConfig;
 
-  /** Queue of background agent IDs waiting to start. */
-  private queue: string[] = [];
-  /** Number of currently running background agents. */
-  private runningBackground = 0;
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
+    this.queue = options.queue;
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
-    this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
   }
 
-  /**
-   * Drain the concurrency queue after SettingsManager has updated maxConcurrent.
-   * Call this whenever the concurrency limit increases so queued agents can start.
-   */
-  notifyConcurrencyChanged(): void {
-    this.drainQueue();
-  }
-
   /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
   private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
     return {
       onStarted: (agent) => {
-        if (options.isBackground) this.runningBackground++;
+        if (options.isBackground) this.queue.markStarted();
         this.observer?.onAgentStarted(agent);
       },
       onSessionCreated: options.observer?.onSessionCreated
         ? (agent, session) => options.observer!.onSessionCreated!(agent, session)
         : undefined,
       onRunFinished: (agent) => {
-        if (options.isBackground) this.finalizeBackgroundRun(agent);
+        if (options.isBackground) {
+          this.queue.markFinished();
+          try { this.observer?.onAgentCompleted(agent); } catch (err) { debugLog("onAgentCompleted observer", err); }
+        }
       },
       onCompacted: (agent, info) => {
         this.observer?.onAgentCompacted(agent, info);
@@ -156,9 +144,9 @@ export class AgentManager {
       this.observer?.onAgentCreated(record);
     }
 
-    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
+    if (options.isBackground && !options.bypassQueue && this.queue.isFull()) {
       // Queue it - will be started when a running agent completes
-      this.queue.push(id);
+      this.queue.enqueue(id);
       return id;
     }
 
@@ -166,23 +154,6 @@ export class AgentManager {
     return id;
   }
 
-  /** Decrement background counter, notify observer (crash-safe), and drain the queue. */
-  private finalizeBackgroundRun(record: Agent): void {
-    this.runningBackground--;
-    try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
-    this.drainQueue();
-  }
-
-  /** Start queued agents up to the concurrency limit. */
-  private drainQueue() {
-    while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
-      const id = this.queue.shift()!;
-      const record = this.agents.get(id);
-      if (record?.status !== "queued") continue;
-      record.promise = record.run();
-    }
-  }
-
   /**
    * Spawn an agent and wait for completion (foreground use).
    * Foreground agents bypass the concurrency queue.
@@ -201,34 +172,17 @@ export class AgentManager {
 
   /**
    * Resume an existing agent session with a new prompt.
+   * Delegates to Agent.resume(), which owns the observer subscription lifecycle.
    */
   async resume(
     id: string,
     prompt: string,
     signal?: AbortSignal,
   ): Promise<Agent | undefined> {
-    const record = this.agents.get(id);
-    const session = record?.session;
-    if (!session) return undefined;
-
-    record.resetForResume(Date.now());
-
-    const unsubResume = subscribeAgentObserver(session, record, {
-      onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-    });
-
-    try {
-      const responseText = await this.runner.resume(session, prompt, {
-        signal,
-      });
-      record.markCompleted(responseText);
-    } catch (err) {
-      record.markError(err);
-    } finally {
-      unsubResume();
-    }
-
-    return record;
+    const agent = this.agents.get(id);
+    if (!agent?.session) return undefined;
+    await agent.resume(prompt, signal);
+    return agent;
   }
 
   getRecord(id: string): Agent | undefined {
@@ -247,7 +201,7 @@ export class AgentManager {
 
     // Remove from queue if queued
     if (record.status === "queued") {
-      this.queue = this.queue.filter(qid => qid !== id);
+      this.queue.dequeue(id);
       record.markStopped();
       return true;
     }
@@ -295,14 +249,14 @@ export class AgentManager {
   abortAll(): number {
     let count = 0;
     // Clear queued agents first
-    for (const id of this.queue) {
+    for (const id of this.queue.queuedIds) {
       const record = this.agents.get(id);
       if (record) {
         record.markStopped();
         count++;
       }
     }
-    this.queue = [];
+    this.queue.clear();
     // Abort running agents
     for (const record of this.agents.values()) {
       if (record.abort()) count++;
@@ -313,11 +267,11 @@ export class AgentManager {
   /** Wait for all running and queued agents to complete (including queued ones). */
   // fallow-ignore-next-line unused-class-member
   async waitForAll(): Promise<void> {
-    // Loop because drainQueue respects the concurrency limit - as running
+    // Loop because queue.drain() respects the concurrency limit - as running
     // agents finish they start queued ones, which need awaiting too.
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop with explicit break
     while (true) {
-      this.drainQueue();
+      this.queue.drain();
       const pending = [...this.agents.values()]
         .filter(r => r.status === "running" || r.status === "queued")
         .map(r => r.promise)
@@ -330,7 +284,7 @@ export class AgentManager {
   dispose() {
     clearInterval(this.cleanupInterval);
     // Clear queue
-    this.queue = [];
+    this.queue.clear();
     for (const record of this.agents.values()) {
       record.session?.dispose();
     }

package/src/lifecycle/agent.ts

@@ -250,6 +250,7 @@ export class Agent {
 			this.setupWorktree();
 		} catch (err) {
 			this.markError(err);
+			this.releaseListeners();
 			this.observer?.onRunFinished?.(this);
 			return;
 		}
@@ -285,6 +286,39 @@ export class Agent {
 		}
 	}
 
+	/**
+	 * Resume an existing session with a new prompt, managing the observer
+	 * subscription lifecycle internally (same wiring as run()).
+	 *
+	 * Requires runner and an existing session (set when the original run created it).
+	 * The returned promise always resolves (errors are captured internally).
+	 * The parent signal flows straight through to runner.resume — resume does not
+	 * route through this.abortController.
+	 */
+	async resume(prompt: string, signal?: AbortSignal): Promise<void> {
+		if (!this._runner) {
+			throw new Error("Agent not configured for execution — missing runner");
+		}
+		const session = this.session;
+		if (!session) {
+			throw new Error("Agent not configured for resume — missing session");
+		}
+
+		this.resetForResume(Date.now());
+		this.attachObserver(subscribeAgentObserver(session, this, {
+			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		}));
+
+		try {
+			const responseText = await this._runner.resume(session, prompt, { signal });
+			this.markCompleted(responseText);
+		} catch (err) {
+			this.markError(err);
+		} finally {
+			this.releaseListeners();
+		}
+	}
+
 	/** Increment tool use count. Called by record-observer on tool_execution_end. */
 	incrementToolUses(): void {
 		this._toolUses++;
@@ -363,7 +397,7 @@ export class Agent {
 	/**
 	 * Abort a running agent: fire AbortController and transition to stopped.
 	 * Returns false if the agent is not running.
-	 * Queue removal stays on AgentManager until #230 extracts ConcurrencyQueue.
+	 * Queue removal is handled by AgentManager via ConcurrencyQueue.dequeue().
 	 */
 	abort(): boolean {
 		if (this._status !== "running") return false;

package/src/lifecycle/concurrency-queue.ts

@@ -0,0 +1,63 @@
+/**
+ * concurrency-queue.ts — Manages background agent scheduling with a configurable concurrency limit.
+ *
+ * Stores agent IDs (not full agent objects) and decides *when* to start them.
+ * The startAgent callback provided at construction handles the actual agent lifecycle.
+ */
+
+export class ConcurrencyQueue {
+	private queue: string[] = [];
+	private running = 0;
+
+	constructor(
+		private readonly getMaxConcurrent: () => number,
+		private readonly startAgent: (id: string) => void,
+	) {}
+
+	/** Whether the concurrency limit has been reached. */
+	isFull(): boolean {
+		return this.running >= this.getMaxConcurrent();
+	}
+
+	/** Add an agent ID to the wait queue. */
+	enqueue(id: string): void {
+		this.queue.push(id);
+	}
+
+	/** Remove an agent ID from the queue (e.g., aborted before starting). Returns true if found. */
+	dequeue(id: string): boolean {
+		const idx = this.queue.indexOf(id);
+		if (idx === -1) return false;
+		this.queue.splice(idx, 1);
+		return true;
+	}
+
+	/** Increment the running count. Called when an agent transitions to running. */
+	markStarted(): void {
+		this.running++;
+	}
+
+	/** Decrement the running count and drain the queue. Called when a background agent finishes. */
+	markFinished(): void {
+		this.running--;
+		this.drain();
+	}
+
+	/** Start queued agents until the concurrency limit is reached. */
+	drain(): void {
+		while (this.queue.length > 0 && !this.isFull()) {
+			const id = this.queue.shift()!;
+			this.startAgent(id);
+		}
+	}
+
+	/** Snapshot of queued IDs for iteration (e.g., abortAll). */
+	get queuedIds(): readonly string[] {
+		return this.queue;
+	}
+
+	/** Clear the queue without starting any agents. */
+	clear(): void {
+		this.queue = [];
+	}
+}