claude-flow-novice 1.6.3 → 1.6.5

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/coordinators/hierarchical-coordinator.js

@@ -0,0 +1,786 @@
+/**
+ * Agent Coordination V2 - Hierarchical Coordinator
+ *
+ * PM-based hierarchical coordination with multi-level agent hierarchy support.
+ * Enables Level 0 coordinator (Claude Code chat) to control all nested levels
+ * via pause/inject/resume operations.
+ *
+ * Features:
+ * - Parent-child agent relationship management
+ * - Multi-level hierarchy (10+ levels supported)
+ * - PM delegates tasks to worker children
+ * - Background process orchestration for child agents
+ * - Cascading operations (pause, resume, shutdown)
+ * - Session forking for parallel worker spawning (<2s for 10 workers)
+ *
+ * Performance Targets:
+ * - Agent spawn time: <2s for 10 hierarchical agents
+ * - Parent control latency: <100ms for pause/inject/resume
+ * - Nested hierarchy depth: 10+ levels
+ * - Checkpoint recovery: <500ms (p99)
+ * - Cascading shutdown: <1s for 20 agents
+ *
+ * @module coordination/v2/coordinators/hierarchical-coordinator
+ */ import { EventEmitter } from 'node:events';
+import { AgentState } from '../../shared/core/agent-state.js';
+import { Logger } from '../../../core/logger.js';
+/**
+ * HierarchicalCoordinator
+ *
+ * Implements PM-based hierarchical coordination pattern:
+ * 1. Level 0 coordinator in Claude Code chat (supervisor)
+ * 2. Level 1+ agents spawned via background processes
+ * 3. PM delegates tasks to worker children
+ * 4. Parent can pause/inject/resume any child at any level
+ * 5. Cascading operations (pause, resume, shutdown) propagate to descendants
+ * 6. Hierarchical completion detection via Phase 4 integration
+ *
+ * @example
+ * ```typescript
+ * const coordinator = new HierarchicalCoordinator(
+ *   stateMachine,
+ *   messageBroker,
+ *   checkpointManager,
+ *   completionDetector,
+ *   { swarmId: 'swarm-1', maxDepth: 10 }
+ * );
+ *
+ * await coordinator.initialize();
+ *
+ * // Spawn root PM
+ * const rootPM = await coordinator.spawnProjectManager('pm-root', 0);
+ *
+ * // Fork worker children from PM
+ * const workers = await coordinator.forkWorkers(rootPM.agentId, 5);
+ *
+ * // Delegate task to worker
+ * await coordinator.delegateTask({
+ *   taskId: 'task-1',
+ *   description: 'Implement feature X',
+ *   workerId: workers[0].agentId,
+ *   pmId: rootPM.agentId,
+ *   priority: 8
+ * });
+ * ```
+ */ export class HierarchicalCoordinator extends EventEmitter {
+    logger;
+    config;
+    stateMachine;
+    messageBroker;
+    checkpointManager;
+    completionDetector;
+    /** All agents in hierarchy (agentId -> node) */ agents;
+    /** Parent-child relationships (childId -> parentId) */ parentRelationships;
+    /** Root PM agent ID */ rootPmId;
+    /** Performance metrics */ metrics;
+    /** Control operation latencies for p99 calculation */ controlLatencies;
+    /** Initialized flag */ initialized;
+    /** Task subscription for cleanup */ taskSubscription;
+    constructor(stateMachine, messageBroker, checkpointManager, completionDetector, config){
+        super();
+        this.logger = new Logger({
+            level: 'info',
+            format: 'text',
+            destination: 'console'
+        });
+        this.config = {
+            swarmId: config.swarmId,
+            maxDepth: config.maxDepth ?? 15,
+            maxBranchingFactor: config.maxBranchingFactor ?? 10,
+            autoCheckpoint: config.autoCheckpoint ?? true,
+            enableBackgroundMonitoring: config.enableBackgroundMonitoring ?? true,
+            controlTimeoutMs: config.controlTimeoutMs ?? 5000
+        };
+        this.stateMachine = stateMachine;
+        this.messageBroker = messageBroker;
+        this.checkpointManager = checkpointManager;
+        this.completionDetector = completionDetector;
+        this.agents = new Map();
+        this.parentRelationships = new Map();
+        this.controlLatencies = [];
+        this.initialized = false;
+        this.metrics = {
+            totalAgentsSpawned: 0,
+            totalDelegations: 0,
+            totalControlOperations: 0,
+            averageControlLatencyMs: 0,
+            p99ControlLatencyMs: 0,
+            totalCascadingOps: 0,
+            averageSpawnTime10Agents: 0,
+            checkpointRecoveries: 0,
+            averageRecoveryTimeMs: 0
+        };
+        this.logger.info('HierarchicalCoordinator created', {
+            swarmId: this.config.swarmId,
+            maxDepth: this.config.maxDepth,
+            maxBranchingFactor: this.config.maxBranchingFactor
+        });
+    }
+    /**
+   * Initialize coordinator
+   */ async initialize() {
+        if (this.initialized) {
+            this.logger.warn('HierarchicalCoordinator already initialized');
+            return;
+        }
+        this.logger.info('Initializing HierarchicalCoordinator', {
+            swarmId: this.config.swarmId
+        });
+        // Subscribe to state machine events
+        this.stateMachine.on('state:transition', this.handleStateTransition.bind(this));
+        // Subscribe to message broker for task delegation
+        this.taskSubscription = await this.messageBroker.subscribe({
+            topic: 'task',
+            handler: this.handleTaskMessage.bind(this)
+        });
+        this.initialized = true;
+        this.logger.info('HierarchicalCoordinator initialized successfully');
+    }
+    /**
+   * Spawn Project Manager agent at specified level
+   *
+   * @param agentId - Unique agent identifier
+   * @param level - Hierarchy level (0 = root, 1+ = nested)
+   * @param parentId - Parent PM agent ID (undefined for root)
+   * @returns Spawned PM agent node
+   */ async spawnProjectManager(agentId, level, parentId) {
+        this.validateInitialized();
+        this.validateDepth(level);
+        const startTime = performance.now();
+        // Generate session ID
+        const sessionId = `session_${agentId}_${Date.now()}`;
+        // Register agent with state machine
+        await this.stateMachine.registerAgent(agentId, sessionId, AgentState.IDLE);
+        // Create agent node
+        const node = {
+            agentId,
+            type: 'pm',
+            state: AgentState.IDLE,
+            level,
+            parentId,
+            childIds: [],
+            isProjectManager: true,
+            sessionId,
+            priority: 10,
+            lastUpdated: Date.now(),
+            metadata: {
+                spawnedAt: new Date(),
+                swarmId: this.config.swarmId
+            }
+        };
+        this.agents.set(agentId, node);
+        // Establish parent-child relationship
+        if (parentId) {
+            this.setParent(agentId, parentId);
+        } else {
+            // Root PM
+            this.rootPmId = agentId;
+        }
+        this.metrics.totalAgentsSpawned++;
+        const spawnLatency = performance.now() - startTime;
+        this.logger.info('Project Manager spawned', {
+            agentId,
+            level,
+            parentId,
+            sessionId,
+            spawnLatencyMs: spawnLatency.toFixed(2)
+        });
+        this.emit('pm:spawned', {
+            agentId,
+            level,
+            parentId,
+            sessionId
+        });
+        return node;
+    }
+    /**
+   * Fork worker agents from PM session (parallel spawning)
+   *
+   * @param pmId - Parent PM agent ID
+   * @param workerCount - Number of workers to spawn
+   * @param workerType - Worker agent type (default: 'worker')
+   * @returns Array of spawned worker nodes
+   */ async forkWorkers(pmId, workerCount, workerType = 'worker') {
+        this.validateInitialized();
+        const pm = this.agents.get(pmId);
+        if (!pm) {
+            throw new Error(`PM agent ${pmId} not found`);
+        }
+        if (!pm.isProjectManager) {
+            throw new Error(`Agent ${pmId} is not a Project Manager`);
+        }
+        this.validateBranchingFactor(pm.childIds.length + workerCount);
+        this.validateDepth(pm.level + 1);
+        const startTime = performance.now();
+        // Parallel worker spawning via Promise.all
+        const workerPromises = Array.from({
+            length: workerCount
+        }, async (_, i)=>{
+            const workerId = `${pmId}_worker_${i}`;
+            const sessionId = `session_${workerId}_${Date.now()}`;
+            // Register with state machine
+            await this.stateMachine.registerAgent(workerId, sessionId, AgentState.IDLE);
+            // Create worker node
+            const worker = {
+                agentId: workerId,
+                type: workerType,
+                state: AgentState.IDLE,
+                level: pm.level + 1,
+                parentId: pmId,
+                childIds: [],
+                isProjectManager: false,
+                sessionId,
+                priority: 5,
+                lastUpdated: Date.now(),
+                metadata: {
+                    spawnedAt: new Date(),
+                    swarmId: this.config.swarmId,
+                    forkIndex: i
+                }
+            };
+            this.agents.set(workerId, worker);
+            this.setParent(workerId, pmId);
+            this.metrics.totalAgentsSpawned++;
+            return worker;
+        });
+        const workers = await Promise.all(workerPromises);
+        const spawnLatency = performance.now() - startTime;
+        // Track 10-agent spawn time for metrics
+        if (workerCount === 10) {
+            this.metrics.averageSpawnTime10Agents = spawnLatency;
+        }
+        this.logger.info('Workers forked', {
+            pmId,
+            workerCount,
+            workerType,
+            spawnLatencyMs: spawnLatency.toFixed(2),
+            target: '2000ms for 10 agents'
+        });
+        this.emit('workers:forked', {
+            pmId,
+            workers,
+            spawnLatencyMs: spawnLatency
+        });
+        return workers;
+    }
+    /**
+   * Delegate task from PM to worker
+   *
+   * @param delegation - Task delegation details
+   */ async delegateTask(delegation) {
+        this.validateInitialized();
+        const { taskId, workerId, pmId, description, priority } = delegation;
+        const pm = this.agents.get(pmId);
+        const worker = this.agents.get(workerId);
+        if (!pm) {
+            throw new Error(`PM agent ${pmId} not found`);
+        }
+        if (!worker) {
+            throw new Error(`Worker agent ${workerId} not found`);
+        }
+        if (!pm.isProjectManager) {
+            throw new Error(`Agent ${pmId} is not a Project Manager`);
+        }
+        if (worker.parentId !== pmId) {
+            throw new Error(`Worker ${workerId} is not a child of PM ${pmId}`);
+        }
+        const startTime = performance.now();
+        // Step 1: Pause worker before injecting task (prevents token waste)
+        if (worker.state !== AgentState.PAUSED) {
+            await this.pauseChild(pmId, workerId, `Task delegation: ${taskId}`);
+        }
+        // Step 2: Inject task message into worker session
+        await this.messageBroker.publish({
+            topic: 'task',
+            payload: {
+                type: 'task_assignment',
+                taskId,
+                description,
+                priority,
+                pmId,
+                workerId,
+                context: delegation.context,
+                deadline: delegation.deadline
+            },
+            priority,
+            senderId: pmId,
+            recipientId: workerId
+        });
+        // Step 3: Transition worker to WORKING state
+        await this.stateMachine.transition(workerId, AgentState.WORKING, {
+            metadata: {
+                taskId,
+                pmId,
+                taskDescription: description
+            }
+        });
+        this.metrics.totalDelegations++;
+        const delegationLatency = performance.now() - startTime;
+        this.logger.info('Task delegated', {
+            taskId,
+            pmId,
+            workerId,
+            priority,
+            delegationLatencyMs: delegationLatency.toFixed(2)
+        });
+        this.emit('task:delegated', {
+            taskId,
+            pmId,
+            workerId,
+            latencyMs: delegationLatency
+        });
+    }
+    /**
+   * Pause child agent (parent control operation)
+   *
+   * @param parentId - Parent agent ID
+   * @param childId - Child agent ID to pause
+   * @param reason - Pause reason
+   */ async pauseChild(parentId, childId, reason) {
+        await this.executeParentControl({
+            operation: 'pause',
+            parentId,
+            childId,
+            reason
+        });
+    }
+    /**
+   * Resume child agent (parent control operation)
+   *
+   * @param parentId - Parent agent ID
+   * @param childId - Child agent ID to resume
+   * @param checkpointId - Optional checkpoint ID to resume from
+   * @param reason - Resume reason
+   */ async resumeChild(parentId, childId, checkpointId, reason) {
+        await this.executeParentControl({
+            operation: 'resume',
+            parentId,
+            childId,
+            checkpointId,
+            reason
+        });
+    }
+    /**
+   * Inject message into child session (parent control operation)
+   *
+   * @param parentId - Parent agent ID
+   * @param childId - Child agent ID
+   * @param message - Message to inject
+   */ async injectMessageToChild(parentId, childId, message) {
+        await this.executeParentControl({
+            operation: 'inject',
+            parentId,
+            childId,
+            message
+        });
+    }
+    /**
+   * Execute parent control operation
+   *
+   * @private
+   * @param request - Parent control request
+   */ async executeParentControl(request) {
+        this.validateInitialized();
+        const { operation, parentId, childId, message, checkpointId, reason } = request;
+        const parent = this.agents.get(parentId);
+        const child = this.agents.get(childId);
+        if (!parent) {
+            throw new Error(`Parent agent ${parentId} not found`);
+        }
+        if (!child) {
+            throw new Error(`Child agent ${childId} not found`);
+        }
+        if (child.parentId !== parentId) {
+            throw new Error(`Agent ${childId} is not a child of ${parentId}`);
+        }
+        const startTime = performance.now();
+        try {
+            switch(operation){
+                case 'pause':
+                    // Create checkpoint before pausing
+                    if (this.config.autoCheckpoint) {
+                        await this.checkpointManager.createCheckpoint(child.sessionId, childId, `control_pause_${Date.now()}`, child.state, {
+                            currentState: child.state
+                        }, {
+                            reason: reason || `Paused by parent ${parentId}`,
+                            autoCheckpoint: true,
+                            context: {
+                                parentId,
+                                operation
+                            }
+                        });
+                    }
+                    // Transition to PAUSED state
+                    await this.stateMachine.transition(childId, AgentState.PAUSED, {
+                        metadata: {
+                            parentId,
+                            reason,
+                            operation: 'pause'
+                        }
+                    });
+                    break;
+                case 'resume':
+                    // Restore from checkpoint if provided
+                    if (checkpointId) {
+                        const restoreResult = await this.checkpointManager.restoreCheckpoint(checkpointId);
+                        if (restoreResult.success) {
+                            await this.stateMachine.restoreFromCheckpoint(childId, checkpointId);
+                            this.metrics.checkpointRecoveries++;
+                            this.metrics.averageRecoveryTimeMs = (this.metrics.averageRecoveryTimeMs * (this.metrics.checkpointRecoveries - 1) + restoreResult.latencyMs) / this.metrics.checkpointRecoveries;
+                        }
+                    }
+                    // Transition to WORKING state
+                    await this.stateMachine.transition(childId, AgentState.WORKING, {
+                        metadata: {
+                            parentId,
+                            reason,
+                            operation: 'resume',
+                            checkpointId
+                        }
+                    });
+                    break;
+                case 'inject':
+                    // Inject message via message broker
+                    await this.messageBroker.publish({
+                        topic: 'control',
+                        payload: {
+                            type: 'parent_injection',
+                            message,
+                            parentId,
+                            childId,
+                            timestamp: Date.now()
+                        },
+                        priority: 10,
+                        senderId: parentId,
+                        recipientId: childId
+                    });
+                    break;
+                case 'shutdown':
+                    // Graceful shutdown: transition to COMPLETED
+                    await this.stateMachine.transition(childId, AgentState.COMPLETED, {
+                        metadata: {
+                            parentId,
+                            reason: reason || 'Shutdown by parent',
+                            operation: 'shutdown'
+                        }
+                    });
+                    break;
+            }
+            const controlLatency = performance.now() - startTime;
+            this.updateControlMetrics(controlLatency);
+            this.logger.info('Parent control operation completed', {
+                operation,
+                parentId,
+                childId,
+                latencyMs: controlLatency.toFixed(2),
+                target: '100ms'
+            });
+            this.emit('parent:control', {
+                operation,
+                parentId,
+                childId,
+                latencyMs: controlLatency,
+                success: true
+            });
+        } catch (error) {
+            const controlLatency = performance.now() - startTime;
+            this.logger.error('Parent control operation failed', {
+                operation,
+                parentId,
+                childId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            this.emit('parent:control', {
+                operation,
+                parentId,
+                childId,
+                latencyMs: controlLatency,
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        }
+    }
+    /**
+   * Cascade control operation to all descendants
+   *
+   * @param agentId - Root agent ID
+   * @param operation - Control operation to cascade
+   */ async cascadeControl(agentId, operation) {
+        this.validateInitialized();
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        const startTime = performance.now();
+        // Get all descendants (DFS traversal)
+        const descendants = this.getAllDescendants(agentId);
+        this.logger.info('Cascading control operation', {
+            operation,
+            rootAgentId: agentId,
+            descendantCount: descendants.length
+        });
+        // Execute operation on all descendants in parallel
+        const operationPromises = descendants.map(async (descendant)=>{
+            const parent = this.agents.get(descendant.parentId);
+            if (!parent) return;
+            try {
+                await this.executeParentControl({
+                    operation,
+                    parentId: descendant.parentId,
+                    childId: descendant.agentId,
+                    reason: `Cascaded from ${agentId}`
+                });
+            } catch (error) {
+                this.logger.error('Cascading operation failed for descendant', {
+                    descendantId: descendant.agentId,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        });
+        await Promise.all(operationPromises);
+        this.metrics.totalCascadingOps++;
+        const cascadeLatency = performance.now() - startTime;
+        this.logger.info('Cascading operation completed', {
+            operation,
+            rootAgentId: agentId,
+            descendantCount: descendants.length,
+            cascadeLatencyMs: cascadeLatency.toFixed(2),
+            target: operation === 'shutdown' ? '1000ms for 20 agents' : 'N/A'
+        });
+        this.emit('cascade:completed', {
+            operation,
+            rootAgentId: agentId,
+            descendantCount: descendants.length,
+            latencyMs: cascadeLatency
+        });
+    }
+    /**
+   * Get all descendants of an agent (DFS traversal)
+   *
+   * @param agentId - Root agent ID
+   * @returns Array of descendant nodes
+   */ getAllDescendants(agentId) {
+        const descendants = [];
+        const visited = new Set();
+        const dfs = (currentId)=>{
+            const agent = this.agents.get(currentId);
+            if (!agent || visited.has(currentId)) return;
+            visited.add(currentId);
+            for (const childId of agent.childIds){
+                const child = this.agents.get(childId);
+                if (child) {
+                    descendants.push(child);
+                    dfs(childId); // Recursive DFS
+                }
+            }
+        };
+        dfs(agentId);
+        return descendants;
+    }
+    /**
+   * Set parent-child relationship
+   *
+   * @private
+   * @param childId - Child agent ID
+   * @param parentId - Parent agent ID
+   */ setParent(childId, parentId) {
+        const parent = this.agents.get(parentId);
+        const child = this.agents.get(childId);
+        if (!parent) {
+            throw new Error(`Parent agent ${parentId} not found`);
+        }
+        if (!child) {
+            throw new Error(`Child agent ${childId} not found`);
+        }
+        // Update parent's child list
+        if (!parent.childIds.includes(childId)) {
+            parent.childIds.push(childId);
+        }
+        // Update child's parent reference
+        child.parentId = parentId;
+        // Track in parent relationships map
+        this.parentRelationships.set(childId, parentId);
+        this.logger.debug('Parent-child relationship established', {
+            parentId,
+            childId,
+            parentLevel: parent.level,
+            childLevel: child.level
+        });
+    }
+    /**
+   * Get hierarchy statistics
+   */ getStatistics() {
+        const allAgents = Array.from(this.agents.values());
+        const pmCount = allAgents.filter((a)=>a.isProjectManager).length;
+        const workerCount = allAgents.length - pmCount;
+        const depths = allAgents.map((a)=>a.level);
+        const maxDepth = depths.length > 0 ? Math.max(...depths) : 0;
+        const branchingFactors = allAgents.filter((a)=>a.isProjectManager).map((a)=>a.childIds.length);
+        const averageBranchingFactor = branchingFactors.length > 0 ? branchingFactors.reduce((sum, f)=>sum + f, 0) / branchingFactors.length : 0;
+        const activeAgents = allAgents.filter((a)=>a.state !== AgentState.PAUSED && a.state !== AgentState.COMPLETED).length;
+        const pausedAgents = allAgents.filter((a)=>a.state === AgentState.PAUSED).length;
+        const completedAgents = allAgents.filter((a)=>a.state === AgentState.COMPLETED).length;
+        return {
+            totalAgents: allAgents.length,
+            pmCount,
+            workerCount,
+            maxDepth,
+            averageBranchingFactor,
+            activeAgents,
+            pausedAgents,
+            completedAgents
+        };
+    }
+    /**
+   * Get coordinator metrics
+   */ getMetrics() {
+        return {
+            ...this.metrics
+        };
+    }
+    /**
+   * Get agent node by ID
+   */ getAgent(agentId) {
+        return this.agents.get(agentId);
+    }
+    /**
+   * Get all agents in hierarchy
+   */ getAllAgents() {
+        return Array.from(this.agents.values());
+    }
+    /**
+   * Get root PM agent
+   */ getRootPM() {
+        return this.rootPmId ? this.agents.get(this.rootPmId) : undefined;
+    }
+    /**
+   * Get children of an agent
+   */ getChildren(agentId) {
+        const agent = this.agents.get(agentId);
+        if (!agent) return [];
+        return agent.childIds.map((id)=>this.agents.get(id)).filter((a)=>a !== undefined);
+    }
+    /**
+   * Handle state transition events from state machine
+   *
+   * @private
+   */ handleStateTransition(event) {
+        const { agentId, toState } = event;
+        const agent = this.agents.get(agentId);
+        if (!agent) return;
+        // Update agent state
+        agent.state = toState;
+        agent.lastUpdated = Date.now();
+        this.logger.debug('Agent state updated', {
+            agentId,
+            newState: toState,
+            level: agent.level,
+            isProjectManager: agent.isProjectManager
+        });
+    }
+    /**
+   * Handle task messages from message broker
+   *
+   * @private
+   */ async handleTaskMessage(message) {
+        const { type, taskId, workerId } = message.payload;
+        if (type === 'task_completion') {
+            this.logger.info('Task completed', {
+                taskId,
+                workerId
+            });
+            // Transition worker to IDLE after task completion
+            const worker = this.agents.get(workerId);
+            if (worker && worker.state === AgentState.WORKING) {
+                await this.stateMachine.transition(workerId, AgentState.IDLE, {
+                    metadata: {
+                        taskId,
+                        reason: 'Task completed'
+                    }
+                });
+            }
+        }
+    }
+    /**
+   * Update control operation metrics
+   *
+   * @private
+   */ updateControlMetrics(latencyMs) {
+        this.metrics.totalControlOperations++;
+        this.controlLatencies.push(latencyMs);
+        // Keep only recent 100 samples for rolling statistics
+        if (this.controlLatencies.length > 100) {
+            this.controlLatencies = this.controlLatencies.slice(-100);
+        }
+        // Update average
+        this.metrics.averageControlLatencyMs = (this.metrics.averageControlLatencyMs * (this.metrics.totalControlOperations - 1) + latencyMs) / this.metrics.totalControlOperations;
+        // Update p99
+        if (this.controlLatencies.length > 0) {
+            const sorted = [
+                ...this.controlLatencies
+            ].sort((a, b)=>a - b);
+            const p99Index = Math.floor(sorted.length * 0.99);
+            this.metrics.p99ControlLatencyMs = sorted[p99Index] || sorted[sorted.length - 1];
+        }
+    }
+    /**
+   * Validate coordinator is initialized
+   *
+   * @private
+   */ validateInitialized() {
+        if (!this.initialized) {
+            throw new Error('HierarchicalCoordinator not initialized. Call initialize() first.');
+        }
+    }
+    /**
+   * Validate hierarchy depth
+   *
+   * @private
+   */ validateDepth(level) {
+        if (level > this.config.maxDepth) {
+            throw new Error(`Hierarchy depth ${level} exceeds maximum ${this.config.maxDepth}`);
+        }
+    }
+    /**
+   * Validate branching factor
+   *
+   * @private
+   */ validateBranchingFactor(childCount) {
+        if (childCount > this.config.maxBranchingFactor) {
+            throw new Error(`Branching factor ${childCount} exceeds maximum ${this.config.maxBranchingFactor}`);
+        }
+    }
+    /**
+   * Cleanup coordinator and release resources
+   */ async cleanup() {
+        this.logger.info('Cleaning up HierarchicalCoordinator', {
+            swarmId: this.config.swarmId,
+            totalAgents: this.agents.size
+        });
+        // Cascading shutdown from root PM
+        if (this.rootPmId) {
+            try {
+                await this.cascadeControl(this.rootPmId, 'shutdown');
+            } catch (error) {
+                this.logger.error('Cascading shutdown failed', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        // Unsubscribe from message broker
+        if (this.taskSubscription) {
+            this.taskSubscription.unsubscribe();
+            this.taskSubscription = undefined;
+        }
+        // Clear state
+        this.agents.clear();
+        this.parentRelationships.clear();
+        this.controlLatencies = [];
+        this.initialized = false;
+        this.removeAllListeners();
+        this.logger.info('HierarchicalCoordinator cleaned up successfully');
+    }
+}
+
+//# sourceMappingURL=hierarchical-coordinator.js.map