┌─────────────────────────────────────────────────────────────────────────────┐
│                              CONTROL PLANE                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  ┌─────────────────────┐ │
│  │ Orchestrator│  │Task Planner  │  │ Scheduler  │  │ Resource Warden     │ │
│  │    Core     │──│ (Decomposer) │──│            │──│ (Lock Manager)      │ │
│  └─────────────┘  └──────────────┘  └────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                               DATA PLANE                                    │
│  ┌──────────────────────────┐            ┌──────────────────────────────┐   │
│  │      Event Bus (IPC)     │            │      Trace Aggregator        │   │
│  │  Pub/Sub Message Passing │            │  Logs, Metrics, Spans        │   │
│  └──────────────────────────┘            └──────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             EXECUTION PLANE                                 │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐       ┌───────────────────┐   │
│  │ Agent Pod │  │ Agent Pod │  │ Agent Pod │  ...  │  Copilot CLI      │   │
│  │     1     │  │     2     │  │     N     │       │  (Child Process)  │   │
│  └───────────┘  └───────────┘  └───────────┘       └───────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

# Clone the repository
git clone https://github.com/sureshsankaran/mcp-subagent-orchestrator.git
cd mcp-subagent-orchestrator

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Check build output
ls dist/

# Run comprehensive demo showcasing all phases (1-7)
npm run demo:e2e

# Run basic component demo
npm run demo

{
  "mcpServers": {
    "hivemind": {
      "command": "node",
      "args": ["path/to/mcp-subagent-orchestrator/dist/index.js"],
      "env": {
        "GH_TOKEN": "your-github-token"
      }
    }
  }
}

import { OrchestratorCore, OrchestratorConfig } from 'mcp-subagent-orchestrator';

// Create orchestrator
const config: OrchestratorConfig = {
  maxConcurrentAgents: 5,
  workspacePath: '/path/to/workspace',
  persistence: {
    enabled: true,
    dbPath: '.hivemind/state.db'
  }
};

const orchestrator = new OrchestratorCore(config);
await orchestrator.initialize();

// Spawn a single agent
const agent = await orchestrator.spawnAgent('Fix the authentication bug in auth.ts');
const result = await orchestrator.waitForAgent(agent.id);

// Submit an autonomous job
const job = await orchestrator.submitJob('Refactor the entire API layer to use async/await');
const status = await orchestrator.waitForJob(job.id);

// Spawn a focused subagent
await mcp.callTool('spawn_agent', {
  task: 'Review auth.ts for security vulnerabilities',
  config: {
    system_instruction: 'You are a security expert. Be thorough.',
    allowed_paths: ['src/auth/'],
    read_only: true
  }
});

// Submit autonomous job (orchestrator handles everything)
await mcp.callTool('submit_task_auto', {
  instruction: 'Add comprehensive unit tests to all service files',
  strategy: 'parallel',
  max_agents: 4
});

// Monitor job progress
await mcp.callTool('get_job_status', { job_id: 'job-123' });

// Acquire file lock (for manual coordination)
await mcp.callTool('acquire_lock', {
  resource: 'src/api/users.ts',
  mode: 'exclusive',
  timeout_ms: 30000
});

{
  "cli": {
    // Force a specific adapter type instead of auto-preference (copilot_v2 > copilot_v1 > codex > gh_copilot > claude)
    "preferred_cli_type": "codex",
    // Optional explicit binary path (skips detection)
    "preferred_cli_path": "/usr/local/bin/codex",
    // Existing options
    "cli_command": "copilot",
    "default_timeout_ms": 300000,
    "auto_approve_tools": true
  }
}

interface OrchestratorConfig {
  // Agent management
  maxConcurrentAgents: number;       // Max parallel agents
  agentTimeout: number;              // Agent execution timeout (ms)
  agentPoolSize: number;             // Pre-warmed agent pool size
  
  // Workspace
  workspacePath: string;             // Root workspace path
  trustedFolders: string[];          // Pre-trusted Copilot folders
  
  // Locking
  lockTimeout: number;               // Default lock acquisition timeout
  deadlockDetection: boolean;        // Enable deadlock detection
  
  // Persistence
  persistence: {
    enabled: boolean;
    dbPath: string;
    checkpointInterval: number;      // Checkpoint frequency (ms)
  };
  
  // Observability
  logging: {
    level: 'debug' | 'info' | 'warn' | 'error';
    format: 'json' | 'pretty';
  };
  
  // Security
  toolApproval: {
    allowedShellCommands: string[];
    deniedShellCommands: string[];
  };

  // CLI (decomposition + spawned agents)
  cli: {
    cli_command: string;
    preferred_cli_type?: 'copilot_v2' | 'copilot_v1' | 'codex' | 'gh_copilot' | 'claude' | 'unknown';
    preferred_cli_path?: string;
    default_timeout_ms: number;
    auto_approve_tools: boolean;
  };
}

# Build TypeScript
npm run build

# Watch mode
npm run build:watch

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format

# Clean build artifacts
npm run clean

# Run all tests
npm test

# Run specific test file
npm test -- tests/unit/locks/LockManager.test.ts

# Run with coverage
npm run test:coverage

mcp-subagent-orchestrator/
├── src/
│   ├── agents/          # Agent pod management
│   ├── cli/             # Copilot CLI adapter
│   ├── core/            # Orchestrator core
│   ├── dashboard/       # REST API & WebSocket
│   ├── errors/          # Custom error classes
│   ├── ipc/             # Event bus & messaging
│   ├── locks/           # Lock manager (Warden)
│   ├── mcp/             # MCP tool definitions
│   ├── persistence/     # SQLite & checkpointing
│   ├── planner/         # Task decomposition
│   ├── tracing/         # Logging & telemetry
│   ├── types/           # TypeScript interfaces
│   ├── utils/           # Shared utilities
│   └── index.ts         # Main entry point
├── tests/
│   ├── unit/            # Unit tests
│   └── integration/     # Integration tests
├── tasks/               # Phase task breakdowns
├── dist/                # Compiled output
├── spec.md              # Full specification
├── TASKS.md             # Development roadmap
└── package.json