feat(core): limit background agent concurrency

[kkhomej33-netizen]

Summary

• What changed:
  • Add a configurable cap for concurrently running background agents.
  • Return a clear tool result when a new background agent cannot start because the cap is reached.
  • Keep the final registry check as the race guard while preflighting before background launch side effects.
• Why it changed:
  • Background agents run independent reasoning loops. Without a cap, repeated run_in_background launches can consume API quota and local resources without backpressure.
• Reviewer focus:
  • The cap applies only to running background agents, not foreground agent rows or paused/terminal entries.
  • The agent tool preflight happens before hooks, worktree setup, child agent setup, and transcript creation.

Validation

• Commands run:

  cd packages/core && npx vitest run src/agents/background-tasks.test.ts src/tools/agent/agent.test.ts
  cd packages/core && npm run typecheck
  cd packages/core && npm run lint
  cd packages/core && npm run build
  git diff --check

• Prompts / inputs used:
  • Started the bundled CLI with QWEN_CODE_MAX_BACKGROUND_AGENTS=1 node dist/cli.js.
  • Asked the main agent to start one background agent analyzing packages/core/src/tools/agent/agent.ts.
  • Asked it to start another background agent analyzing packages/core/src/agents/background-tasks.ts before the first completed.
• Expected result:
  • The first background agent starts.
  • The second background agent is rejected with a clear maximum-concurrency message.
  • The already-running background agent remains active.
• Observed result:
  • The first agent remained active.
  • The second launch returned: Cannot start background agent: maximum concurrent background agents (1) reached. Stop an existing agent first.
• Quickest reviewer verification path:
  • Run QWEN_CODE_MAX_BACKGROUND_AGENTS=1 node dist/cli.js.
  • Launch two agent tool calls with run_in_background: true before the first completes.
• Evidence (output, logs, screenshots, video, JSON, before/after, etc.):
  • Manual TUI acceptance screenshot captured the second agent launch failing with the expected message while the first background agent remained active.

Scope / Risk

• Main risk or tradeoff:
  • The default cap is 10. Workflows that intentionally launch more than 10 concurrent background agents must opt in with QWEN_CODE_MAX_BACKGROUND_AGENTS.
• Not covered / not validated:
  • Full cross-platform integration suites were not run.
  • Root npm run build is currently blocked in this checkout by existing packages/cli/src/serve/* ACP bridge/status type errors unrelated to this change.
• Breaking changes / migration notes:
  • No API migration is required. Users can raise the cap with QWEN_CODE_MAX_BACKGROUND_AGENTS=<n>.

Testing Matrix

	🍏	🪟	🐧
npm run	✅	⚠️	⚠️
npx	✅	⚠️	⚠️
Docker	⚠️	N/A	⚠️
Podman	⚠️	N/A	N/A
Seatbelt	⚠️	N/A	N/A

Testing matrix notes:

• macOS package-level npm run build, npm run typecheck, and npm run lint passed in packages/core.
• macOS npx vitest run src/agents/background-tasks.test.ts src/tools/agent/agent.test.ts passed in packages/core.
• Docker, Podman, Seatbelt, Windows, and Linux were not run for this focused registry/tool change.

Linked Issues / Bugs

[kkhomej33-netizen]

E2E Test Report

Manual TUI acceptance was run with:

QWEN_CODE_MAX_BACKGROUND_AGENTS=1 node dist/cli.js

Scenario:

1. Start one background agent analyzing packages/core/src/tools/agent/agent.ts.
2. Before it completes, ask the main agent to start another background agent analyzing packages/core/src/agents/background-tasks.ts.

Expected:

• The first background agent remains active.
• The second launch is rejected with the concurrency-limit message.

Observed:

• The footer showed one active local agent.
• The second launch returned:

Cannot start background agent: maximum concurrent background agents (1) reached. Stop an existing agent first.

This matches the expected behavior for the new background-agent concurrency cap.