swarm-orchestrator 7.0.0-alpha.0

package/dist/src/config-loader.js

@@ -0,0 +1,339 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = void 0;
+const fs = __importStar(require("fs"));
+const yaml = __importStar(require("js-yaml"));
+const path = __importStar(require("path"));
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('config-loader');
+class ConfigLoader {
+    configDir;
+    customAgentsDir;
+    constructor(configDir) {
+        const cwd = process.cwd();
+        const packageRoot = this.findPackageRoot(__dirname);
+        this.configDir = configDir || this.resolveConfigDir(cwd, packageRoot);
+        this.customAgentsDir = this.resolveCustomAgentsDir(cwd, packageRoot);
+        logger.debug(`agent config dir: ${this.configDir}`);
+        logger.debug(`custom agents dir: ${this.customAgentsDir}`);
+    }
+    findPackageRoot(startDir) {
+        // walk upwards until we find a package.json
+        let current = startDir;
+        for (let i = 0; i < 8; i++) {
+            const candidate = path.join(current, 'package.json');
+            if (fs.existsSync(candidate)) {
+                return current;
+            }
+            const parent = path.dirname(current);
+            if (parent === current) {
+                break;
+            }
+            current = parent;
+        }
+        // fallback: best effort
+        return startDir;
+    }
+    resolveConfigDir(cwd, packageRoot) {
+        const cwdConfig = path.join(cwd, 'config');
+        if (fs.existsSync(path.join(cwdConfig, 'default-agents.yaml'))) {
+            return cwdConfig;
+        }
+        const pkgConfig = path.join(packageRoot, 'config');
+        if (fs.existsSync(path.join(pkgConfig, 'default-agents.yaml'))) {
+            return pkgConfig;
+        }
+        return cwdConfig;
+    }
+    resolveCustomAgentsDir(cwd, packageRoot) {
+        const cwdAgents = path.join(cwd, '.github', 'agents');
+        if (fs.existsSync(cwdAgents)) {
+            return cwdAgents;
+        }
+        const pkgAgents = path.join(packageRoot, '.github', 'agents');
+        if (fs.existsSync(pkgAgents)) {
+            return pkgAgents;
+        }
+        return cwdAgents;
+    }
+    loadDefaultAgents() {
+        const filePath = path.join(this.configDir, 'default-agents.yaml');
+        return this.loadAgentFile(filePath);
+    }
+    loadUserAgents() {
+        const filePath = path.join(this.configDir, 'user-agents.yaml');
+        return this.loadAgentFile(filePath);
+    }
+    /**
+     * Load all agents: custom .agent.md files + YAML configs
+     * Custom agents take precedence over YAML
+     */
+    loadAllAgents() {
+        const agentMap = new Map();
+        // Load YAML configs first (legacy/fallback)
+        try {
+            const defaultAgents = this.loadDefaultAgents();
+            logger.debug(`loaded default agents from ${path.join(this.configDir, 'default-agents.yaml')}`);
+            defaultAgents.agents.forEach(agent => {
+                agentMap.set(agent.name, agent);
+            });
+        }
+        catch (error) {
+            const err = error;
+            logger.warn(`Failed to load default agents: ${err.message}`);
+        }
+        try {
+            const userAgents = this.loadUserAgents();
+            logger.debug(`loaded user agents from ${path.join(this.configDir, 'user-agents.yaml')}`);
+            userAgents.agents.forEach(agent => {
+                agentMap.set(agent.name, agent);
+            });
+        }
+        catch {
+            // User agents YAML (config/user-agents.yaml) is optional; missing file is normal
+        }
+        // Load custom .agent.md files (override YAML if name matches)
+        const customAgents = this.loadCustomAgents();
+        customAgents.forEach(agent => {
+            agentMap.set(agent.name, agent);
+        });
+        return Array.from(agentMap.values());
+    }
+    /**
+     * Load custom agents from .github/agents/*.agent.md
+     */
+    loadCustomAgents() {
+        if (!fs.existsSync(this.customAgentsDir)) {
+            logger.debug(`no custom agents directory at ${this.customAgentsDir}`);
+            return [];
+        }
+        const agentFiles = fs.readdirSync(this.customAgentsDir)
+            .filter(file => file.endsWith('.agent.md'));
+        const agents = [];
+        for (const file of agentFiles) {
+            try {
+                const agentPath = path.join(this.customAgentsDir, file);
+                const agent = this.parseCustomAgentFile(agentPath);
+                if (agent) {
+                    agents.push(agent);
+                }
+            }
+            catch (error) {
+                const err = error;
+                logger.warn(`Failed to load custom agent ${file}: ${err.message}`);
+            }
+        }
+        return agents;
+    }
+    /**
+     * Parse a .agent.md custom agent file
+     */
+    parseCustomAgentFile(filePath) {
+        const content = fs.readFileSync(filePath, 'utf8');
+        // Extract frontmatter (YAML between --- markers)
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!frontmatterMatch || !frontmatterMatch[1]) {
+            logger.warn(`No frontmatter found in ${filePath}`);
+            return null;
+        }
+        const frontmatter = yaml.load(frontmatterMatch[1]);
+        // Extract markdown content after frontmatter
+        const markdownContent = content.substring(frontmatterMatch[0].length).trim();
+        // Parse sections from markdown
+        const scope = this.extractMarkdownSection(markdownContent, 'Scope');
+        const boundaries = this.extractMarkdownSection(markdownContent, 'Boundaries');
+        const doneDefinition = this.extractMarkdownSection(markdownContent, 'Done Definition');
+        const refusalRules = this.extractMarkdownSection(markdownContent, 'Refusal Rules');
+        // Convert custom agent to AgentProfile format
+        const agent = {
+            name: frontmatter.name,
+            purpose: frontmatter.description,
+            scope: scope.length > 0 ? scope : ['See .agent.md file for details'],
+            boundaries: boundaries.length > 0 ? boundaries : ['See .agent.md file for details'],
+            done_definition: doneDefinition.length > 0 ? doneDefinition : ['See .agent.md file for details'],
+            refusal_rules: refusalRules.length > 0 ? refusalRules : ['Follow agent guidelines'],
+            output_contract: {
+                transcript: `proof/step-{N}-${frontmatter.name.replace(/_/g, '-')}.md`,
+                artifacts: []
+            },
+            customAgentPath: filePath,
+            description: frontmatter.description,
+            ...(frontmatter.tools && { tools: frontmatter.tools }),
+            ...(frontmatter.metadata && { metadata: frontmatter.metadata })
+        };
+        return agent;
+    }
+    /**
+     * Extract bullet point list from markdown section
+     */
+    extractMarkdownSection(markdown, sectionHeader) {
+        const items = [];
+        // Find section header (## Scope or ## Boundaries, etc.)
+        const headerRegex = new RegExp(`##\\s+${sectionHeader}[^\\n]*\\n`, 'i');
+        const match = markdown.match(headerRegex);
+        if (!match || match.index === undefined) {
+            return items;
+        }
+        // Extract content until next ## header or end
+        const startIndex = match.index + match[0].length;
+        const remainingContent = markdown.substring(startIndex);
+        const nextHeaderMatch = remainingContent.match(/\n##\s+/);
+        const sectionContent = nextHeaderMatch
+            ? remainingContent.substring(0, nextHeaderMatch.index)
+            : remainingContent;
+        // Extract bullet points (lines starting with - or *)
+        const lines = sectionContent.split('\n');
+        for (const line of lines) {
+            const bulletMatch = line.match(/^[-*]\s+(.+)$/);
+            if (bulletMatch && bulletMatch[1]) {
+                items.push(bulletMatch[1].trim());
+            }
+        }
+        return items;
+    }
+    /**
+     * Get agent name for --agent flag (converts names to match .agent.md naming)
+     */
+    getAgentCLIName(agentName) {
+        // If agent has customAgentPath, use the name from frontmatter
+        const agent = this.getAgentByName(agentName);
+        if (agent?.customAgentPath) {
+            return agent.name; // already in correct format from frontmatter
+        }
+        // Otherwise normalize to lowercase (e.g. 'Worker' -> 'worker')
+        return agentName
+            .replace(/([A-Z])/g, '_$1')
+            .toLowerCase()
+            .replace(/^_/, '');
+    }
+    loadAgentFile(filePath) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`Config file not found: ${filePath}`);
+        }
+        const content = fs.readFileSync(filePath, 'utf8');
+        const config = yaml.load(content);
+        this.validateConfig(config, filePath);
+        return config;
+    }
+    validateConfig(config, filePath) {
+        if (!config || typeof config !== 'object') {
+            throw new Error(`Invalid config format in ${filePath}`);
+        }
+        if (!Array.isArray(config.agents)) {
+            throw new Error(`Missing 'agents' array in ${filePath}`);
+        }
+        config.agents.forEach((agent, index) => {
+            this.validateAgent(agent, `${filePath}[${index}]`);
+        });
+    }
+    validateAgent(agent, context) {
+        const requiredFields = [
+            'name',
+            'purpose',
+            'scope',
+            'boundaries',
+            'done_definition',
+            'output_contract',
+            'refusal_rules'
+        ];
+        for (const field of requiredFields) {
+            if (!(field in agent)) {
+                throw new Error(`Missing required field '${field}' in agent at ${context}`);
+            }
+        }
+        // Validate name is non-empty string
+        if (typeof agent.name !== 'string' || agent.name.trim() === '') {
+            throw new Error(`Agent name must be non-empty string at ${context}`);
+        }
+        // Validate purpose is non-empty string
+        if (typeof agent.purpose !== 'string' || agent.purpose.trim() === '') {
+            throw new Error(`Agent purpose must be non-empty string at ${context}`);
+        }
+        // Validate arrays
+        const arrayFields = ['scope', 'boundaries', 'done_definition', 'refusal_rules'];
+        for (const field of arrayFields) {
+            if (!Array.isArray(agent[field])) {
+                throw new Error(`Agent field '${field}' must be an array at ${context}`);
+            }
+        }
+        // Validate output_contract
+        if (!agent.output_contract || typeof agent.output_contract !== 'object') {
+            throw new Error(`Agent output_contract must be an object at ${context}`);
+        }
+        if (typeof agent.output_contract.transcript !== 'string') {
+            throw new Error(`Agent output_contract.transcript must be a string at ${context}`);
+        }
+        if (!Array.isArray(agent.output_contract.artifacts)) {
+            throw new Error(`Agent output_contract.artifacts must be an array at ${context}`);
+        }
+    }
+    getAgentByName(name) {
+        const allAgents = this.loadAllAgents();
+        // Exact match first, then normalized match (handles PascalCase vs snake_case)
+        return allAgents.find(agent => agent.name === name)
+            || allAgents.find(agent => ConfigLoader.normalizeAgentName(agent.name) === ConfigLoader.normalizeAgentName(name));
+    }
+    /**
+     * Build an agent map keyed by name, with lowercase aliases for mixed-case names.
+     * Plans use lowercase ('worker', 'reviewer'); YAML may use mixed case.
+     * Both must resolve to the same agent profile.
+     */
+    buildAgentMap() {
+        const agents = this.loadAllAgents();
+        const map = new Map();
+        for (const agent of agents) {
+            map.set(agent.name, agent);
+            const snakeName = ConfigLoader.normalizeAgentName(agent.name);
+            if (snakeName !== agent.name && !map.has(snakeName)) {
+                map.set(snakeName, agent);
+            }
+        }
+        return map;
+    }
+    /**
+     * Normalize agent name for consistent lookups.
+     * 'Worker' -> 'worker', 'worker' -> 'worker'
+     */
+    static normalizeAgentName(name) {
+        return name
+            .replace(/([A-Z])/g, '_$1')
+            .toLowerCase()
+            .replace(/^_/, '')
+            .replace(/__+/g, '_');
+    }
+}
+exports.ConfigLoader = ConfigLoader;
+exports.default = ConfigLoader;

