feat(concurrency): prevent background task races and leaks

Ensure queue waiters settle once, centralize completion with status guards, and release slots before async work so shutdown and cancellations don’t leak concurrency. Internal hardening only.

src/features/background-agent/concurrency.ts

@@ -1,9 +1,21 @@
 import type { BackgroundTaskConfig } from "../../config/schema"
 
+/**
+ * Queue entry with settled-flag pattern to prevent double-resolution.
+ *
+ * The settled flag ensures that cancelWaiters() doesn't reject
+ * an entry that was already resolved by release().
+ */
+interface QueueEntry {
+  resolve: () => void
+  rawReject: (error: Error) => void
+  settled: boolean
+}
+
 export class ConcurrencyManager {
   private config?: BackgroundTaskConfig
   private counts: Map<string, number> = new Map()
-  private queues: Map<string, Array<() => void>> = new Map()
+  private queues: Map<string, QueueEntry[]> = new Map()
 
   constructor(config?: BackgroundTaskConfig) {
     this.config = config
@@ -38,9 +50,20 @@ export class ConcurrencyManager {
       return
     }
 
-    return new Promise<void>((resolve) => {
+    return new Promise<void>((resolve, reject) => {
       const queue = this.queues.get(model) ?? []
-      queue.push(resolve)
+
+      const entry: QueueEntry = {
+        resolve: () => {
+          if (entry.settled) return
+          entry.settled = true
+          resolve()
+        },
+        rawReject: reject,
+        settled: false,
+      }
+
+      queue.push(entry)
       this.queues.set(model, queue)
     })
   }
@@ -52,15 +75,63 @@ export class ConcurrencyManager {
     }
 
     const queue = this.queues.get(model)
-    if (queue && queue.length > 0) {
+
+    // Try to hand off to a waiting entry (skip any settled entries from cancelWaiters)
+    while (queue && queue.length > 0) {
       const next = queue.shift()!
-      this.counts.set(model, this.counts.get(model) ?? 0)
-      next()
-    } else {
-      const current = this.counts.get(model) ?? 0
-      if (current > 0) {
-        this.counts.set(model, current - 1)
+      if (!next.settled) {
+        // Hand off the slot to this waiter (count stays the same)
+        next.resolve()
+        return
       }
     }
+
+    // No handoff occurred - decrement the count to free the slot
+    const current = this.counts.get(model) ?? 0
+    if (current > 0) {
+      this.counts.set(model, current - 1)
+    }
+  }
+
+  /**
+   * Cancel all waiting acquires for a model. Used during cleanup.
+   */
+  cancelWaiters(model: string): void {
+    const queue = this.queues.get(model)
+    if (queue) {
+      for (const entry of queue) {
+        if (!entry.settled) {
+          entry.settled = true
+          entry.rawReject(new Error(`Concurrency queue cancelled for model: ${model}`))
+        }
+      }
+      this.queues.delete(model)
+    }
+  }
+
+  /**
+   * Clear all state. Used during manager cleanup/shutdown.
+   * Cancels all pending waiters.
+   */
+  clear(): void {
+    for (const [model] of this.queues) {
+      this.cancelWaiters(model)
+    }
+    this.counts.clear()
+    this.queues.clear()
+  }
+
+  /**
+   * Get current count for a model (for testing/debugging)
+   */
+  getCount(model: string): number {
+    return this.counts.get(model) ?? 0
+  }
+
+  /**
+   * Get queue length for a model (for testing/debugging)
+   */
+  getQueueLength(model: string): number {
+    return this.queues.get(model)?.length ?? 0
   }
 }