@gotgenes/pi-subagents 11.0.1 → 11.1.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.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)"]
@@ -266,9 +267,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 +348,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 +715,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()`.

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "11.0.1",
+  "version": "11.1.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,6 +11,7 @@ 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";
 
@@ -27,14 +28,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 +69,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 +145,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 +155,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.
@@ -247,7 +219,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 +267,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 +285,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 +302,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

@@ -363,7 +363,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 = [];
+	}
+}