feat(core): limit background agent concurrency

packages/core/src/agents/background-agent-resume.test.ts

@@ -455,6 +455,144 @@ describe('BackgroundAgentResumeService', () => {
     });
   });
 
+  it('can resume into the final background concurrency slot', async () => {
+    registry = new BackgroundTaskRegistry({
+      maxConcurrentBackgroundAgents: 1,
+    });
+    const sessionId = 'session-resume-cap';
+    const agentId = 'agent-resume-cap';
+    const metaPath = getAgentMetaPath(tempDir, sessionId, agentId);
+    const outputFile = getAgentJsonlPath(tempDir, sessionId, agentId);
+
+    writeAgentMeta(metaPath, {
+      agentId,
+      agentType: 'researcher',
+      description: 'Resume at cap',
+      parentSessionId: sessionId,
+      parentAgentId: null,
+      createdAt: '2026-04-20T00:00:00.000Z',
+      status: 'running',
+      subagentName: 'researcher',
+      resolvedApprovalMode: 'default',
+    });
+    fs.writeFileSync(
+      outputFile,
+      JSON.stringify({
+        uuid: 'u1',
+        parentUuid: null,
+        sessionId,
+        timestamp: '2026-04-20T00:00:00.000Z',
+        type: 'user',
+        message: { role: 'user', parts: [{ text: 'Resume at cap' }] },
+      }) + '\n',
+      'utf8',
+    );
+
+    registry.register({
+      agentId,
+      description: 'Resume at cap',
+      subagentType: 'researcher',
+      isBackgrounded: true,
+      status: 'paused',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+      prompt: 'Resume at cap',
+      outputFile,
+      metaPath,
+    });
+
+    const subagent = {
+      execute: vi.fn(async () => undefined),
+      setExternalMessageProvider: vi.fn(),
+      getCore: () => ({ getEventEmitter: () => new AgentEventEmitter() }),
+      getExecutionSummary: () => ({
+        totalTokens: 0,
+        totalDurationMs: 0,
+      }),
+      getTerminateMode: () => AgentTerminateMode.GOAL,
+      getFinalText: () => 'done',
+    };
+
+    const { service, subagentManager } = createService();
+    subagentManager.createAgentHeadless.mockResolvedValue(subagent);
+
+    const resumed = await service.resumeBackgroundAgent(agentId, 'continue');
+
+    expect(resumed).toBeDefined();
+    await vi.waitFor(() => {
+      expect(registry.get(agentId)?.status).toBe('completed');
+    });
+    expect(subagent.execute).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps a paused agent paused when resume cannot claim a background slot', async () => {
+    registry = new BackgroundTaskRegistry({
+      maxConcurrentBackgroundAgents: 1,
+    });
+    const sessionId = 'session-resume-full';
+    const agentId = 'agent-resume-full';
+    const metaPath = getAgentMetaPath(tempDir, sessionId, agentId);
+    const outputFile = getAgentJsonlPath(tempDir, sessionId, agentId);
+
+    registry.register({
+      agentId: 'already-running',
+      description: 'Already running',
+      subagentType: 'researcher',
+      isBackgrounded: true,
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+      outputFile: path.join(tempDir, 'already-running.jsonl'),
+    });
+
+    writeAgentMeta(metaPath, {
+      agentId,
+      agentType: 'researcher',
+      description: 'Resume while full',
+      parentSessionId: sessionId,
+      parentAgentId: null,
+      createdAt: '2026-04-20T00:00:00.000Z',
+      status: 'running',
+      subagentName: 'researcher',
+      resolvedApprovalMode: 'default',
+    });
+    fs.writeFileSync(
+      outputFile,
+      JSON.stringify({
+        uuid: 'u1',
+        parentUuid: null,
+        sessionId,
+        timestamp: '2026-04-20T00:00:00.000Z',
+        type: 'user',
+        message: { role: 'user', parts: [{ text: 'Resume while full' }] },
+      }) + '\n',
+      'utf8',
+    );
+    registry.register({
+      agentId,
+      description: 'Resume while full',
+      subagentType: 'researcher',
+      isBackgrounded: true,
+      status: 'paused',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+      prompt: 'Resume while full',
+      outputFile,
+      metaPath,
+    });
+
+    const { service, subagentManager } = createService();
+
+    const resumed = await service.resumeBackgroundAgent(agentId, 'continue');
+
+    expect(resumed).toBeUndefined();
+    expect(registry.get(agentId)?.status).toBe('paused');
+    expect(registry.get(agentId)?.error).toContain(
+      'maximum concurrent background agents (1) reached',
+    );
+    expect(subagentManager.createAgentHeadless).not.toHaveBeenCalled();
+  });
+
   it('passes the sidechain transcript path to SubagentStop hooks on resume', async () => {
     const sessionId = 'session-stop-hook';
     const agentId = 'agent-stop-hook';

packages/core/src/agents/background-agent-resume.ts

@@ -487,18 +487,32 @@ export class BackgroundAgentResumeService {
 
     const bgAbortController = new AbortController();
 
-    registry.register({
-      ...existing,
-      status: 'running',
-      abortController: bgAbortController,
-      endTime: undefined,
-      result: undefined,
-      error: undefined,
-      resumeBlockedReason: undefined,
-      stats: undefined,
-      recentActivities: [],
-      pendingMessages: [...(existing.pendingMessages ?? [])],
-    });
+    try {
+      registry.register({
+        ...existing,
+        status: 'running',
+        abortController: bgAbortController,
+        endTime: undefined,
+        result: undefined,
+        error: undefined,
+        resumeBlockedReason: undefined,
+        stats: undefined,
+        recentActivities: [],
+        pendingMessages: [...(existing.pendingMessages ?? [])],
+      });
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      debugLogger.warn(
+        `[BackgroundAgentResume] Cannot resume background agent ${agentId}: ${errorMessage}`,
+      );
+      patchAgentMeta(metaPath, {
+        lastError: errorMessage,
+        lastUpdatedAt: new Date().toISOString(),
+      });
+      this.restorePausedEntry(agentId, { error: errorMessage });
+      return undefined;
+    }
 
     let cleanupOwnedMonitorNotifications: (() => void) | undefined;
     let cleanupJsonl: (() => void) | undefined;

packages/core/src/agents/background-tasks.test.ts

@@ -6,12 +6,33 @@
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
+  BACKGROUND_AGENT_CONCURRENCY_ENV,
   BackgroundTaskRegistry,
+  DEFAULT_MAX_CONCURRENT_BACKGROUND_AGENTS,
+  MAX_CONCURRENT_BACKGROUND_AGENTS,
   MAX_RETAINED_TERMINAL_AGENTS,
+  resolveMaxConcurrentBackgroundAgents,
+  type AgentTaskRegistration,
   type BackgroundTaskEntry,
 } from './background-tasks.js';
 import * as transcript from './agent-transcript.js';
 
+function makeRegistration(
+  agentId: string,
+  overrides: Partial<AgentTaskRegistration> = {},
+): AgentTaskRegistration {
+  return {
+    agentId,
+    description: agentId,
+    status: 'running',
+    startTime: Date.now(),
+    abortController: new AbortController(),
+    isBackgrounded: true,
+    outputFile: `/tmp/${agentId}.jsonl`,
+    ...overrides,
+  };
+}
+
 describe('BackgroundTaskRegistry', () => {
   let registry: BackgroundTaskRegistry;
 
@@ -343,6 +364,86 @@ describe('BackgroundTaskRegistry', () => {
     expect(running[0].agentId).toBe('b');
   });
 
+  describe('background concurrency limit', () => {
+    it('resolves the default and env override for the background agent cap', () => {
+      expect(resolveMaxConcurrentBackgroundAgents({})).toBe(
+        DEFAULT_MAX_CONCURRENT_BACKGROUND_AGENTS,
+      );
+      expect(
+        resolveMaxConcurrentBackgroundAgents({
+          [BACKGROUND_AGENT_CONCURRENCY_ENV]: '3',
+        }),
+      ).toBe(3);
+      expect(
+        resolveMaxConcurrentBackgroundAgents({
+          [BACKGROUND_AGENT_CONCURRENCY_ENV]: '0',
+        }),
+      ).toBe(DEFAULT_MAX_CONCURRENT_BACKGROUND_AGENTS);
+      expect(MAX_CONCURRENT_BACKGROUND_AGENTS).toBeGreaterThanOrEqual(1);
+    });
+
+    it('rejects new running background agents once the cap is reached', () => {
+      registry = new BackgroundTaskRegistry({
+        maxConcurrentBackgroundAgents: 2,
+      });
+
+      registry.register(makeRegistration('bg-1'));
+      registry.register(makeRegistration('bg-2'));
+
+      expect(() => registry.register(makeRegistration('bg-3'))).toThrow(
+        'Cannot start background agent: maximum concurrent background agents ' +
+          '(2) reached. Stop an existing agent first.',
+      );
+      expect(registry.get('bg-3')).toBeUndefined();
+    });
+
+    it('allows replacing the same running background agent at the cap', () => {
+      registry = new BackgroundTaskRegistry({
+        maxConcurrentBackgroundAgents: 1,
+      });
+
+      registry.register(makeRegistration('bg-1'));
+
+      expect(() =>
+        registry.register(
+          makeRegistration('bg-1', {
+            prompt: 'resumed continuation',
+          }),
+        ),
+      ).not.toThrow();
+      expect(registry.get('bg-1')?.prompt).toBe('resumed continuation');
+    });
+
+    it('does not count foreground, paused, or terminal entries toward the cap', () => {
+      registry = new BackgroundTaskRegistry({
+        maxConcurrentBackgroundAgents: 1,
+      });
+
+      registry.register(
+        makeRegistration('fg-1', {
+          isBackgrounded: false,
+        }),
+      );
+      registry.register(
+        makeRegistration('paused-1', {
+          status: 'paused',
+        }),
+      );
+
+      registry.register(makeRegistration('bg-1'));
+      expect(() => registry.register(makeRegistration('bg-2'))).toThrow(
+        'maximum concurrent background agents (1) reached',
+      );
+
+      registry.complete('bg-1', 'done');
+      registry.register(makeRegistration('bg-2'));
+
+      expect(registry.get('fg-1')).toBeDefined();
+      expect(registry.get('paused-1')).toBeDefined();
+      expect(registry.get('bg-2')?.status).toBe('running');
+    });
+  });
+
   it('aborts all running agents and emits fallback notifications', () => {
     const callback = vi.fn();
     registry.setNotificationCallback(callback);