fix(swarm): release domain-pool agents after terminal tasks

[Tong-bit-art]

Problem and change

UnifiedSwarmCoordinator.assignTaskToDomain() acquires its worker through AgentPool.acquire(), which moves that agent from available to busy. The terminal task paths only reset the shared AgentState:

• handleTaskComplete() sets agent.status = 'idle' / currentTask = undefined
• handleTaskFail()'s final-failure branch does the same
• cancelTask() does the same

None of them call releaseAgentToDomain(). AgentPool.release() is the only operation that removes the id from busy and returns it to available; releaseAgentToDomain() is also the only code that drains domainTaskQueues. It had zero callers in src/ (git grep at 1882006a0; git log -S releaseAgentToDomain shows only the introducing commit 53cfd8a53).

Consequences in the documented API flow (README assignTaskToDomain() / executeParallel(), and QueenCoordinator.executeDelegation()):

• each terminal domain task permanently consumes one pool slot;
• once a domain pool reaches its fixed cap (core 5, security/integration/support 3, queen 1), pool.acquire() returns undefined and further tasks sit in domainTaskQueues;
• nothing drains those queues, so getStatus() shows availableAgents: 0 / tasksQueued growing and executeParallel() waits until its task timeout.

Change: release the acquired domain agent after a non-terminal to terminal transition, on completion, terminal failure, and cancellation. The release also assigns the next queued task for that domain. Retries are deliberately unchanged: handleTaskFail() re-queues through assignTask(), which may hand the task back to the same agent, so releasing there would race that reassignment.

Two drain-path guards are part of the same change because making release() reachable exposes both failure modes:

• AgentPool.release() normally calls checkScaling(), and a one-agent domain (queen, maxSize: 1) would scale to zero before the queued task can be dispatched; the next acquire() would then create a pool-only agent absent from coordinator state. release() accepts an optional { rescale: false }, used when an assignable task is waiting, so the freed slot is handed to that task first.
• A cancelled or timed-out task can remain in domainTaskQueues. The drain now skips any entry whose status is no longer queued/created, so releasing a slot cannot resurrect a terminal task and send it to a worker.

Validation

• 6 new public-path regressions in v3/@claude-flow/swarm/__tests__/domain-pool-agent-release.test.ts.
• Against main 1882006a0: 6/6 fail (the busy set retains the completed/failed/cancelled agent; queued tasks stay queued; the one-agent queen case is assigned to a pool-only id).
• Candidate on main: 6/6 pass; full @claude-flow/swarm suite 283/283, 19/19 files; tsc --noEmit 0 errors; git diff --check clean.

Relationship to #4244

#4244 (fix(swarm): keep coordinator cancellation terminal) touches the same handlers, but this change is independent on current main: it includes wasTerminal guards so a late/duplicate terminal report cannot free an agent that has since been reassigned. It does not fix the cancellation-retry race that #4244 addresses. If #4244 lands first, the guards here can be narrowed during rebase; if this lands first, #4244 can keep its terminal-state logic.

Scope / known limitations

• Retry path: if a retry is assigned to a different agent, the original agent can still retain its pool slot. That is a separate follow-up (same ownership root cause) and is intentionally not folded in here.
• AgentPool.acquire() can create a pool-only agent that is not registered in coordinator state; the one-agent queue path is guarded here, but the general empty-pool acquisition path is a separate fix in fix(swarm): stop domain pools from creating unregistered agents #4246.
• submitTask() auto-assignment followed by assignTaskToDomain() can leave the first generic agent busy; separate follow-up.
• Timeout (waitForTaskCompletion() / waitForQueuedTask()) is a client-side deadline and still does not release; releasing there would double-book an agent that may still be working. Not changed.
• @claude-flow/swarm is a standalone leaf package (not a dependency of @claude-flow/cli); blast radius is the published package and its consumers, matching the scope of prior merged swarm fixes dream(swarm): #3538 fix spawnAgent() auto-domain branch skipping pool.add() (evaluated, ACCEPT-scoped) #3539 / dream(swarm): #3242 fix AgentPool health checks that could never detect a dead agent (evaluated, ACCEPT-scoped) #3243.

Compatibility

• No public method signatures or return shapes changed. AgentPool.release() gains an optional { rescale?: boolean } parameter; existing calls behave exactly as before.
• releaseAgentToDomain() behavior is unchanged for callers; the new releaseDomainAgent() helper only calls it for agents the pool actually owns.
• Adds one additive SwarmEventType: agent.domain_release_failed, emitted only when pool bookkeeping fails; task completion/failure still resolves.
• No dependency, lockfile, or persistence-format changes.

Interaction with the domain-pool no-autoscale fix

If the separate fix(swarm): stop domain pools from creating unregistered agents change lands first, checkScaling() becomes a no-op for domain pools, so the { rescale: false } parameter added here is redundant. A rebase can drop that parameter and the corresponding agent-pool.ts/types.ts hunks; no conflict is expected.