package/dist/src/context-broker.js

@@ -0,0 +1,358 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextBroker = void 0;
+const crypto_1 = require("crypto");
+const events_1 = require("events");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const defaults_1 = require("./defaults");
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('context-broker');
+/**
+ * Context Broker - manages shared state and git locking for parallel agents
+ * Uses EventEmitter for zero-latency dependency notification instead of file polling
+ */
+class ContextBroker extends events_1.EventEmitter {
+    contextDir;
+    lockDir;
+    contextFile;
+    maxLockWaitMs = defaults_1.DEFAULT_CONTEXT_LOCK_WAIT_MS;
+    constructor(runDir) {
+        super();
+        // Plans with many steps create concurrent per-step listeners for dependency tracking
+        this.setMaxListeners(50);
+        this.contextDir = path.join(runDir, '.context');
+        this.lockDir = path.join(runDir, '.locks');
+        this.contextFile = path.join(this.contextDir, 'shared-context.json');
+        this.ensureDirectories();
+    }
+    ensureDirectories() {
+        if (!fs.existsSync(this.contextDir)) {
+            fs.mkdirSync(this.contextDir, { recursive: true });
+        }
+        if (!fs.existsSync(this.lockDir)) {
+            fs.mkdirSync(this.lockDir, { recursive: true });
+        }
+    }
+    /**
+     * Acquire a git lock for safe concurrent operations
+     * Returns lock ID if successful, null if timeout
+     */
+    async acquireGitLock(agentName, operation) {
+        const lockId = (0, crypto_1.randomBytes)(16).toString('hex');
+        const lockFile = path.join(this.lockDir, 'git.lock');
+        const lock = {
+            lockId,
+            agentName,
+            operation,
+            acquiredAt: new Date().toISOString()
+        };
+        const startTime = Date.now();
+        // spin-wait for lock with timeout
+        while (Date.now() - startTime < this.maxLockWaitMs) {
+            // Re-ensure lock directory exists (may have been removed by rollback/cleanup)
+            if (!fs.existsSync(this.lockDir)) {
+                fs.mkdirSync(this.lockDir, { recursive: true });
+            }
+            try {
+                // atomic file creation (fails if exists)
+                fs.writeFileSync(lockFile, JSON.stringify(lock, null, 2), { flag: 'wx' });
+                return lockId;
+            }
+            catch (err) {
+                const error = err;
+                if (error.code === 'ENOENT') {
+                    // Directory was removed between check and write, retry
+                    fs.mkdirSync(this.lockDir, { recursive: true });
+                    continue;
+                }
+                if (error.code === 'EEXIST') {
+                    // lock exists, check if stale (> 5 minutes old)
+                    try {
+                        const existingLock = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+                        const lockAge = Date.now() - new Date(existingLock.acquiredAt).getTime();
+                        if (lockAge > defaults_1.DEFAULT_CONTEXT_STALE_LOCK_MS) {
+                            // stale lock, force remove
+                            fs.unlinkSync(lockFile);
+                            continue;
+                        }
+                    }
+                    catch {
+                        // Lock file contains invalid JSON (corrupted write); safe to remove and retry
+                        fs.unlinkSync(lockFile);
+                        continue;
+                    }
+                    // wait and retry
+                    await this.sleep(100);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return null; // timeout
+    }
+    /**
+     * Release a git lock
+     */
+    releaseGitLock(lockId) {
+        const lockFile = path.join(this.lockDir, 'git.lock');
+        try {
+            const lock = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+            if (lock.lockId === lockId) {
+                fs.unlinkSync(lockFile);
+            }
+            else {
+                logger.warn(`Lock mismatch: expected ${lockId}, got ${lock.lockId}`);
+            }
+        }
+        catch (err) {
+            const error = err;
+            if (error.code !== 'ENOENT') {
+                logger.error('Failed to release lock:', error);
+            }
+        }
+    }
+    /**
+     * Force-remove all lock files regardless of age.
+     * Use before critical phases (e.g. final merge) to clear stale locks
+     * from cancelled runs.
+     */
+    forceReleaseStaleLocks() {
+        // Re-ensure lock directory exists (may have been removed by rollback/cleanup)
+        if (!fs.existsSync(this.lockDir)) {
+            fs.mkdirSync(this.lockDir, { recursive: true });
+        }
+        const lockFile = path.join(this.lockDir, 'git.lock');
+        try {
+            if (fs.existsSync(lockFile)) {
+                fs.unlinkSync(lockFile);
+            }
+        }
+        catch {
+            // Lock file may have been removed by a concurrent release; harmless
+        }
+    }
+    /**
+     * Add context from a completed step.
+     * Uses an exclusive file lock around the read-modify-write to prevent
+     * concurrent writers from losing entries. In single-process Node.js the
+     * synchronous I/O already serializes, but the lock protects against
+     * future multi-process architectures.
+     */
+    addStepContext(entry) {
+        this.ensureDirectories();
+        const lockFile = path.join(this.lockDir, 'context.lock');
+        this.acquireFileLockSync(lockFile);
+        try {
+            const contexts = this.getAllContext();
+            contexts.push(entry);
+            fs.writeFileSync(this.contextFile, JSON.stringify(contexts, null, 2), 'utf8');
+        }
+        finally {
+            this.releaseFileLockSync(lockFile);
+        }
+        this.emit('step-completed', entry.stepNumber);
+    }
+    /**
+     * Synchronous exclusive file lock via atomic wx creation.
+     * Stale locks (>5s) are force-removed on retry.
+     */
+    acquireFileLockSync(lockFile) {
+        const maxAttempts = 50;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                fs.writeFileSync(lockFile, JSON.stringify({ pid: process.pid, ts: Date.now() }), { flag: 'wx' });
+                return;
+            }
+            catch (err) {
+                const error = err;
+                if (error.code === 'EEXIST') {
+                    try {
+                        const stat = fs.statSync(lockFile);
+                        if (Date.now() - stat.mtimeMs > defaults_1.DEFAULT_SIGKILL_DELAY_MS) {
+                            fs.unlinkSync(lockFile);
+                            continue;
+                        }
+                    }
+                    catch {
+                        // Lock removed between check and stat; retry
+                        continue;
+                    }
+                    // Single-process Node.js: synchronous ops cannot interleave,
+                    // so this continue only fires in multi-process scenarios
+                    continue;
+                }
+                if (error.code === 'ENOENT') {
+                    this.ensureDirectories();
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error(`Failed to acquire context lock after ${maxAttempts} attempts: ${lockFile}`);
+    }
+    releaseFileLockSync(lockFile) {
+        try {
+            fs.unlinkSync(lockFile);
+        }
+        catch {
+            // Lock file already removed or directory cleaned; harmless
+        }
+    }
+    /**
+     * Get all shared context entries
+     */
+    getAllContext() {
+        if (!fs.existsSync(this.contextFile)) {
+            return [];
+        }
+        try {
+            const content = fs.readFileSync(this.contextFile, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn(`[context-broker] Failed to parse ${this.contextFile}: ${msg}`);
+            return [];
+        }
+    }
+    /**
+     * Get context for specific steps (useful for dependency resolution).
+     * When strictIsolation is true, only entries with verified transcript
+     * evidence are returned -- rejects anything backed by shared mutable state.
+     */
+    getContextForSteps(stepNumbers, strictIsolation = false) {
+        const allContext = this.getAllContext();
+        const byStep = allContext.filter(entry => stepNumbers.includes(entry.stepNumber));
+        if (!strictIsolation) {
+            return byStep;
+        }
+        // strict mode: only entries with a non-empty transcript path
+        return byStep.filter(entry => entry.data.transcript && entry.data.transcript.length > 0);
+    }
+    /**
+     * Get summary of changes from dependent steps.
+     * Strict isolation mode filters to transcript-backed entries only.
+     */
+    getDependencyContext(dependencies, strictIsolation = false) {
+        if (dependencies.length === 0) {
+            return 'No dependencies - you are starting fresh.';
+        }
+        const entries = this.getContextForSteps(dependencies, strictIsolation);
+        if (entries.length === 0) {
+            return `Dependencies: Steps ${dependencies.join(', ')} (context not yet available)`;
+        }
+        const lines = [];
+        lines.push(`Context from ${entries.length} dependent step(s):`);
+        entries.forEach(entry => {
+            lines.push(`\nStep ${entry.stepNumber} (${entry.agentName}):`);
+            lines.push(`  - ${entry.data.outputsSummary}`);
+            if (entry.data.filesChanged.length > 0) {
+                lines.push(`  - Files modified: ${entry.data.filesChanged.slice(0, 5).join(', ')}${entry.data.filesChanged.length > 5 ? '...' : ''}`);
+            }
+            if (entry.data.branchName) {
+                lines.push(`  - Branch: ${entry.data.branchName}`);
+            }
+            if (entry.data.commitShas && entry.data.commitShas.length > 0) {
+                lines.push(`  - Commits: ${entry.data.commitShas.length}`);
+            }
+        });
+        return lines.join('\n');
+    }
+    /**
+     * Check if all dependencies are satisfied
+     */
+    areDependenciesSatisfied(dependencies) {
+        if (dependencies.length === 0) {
+            return true;
+        }
+        const completedSteps = new Set(this.getAllContext().map(entry => entry.stepNumber));
+        return dependencies.every(dep => completedSteps.has(dep));
+    }
+    /**
+     * Wait for dependencies to be satisfied.
+     * Uses EventEmitter notifications instead of file polling for zero-latency response.
+     * Falls back to a timeout to prevent indefinite hangs.
+     */
+    async waitForDependencies(dependencies, timeoutMs = defaults_1.DEFAULT_DEPENDENCY_WAIT_MS) {
+        if (this.areDependenciesSatisfied(dependencies)) {
+            return true;
+        }
+        return new Promise((resolve) => {
+            const remaining = new Set(dependencies.filter(dep => {
+                const completedSteps = new Set(this.getAllContext().map(e => e.stepNumber));
+                return !completedSteps.has(dep);
+            }));
+            if (remaining.size === 0) {
+                resolve(true);
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.removeListener('step-completed', onStep);
+                resolve(false);
+            }, timeoutMs);
+            const onStep = (stepNumber) => {
+                remaining.delete(stepNumber);
+                if (remaining.size === 0) {
+                    clearTimeout(timer);
+                    this.removeListener('step-completed', onStep);
+                    resolve(true);
+                }
+            };
+            this.on('step-completed', onStep);
+        });
+    }
+    /**
+     * Clear all context (useful for testing or fresh runs)
+     */
+    clearContext() {
+        if (fs.existsSync(this.contextFile)) {
+            fs.unlinkSync(this.contextFile);
+        }
+        // clean up any stale locks
+        if (fs.existsSync(this.lockDir)) {
+            const lockFiles = fs.readdirSync(this.lockDir);
+            lockFiles.forEach(file => {
+                fs.unlinkSync(path.join(this.lockDir, file));
+            });
+        }
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.ContextBroker = ContextBroker;
+exports.default = ContextBroker;