fix(workers): cleanup background processes and avoid default background fan-out

[blackms]

Summary

• fix headless worker timeout/cancel cleanup so child processes stay tracked until exit
• add SIGTERM -> SIGKILL escalation with configurable grace period (killGraceMs)
• prevent forced background teammate execution by default (runInBackground now defaults to false)
• expose optional runInBackground in teammate_spawn MCP input schema
• soften generated CLAUDE.md swarm guidance to avoid always-on background fan-out
• add targeted regression tests for process cleanup + teammate MCP/background defaults

Validation

• cd v3/plugins/teammate-plugin && npm test
• cd v3/plugins/teammate-plugin && npm run build
• cd v3/@claude-flow/cli && npm test -- __tests__/services/headless-worker-executor.cleanup.test.ts __tests__/services/headless-worker-executor.test.ts
• cd v3/@claude-flow/cli && npx tsc --noEmit --pretty false --module NodeNext --target ES2022 --moduleResolution NodeNext src/services/headless-worker-executor.ts

References

• Closes [Upstream #1042] Memory leak: Background agents not cleaned up after task completion #8
• Upstream issue: Memory leak: Background agents not cleaned up after task completion ruvnet/ruflo#1042

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Enhanced process cleanup and termination workflow with graceful shutdown and configurable grace period.
  • Optimized agent spawning to use single-message parallel execution model.

• Behavior Changes

  • Background task execution default changed from automatic to opt-in (disabled by default).

• Tests

  • Added test coverage for process termination and agent spawning flows.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

The changes implement graceful process termination with timeout escalation in HeadlessWorkerExecutor, modify the teammate spawning tool to make runInBackground configurable with a default of false, update related protocol documentation, and introduce comprehensive test coverage for the new termination flow and background execution behavior.

Changes

Cohort / File(s)	Summary
HeadlessWorkerExecutor Termination Flow v3/@claude-flow/cli/src/services/headless-worker-executor.ts	Added graceful shutdown mechanism with configurable grace period (killGraceMs), SIGTERM→SIGKILL escalation, and refined cleanup pathways. Integrated termination logic throughout execution lifecycle (timeout, cancellation, completion). Added tracking for termination reasons and force-kill timeouts.
HeadlessWorkerExecutor Tests v3/@claude-flow/cli/__tests__/services/headless-worker-executor.cleanup.test.ts	New unit tests validating process cleanup behavior: escalation to SIGKILL after grace period with timeout detection, and cancellation status preservation until process closure.
Teammate Plugin Background Execution Control v3/plugins/teammate-plugin/src/mcp-tools.ts, v3/plugins/teammate-plugin/src/teammate-bridge.ts	Made runInBackground an optional configurable parameter with default changed from hardcoded true to false. Updated MCP tool schema to expose the boolean field in teammate_spawn tool inputs.
Teammate Plugin Tests v3/plugins/teammate-plugin/tests/mcp-tools.test.ts, v3/plugins/teammate-plugin/tests/teammate-bridge.test.ts	New test coverage validating runInBackground default behavior (false when omitted), explicit true value propagation, and MCP schema exposure of the parameter.
Protocol Documentation v3/@claude-flow/cli/src/init/claudemd-generator.ts	Updated swarm initiation messaging and agent spawning protocol guidance: clarified single-message all-in-one parallel execution, restricted run_in_background: true to independent long-running tasks only, and added constraint preventing max-agent exceeding during background fan-out.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant HeadlessWorkerExecutor
    participant ChildProcess
    participant System

    Caller->>HeadlessWorkerExecutor: executeClaudeCode(code, timeout)
    HeadlessWorkerExecutor->>ChildProcess: spawn process
    ChildProcess->>HeadlessWorkerExecutor: stdout/stderr events
    
    alt Execution Timeout
        HeadlessWorkerExecutor->>HeadlessWorkerExecutor: Start grace timer (killGraceMs)
        HeadlessWorkerExecutor->>ChildProcess: SIGTERM (requestTermination)
        Note over ChildProcess: Grace period
        alt Process closes within grace
            ChildProcess->>HeadlessWorkerExecutor: exit/close event
            HeadlessWorkerExecutor->>HeadlessWorkerExecutor: cleanupPoolEntry
            HeadlessWorkerExecutor->>Caller: resolve with timeout error
        else Grace period expires
            HeadlessWorkerExecutor->>ChildProcess: SIGKILL (force escalation)
            ChildProcess->>System: process terminated
            HeadlessWorkerExecutor->>Caller: resolve with timeout error
        end
    else Execution Completes Normally
        ChildProcess->>HeadlessWorkerExecutor: exit code 0
        HeadlessWorkerExecutor->>HeadlessWorkerExecutor: finalize(result)
        HeadlessWorkerExecutor->>Caller: resolve with result
    else Execution Cancelled
        Caller->>HeadlessWorkerExecutor: cancel(executionId)
        HeadlessWorkerExecutor->>ChildProcess: SIGTERM (requestTermination)
        ChildProcess->>HeadlessWorkerExecutor: exit/close event
        HeadlessWorkerExecutor->>Caller: resolve with cancellation
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Processes once wandered wild and free,
Background tasks would never flee—
But now with grace and SIGTERM's call,
They bow and cleanup, best of all!
No memory leaks shall haunt the swarm,
Just clean exits—the graceful norm. 🎭

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/issue-8-background-process-cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔗 Integration Test Results

🔗 Cross-Agent Integration Test Report

Session ID: integration-20260206-232244-4b660236685687317ad2e40e42d4f589d4d1d150
Timestamp: 2026-02-06T23:24:42.653Z
Overall Status: ✅ PASSED

Summary

• Total Tests: 4
• Passed: 4
• Failed: 0
• Success Rate: 100.0%

Test Results

Component	Status	Details
Agent Coordination	✅	Multi-agent communication and task distribution
Memory Integration	✅	Shared memory operations and synchronization
Fault Tolerance	✅	Failure recovery and system resilience
Performance	✅	Multi-agent performance and scalability

Recommendations

• All integration tests passed successfully!

Next Steps

1. Review detailed test artifacts
2. Address any failed test scenarios
3. Monitor integration performance in production

---

Generated by Cross-Agent Integration Test Pipeline