@cleocode/cleo 2026.4.41 → 2026.4.43

package/dist/dispatch/engines/orchestrate-engine.js

@@ -1,912 +0,0 @@
-/**
- * Orchestrate Engine
- *
- * Thin wrapper layer that delegates to core modules.
- * All business logic lives in src/core/orchestration/.
- *
- * Wave 7a (T432): composeSpawnPayload from @cleocode/cant is now wired into
- * the orchestrateSpawnExecute path. Before the Pi adapter spawn call, the
- * composer runs JIT context assembly (context_sources from BRAIN + mental model)
- * and produces a token-budgeted systemPrompt. The resulting prompt replaces the
- * raw prepareSpawn prompt so subagents receive fully-composed context at spawn
- * time. This unblocks the ULTRAPLAN Wave 5 empirical gate (T432 blocker).
- *
- * @task T4478
- * @task T4784
- * @task T432
- */
-// Core module imports
-import { orchestrationAnalyzeDependencies as analyzeDependencies, analyzeEpic, buildBrainState, computeEpicStatus, computeOverallStatus, computeProgress, computeStartupSummary, endParallelExecution, estimateContext, getAccessor, orchestrationGetCriticalPath as getCriticalPath, getEnrichedWaves, orchestrationGetNextTask as getNextTask, getParallelStatus, orchestrationGetReadyTasks as getReadyTasks, getSkillContent, getUnblockOpportunities, prepareSpawn, resolveProjectRoot, startParallelExecution, validateSpawnReadiness, } from '@cleocode/core/internal';
-import { cleoErrorToEngineError, engineError } from './_error.js';
-import { sessionContextInject, sessionEnd, sessionStatus } from './session-engine.js';
-/**
- * Send a structured orchestration event to conduit.db via the active agent
- * credential. Failures are silently swallowed — conduit events MUST NOT block
- * or alter orchestration outcomes.
- *
- * @param cwd   - Project root used to locate conduit.db and the agent registry.
- * @param to    - Recipient agent ID (e.g. 'cleo-core').
- * @param event - Structured event payload (LAFS-shaped JSON).
- */
-async function sendConduitEvent(cwd, to, event) {
-    try {
-        const { AgentRegistryAccessor, createConduit } = await import('@cleocode/core/internal');
-        const registry = new AgentRegistryAccessor(cwd);
-        const conduit = await createConduit(registry);
-        try {
-            await conduit.send(to, JSON.stringify(event));
-        }
-        finally {
-            await conduit.disconnect();
-        }
-    }
-    catch {
-        // Best-effort: conduit failures must never surface to callers
-    }
-}
-/**
- * Load all tasks from task data.
- */
-async function loadTasks(projectRoot) {
-    const root = projectRoot || resolveProjectRoot();
-    try {
-        const accessor = await getAccessor(root);
-        const result = await accessor.queryTasks({});
-        return result?.tasks ?? [];
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * orchestrate.status - Get orchestrator status
- * @task T4478
- */
-export async function orchestrateStatus(epicId, projectRoot) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const tasks = await loadTasks(root);
-        if (epicId) {
-            const epic = tasks.find((t) => t.id === epicId);
-            if (!epic) {
-                return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
-            }
-            const children = tasks.filter((t) => t.parentId === epicId);
-            const status = computeEpicStatus(epicId, epic.title, children);
-            return { success: true, data: status };
-        }
-        // No epicId - return overall status
-        const status = computeOverallStatus(tasks);
-        return { success: true, data: status };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.analyze - Dependency analysis
- * @task T4478
- */
-export async function orchestrateAnalyze(epicId, projectRoot, mode) {
-    // Mode: critical-path (delegates to critical path engine)
-    if (mode === 'critical-path') {
-        return orchestrateCriticalPath(projectRoot);
-    }
-    // Default mode: analysis (requires epicId)
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required for standard analysis');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const result = await analyzeEpic(epicId, root, accessor);
-        // Add dependency graph and circular dep detection via core analyze module
-        const tasks = await loadTasks(root);
-        const children = tasks.filter((t) => t.parentId === epicId);
-        const depAnalysis = analyzeDependencies(children, tasks);
-        return {
-            success: true,
-            data: {
-                epicId: result.epicId,
-                epicTitle: tasks.find((t) => t.id === epicId)?.title || epicId,
-                totalTasks: result.totalTasks,
-                waves: result.waves,
-                circularDependencies: depAnalysis.circularDependencies,
-                missingDependencies: depAnalysis.missingDependencies,
-                dependencyGraph: depAnalysis.dependencyGraph,
-            },
-        };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.ready - Get parallel-safe tasks (ready to execute)
- * @task T4478
- */
-export async function orchestrateReady(epicId, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const readyTasks = await getReadyTasks(epicId, root, accessor);
-        const ready = readyTasks.filter((t) => t.ready);
-        return {
-            success: true,
-            data: {
-                epicId,
-                readyTasks: ready.map((t) => ({
-                    id: t.taskId,
-                    title: t.title,
-                    priority: 'medium', // getReadyTasks doesn't return priority
-                    depends: t.blockers,
-                })),
-                total: ready.length,
-            },
-        };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.next - Next task to spawn
- * @task T4478
- */
-export async function orchestrateNext(epicId, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const nextTask = await getNextTask(epicId, root, accessor);
-        if (!nextTask) {
-            return {
-                success: true,
-                data: {
-                    epicId,
-                    nextTask: null,
-                    message: 'No tasks ready to spawn. All pending tasks may have unmet dependencies.',
-                },
-            };
-        }
-        // Get all ready tasks for alternatives
-        const readyTasks = await getReadyTasks(epicId, root, accessor);
-        const ready = readyTasks.filter((t) => t.ready);
-        return {
-            success: true,
-            data: {
-                epicId,
-                nextTask: { id: nextTask.taskId, title: nextTask.title, priority: 'medium' },
-                alternatives: ready
-                    .slice(1, 4)
-                    .map((t) => ({ id: t.taskId, title: t.title, priority: 'medium' })),
-                totalReady: ready.length,
-            },
-        };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.waves - Compute dependency waves
- * @task T4478
- */
-export async function orchestrateWaves(epicId, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const result = await getEnrichedWaves(epicId, root, accessor);
-        return { success: true, data: result };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.context - Context usage check
- * @task T4478
- */
-export async function orchestrateContext(epicId, projectRoot) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const tasks = await loadTasks(root);
-        let taskCount = tasks.length;
-        if (epicId) {
-            taskCount = tasks.filter((t) => t.parentId === epicId).length;
-        }
-        const contextData = estimateContext(taskCount, root, epicId);
-        return { success: true, data: contextData };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.validate - Validate spawn readiness for a task
- * @task T4478
- */
-export async function orchestrateValidate(taskId, projectRoot) {
-    if (!taskId) {
-        return engineError('E_INVALID_INPUT', 'taskId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const result = await validateSpawnReadiness(taskId, root, accessor);
-        return { success: true, data: result };
-    }
-    catch (err) {
-        return engineError('E_VALIDATION', err.message);
-    }
-}
-/**
- * orchestrate.spawn.select - Select best provider for spawn based on required capabilities
- * @task T5236
- */
-export async function orchestrateSpawnSelectProvider(capabilities, _projectRoot) {
-    if (!capabilities || capabilities.length === 0) {
-        return engineError('E_INVALID_INPUT', 'At least one capability is required');
-    }
-    try {
-        const { initializeDefaultAdapters, spawnRegistry } = await import('@cleocode/core/internal');
-        const { getAllProviders, getProvidersBySpawnCapability, providerSupportsById } = await import('@cleocode/caamp');
-        await initializeDefaultAdapters();
-        // Get providers matching all required capabilities
-        let matchingProviders = [];
-        if (capabilities.length === 1) {
-            // Single capability - use direct filter
-            matchingProviders = getProvidersBySpawnCapability(capabilities[0]);
-        }
-        else {
-            // Multiple capabilities - find intersection
-            const providerSets = capabilities.map((cap) => new Set(getProvidersBySpawnCapability(cap).map((p) => p.id)));
-            // Find intersection of all provider IDs
-            const allProviders = await spawnRegistry.listSpawnCapable();
-            const intersection = allProviders
-                .filter((adapter) => providerSets.every((set) => set.has(adapter.providerId)))
-                .map((adapter) => getAllProviders().find((p) => p.id === adapter.providerId))
-                .filter((provider) => provider !== undefined);
-            matchingProviders = intersection;
-        }
-        if (matchingProviders.length === 0) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_NO_PROVIDER',
-                    message: `No provider found with all required capabilities: ${capabilities.join(', ')}`,
-                    exitCode: 60,
-                },
-            };
-        }
-        // Get first registered adapter for the matching providers
-        const adapter = matchingProviders
-            .map((p) => spawnRegistry.getForProvider(p.id))
-            .find((a) => a !== undefined);
-        if (!adapter) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_NO_ADAPTER',
-                    message: 'No spawn adapter registered for matching providers',
-                    exitCode: 60,
-                },
-            };
-        }
-        // Verify adapter can actually spawn
-        const canSpawn = await adapter.canSpawn();
-        if (!canSpawn) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_ADAPTER_UNAVAILABLE',
-                    message: `Selected adapter '${adapter.id}' cannot spawn in current environment`,
-                    exitCode: 63,
-                },
-            };
-        }
-        return {
-            success: true,
-            data: {
-                providerId: adapter.providerId,
-                adapterId: adapter.id,
-                capabilities: capabilities.filter((cap) => providerSupportsById(adapter.providerId, `spawn.${cap}`)),
-            },
-        };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.spawn.execute - Execute spawn for a task using adapter registry
- * @task T5236
- */
-export async function orchestrateSpawnExecute(taskId, adapterId, protocolType, projectRoot, tier) {
-    const cwd = projectRoot ?? process.cwd();
-    try {
-        // Get spawn registry
-        const { initializeDefaultAdapters, spawnRegistry } = await import('@cleocode/core/internal');
-        await initializeDefaultAdapters();
-        // Find adapter
-        let adapter;
-        if (adapterId) {
-            adapter = spawnRegistry.get(adapterId);
-        }
-        else {
-            // Auto-select first capable adapter
-            const capable = await spawnRegistry.listSpawnCapable();
-            adapter = capable[0];
-        }
-        if (!adapter) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_NO_ADAPTER',
-                    message: 'No spawn adapter available for this provider',
-                    exitCode: 60,
-                },
-            };
-        }
-        // Verify provider supports subagents using providerSupportsById
-        const { providerSupportsById } = await import('@cleocode/caamp');
-        if (!providerSupportsById(adapter.providerId, 'spawn.supportsSubagents')) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_CAPABILITY_UNSUPPORTED',
-                    message: `Provider ${adapter.providerId} does not support spawning subagents`,
-                    exitCode: 60,
-                },
-            };
-        }
-        // Prepare spawn context (reuse existing prepareSpawn logic)
-        const { prepareSpawn } = await import('@cleocode/core/internal');
-        const accessor = await getAccessor(cwd);
-        const spawnContext = await prepareSpawn(taskId, cwd, accessor);
-        // Check for unresolved tokens
-        if (!spawnContext.tokenResolution.fullyResolved) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_VALIDATION_FAILED',
-                    message: `Unresolved tokens in spawn context: ${spawnContext.tokenResolution.unresolvedTokens.join(', ')}`,
-                    exitCode: 63,
-                },
-            };
-        }
-        // Build CLEO spawn context from core spawn context
-        const { getSpawnCapableProviders } = await import('@cleocode/caamp');
-        const providers = getSpawnCapableProviders();
-        const provider = providers.find((p) => p.id === adapter.providerId);
-        if (!provider) {
-            return {
-                success: false,
-                error: {
-                    code: 'E_SPAWN_NO_PROVIDER',
-                    message: `Provider ${adapter.providerId} not found`,
-                    exitCode: 60,
-                },
-            };
-        }
-        // T432 (Wave 7a): JIT context assembly via composeSpawnPayload.
-        //
-        // Attempt to load the agent definition from the CANT bundle for this task.
-        // If the task has a compiled .cant agent definition available, we compose
-        // a token-budgeted system prompt that includes BRAIN context sources and
-        // the agent's mental model. The composed prompt replaces the raw prepareSpawn
-        // prompt. If no CANT definition is available or the composer throws, we fall
-        // back to the raw prompt (graceful degradation — never blocks spawning).
-        let composedPrompt = spawnContext.prompt;
-        try {
-            const { composeSpawnPayload } = await import('@cleocode/cant');
-            const { brainContextProvider } = await import('@cleocode/cant');
-            const { createHash } = await import('node:crypto');
-            // Derive a project hash for scoped mental model lookup.
-            const projectHash = createHash('sha256').update(cwd).digest('hex').slice(0, 12);
-            // Look for a compiled agent definition attached to the spawn context.
-            // The spawn context may carry an `agentDef` field if the task was
-            // created via `cleo orchestrate spawn` with a compiled CANT bundle.
-            // For tasks without an agentDef we use a minimal stub so that the
-            // composer still assembles any available BRAIN context.
-            const agentDef = spawnContext.agentDef;
-            if (agentDef) {
-                const provider = brainContextProvider(cwd);
-                const payload = await composeSpawnPayload(agentDef, provider, projectHash);
-                composedPrompt = payload.systemPrompt;
-            }
-            // If no agentDef, composedPrompt remains the raw prepareSpawn prompt.
-        }
-        catch {
-            // Graceful degradation: composer failure must never block spawning.
-            // The raw prompt from prepareSpawn is used unchanged.
-        }
-        const cleoSpawnContext = {
-            taskId: spawnContext.taskId,
-            protocol: protocolType || spawnContext.protocol,
-            prompt: composedPrompt,
-            provider: provider.id,
-            options: {
-                prompt: composedPrompt,
-            },
-            workingDirectory: cwd,
-            tokenResolution: {
-                resolved: [],
-                unresolved: spawnContext.tokenResolution.unresolvedTokens,
-                totalTokens: 0,
-            },
-        };
-        // Wave 6-C/D: Capacity-aware routing — find the least-loaded agent and
-        // attach it as a preferred routing hint on the spawn options.
-        // Best-effort: if no agents are registered or the check throws, fall
-        // through to default spawn behavior without blocking.
-        try {
-            const { findLeastLoadedAgent } = await import('@cleocode/core/internal');
-            const leastLoaded = await findLeastLoadedAgent(undefined, cwd);
-            if (leastLoaded) {
-                cleoSpawnContext.options = {
-                    ...cleoSpawnContext.options,
-                    preferredAgent: leastLoaded.id,
-                };
-            }
-        }
-        catch {
-            // Capacity check is best-effort — never block spawn
-        }
-        // Dispatch SubagentStart hook BEFORE spawning — triggers brain observation
-        // recording and conduit messaging for the agent lifecycle (T555).
-        try {
-            const { hooks } = await import('@cleocode/core/internal');
-            await hooks
-                .dispatch('SubagentStart', cwd, {
-                timestamp: new Date().toISOString(),
-                taskId,
-                agentId: cleoSpawnContext.options?.preferredAgent ?? `worker-${taskId}`,
-                role: protocolType || 'worker',
-                providerId: adapter.providerId,
-            })
-                .catch(() => {
-                /* Hooks are best-effort — never block spawn */
-            });
-        }
-        catch {
-            /* Hook registry unavailable — non-fatal */
-        }
-        // Execute spawn
-        const result = await adapter.spawn(cleoSpawnContext);
-        // Dispatch SubagentStop hook AFTER spawn returns — records completion
-        // status in brain and conduit (T555).
-        try {
-            const { hooks } = await import('@cleocode/core/internal');
-            await hooks
-                .dispatch('SubagentStop', cwd, {
-                timestamp: new Date().toISOString(),
-                taskId,
-                agentId: cleoSpawnContext.options?.preferredAgent ?? `worker-${taskId}`,
-                status: result.status,
-                instanceId: result.instanceId,
-            })
-                .catch(() => {
-                /* Hooks are best-effort — never block spawn */
-            });
-        }
-        catch {
-            /* Hook registry unavailable — non-fatal */
-        }
-        // Best-effort: record spawn event in conduit.db so agents can observe
-        // orchestration activity. Never awaited in a blocking way — fires and
-        // the main return path continues regardless of conduit outcome.
-        void sendConduitEvent(cwd, 'cleo-core', {
-            event: 'agent.spawned',
-            taskId,
-            instanceId: result.instanceId,
-            status: result.status,
-            providerId: adapter.providerId,
-            adapterId: adapter.id,
-            tier: tier ?? null,
-            spawnedAt: new Date().toISOString(),
-        });
-        return {
-            success: true,
-            data: {
-                instanceId: result.instanceId,
-                status: result.status,
-                providerId: adapter.providerId,
-                taskId,
-                timing: result.timing,
-                tier: tier ?? null,
-            },
-        };
-    }
-    catch (error) {
-        return {
-            success: false,
-            error: {
-                code: 'E_SPAWN_FAILED',
-                message: error instanceof Error ? error.message : 'Unknown spawn error',
-                exitCode: 60,
-            },
-        };
-    }
-}
-/**
- * orchestrate.spawn - Generate spawn prompt for a task
- * @task T4478
- */
-export async function orchestrateSpawn(taskId, protocolType, projectRoot, tier) {
-    if (!taskId) {
-        return engineError('E_INVALID_INPUT', 'taskId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        // Validate readiness first
-        const accessor = await getAccessor(root);
-        const validation = await validateSpawnReadiness(taskId, root, accessor);
-        if (!validation.ready) {
-            return engineError('E_SPAWN_VALIDATION_FAILED', `Task ${taskId} is not ready to spawn`, {
-                details: { issues: validation.issues },
-            });
-        }
-        // Prepare spawn context via core
-        const spawnContext = await prepareSpawn(taskId, root, accessor);
-        return {
-            success: true,
-            data: {
-                taskId,
-                spawnContext: {
-                    taskId: spawnContext.taskId,
-                    protocol: spawnContext.protocol,
-                    protocolType: protocolType || spawnContext.protocol,
-                    tier: tier ?? null,
-                },
-                protocolType: protocolType || spawnContext.protocol,
-                tier: tier ?? null,
-                tokenResolution: spawnContext.tokenResolution,
-            },
-        };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.startup - Initialize orchestration for an epic
- * @task T4478
- */
-export async function orchestrateStartup(epicId, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const tasks = await loadTasks(root);
-        const epic = tasks.find((t) => t.id === epicId);
-        if (!epic) {
-            return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
-        }
-        const children = tasks.filter((t) => t.parentId === epicId);
-        const readyTasks = await getReadyTasks(epicId, root, accessor);
-        const ready = readyTasks.filter((t) => t.ready);
-        const summary = computeStartupSummary(epicId, epic.title, children, ready.length);
-        return { success: true, data: summary };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.bootstrap - Load brain state for agent bootstrapping
- * @task T4478
- * @task T4657
- */
-export async function orchestrateBootstrap(projectRoot, params) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const brain = await buildBrainState(root, params, accessor);
-        return { success: true, data: brain };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.critical-path - Find the longest dependency chain
- * @task T4478
- */
-export async function orchestrateCriticalPath(projectRoot) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const result = await getCriticalPath(root, accessor);
-        return { success: true, data: result };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.unblock-opportunities - Analyze dependency graph for unblocking opportunities
- * @task T4478
- */
-export async function orchestrateUnblockOpportunities(projectRoot) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const result = await getUnblockOpportunities(root, accessor);
-        return { success: true, data: result };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.parallel - Manage parallel execution (start/end)
- * @task T4632
- */
-export async function orchestrateParallel(action, epicId, wave, projectRoot) {
-    if (action === 'start') {
-        if (wave === undefined || wave === null) {
-            return engineError('E_INVALID_INPUT', 'wave number is required for start action');
-        }
-        return orchestrateParallelStart(epicId, wave, projectRoot);
-    }
-    if (action === 'end') {
-        // wave is technically optional for end if we want to end ANY parallel execution,
-        // but the current implementation expects wave.
-        // However, endParallelExecution calls endParallelExecution(epicId, wave, root)
-        if (wave === undefined || wave === null) {
-            // If wave is not provided, maybe we can find the active one?
-            // For now, let's require it to match the underlying signature or default to 0/current?
-            // The underlying `endParallelExecution` signature is `(epicId: string, wave: number, root: string)`.
-            // Let's require it for now to be safe, or check if we can improve this.
-            return engineError('E_INVALID_INPUT', 'wave number is required for end action');
-        }
-        return orchestrateParallelEnd(epicId, wave, projectRoot);
-    }
-    return engineError('E_INVALID_INPUT', `Unknown parallel action: ${action}`);
-}
-/**
- * orchestrate.parallel.start - Start parallel execution for a wave
- * @task T4632
- */
-export async function orchestrateParallelStart(epicId, wave, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
-    if (wave === undefined || wave === null) {
-        return engineError('E_INVALID_INPUT', 'wave number is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const accessor = await getAccessor(root);
-        const result = await startParallelExecution(epicId, wave, root, accessor);
-        return { success: true, data: result };
-    }
-    catch (err) {
-        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to start parallel execution');
-    }
-}
-/**
- * orchestrate.parallel.end - End parallel execution for a wave
- * @task T4632
- */
-export async function orchestrateParallelEnd(epicId, wave, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const result = await endParallelExecution(epicId, wave, root);
-        if (result.alreadyEnded) {
-            return {
-                success: true,
-                data: {
-                    epicId,
-                    wave,
-                    message: 'No parallel execution was active',
-                    alreadyEnded: true,
-                },
-            };
-        }
-        return { success: true, data: result };
-    }
-    catch (err) {
-        return cleoErrorToEngineError(err, 'E_GENERAL', 'Failed to end parallel execution');
-    }
-}
-/**
- * orchestrate.check - Check current orchestration state
- * @task T4632
- */
-export async function orchestrateCheck(projectRoot) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const parallelState = await getParallelStatus(root);
-        const tasks = await loadTasks(root);
-        const activeTasks = tasks.filter((t) => t.status === 'active');
-        const progress = computeProgress(tasks);
-        return {
-            success: true,
-            data: {
-                parallelExecution: {
-                    active: parallelState.active,
-                    epicId: parallelState.epicId || null,
-                    wave: parallelState.wave || null,
-                    tasks: parallelState.tasks || [],
-                    startedAt: parallelState.startedAt || null,
-                },
-                activeTasks: activeTasks.map((t) => ({ id: t.id, title: t.title, status: t.status })),
-                progress,
-            },
-        };
-    }
-    catch (err) {
-        return engineError('E_GENERAL', err.message);
-    }
-}
-/**
- * orchestrate.skill.inject - Read skill content for injection into agent context
- * @task T4632
- */
-export function orchestrateSkillInject(skillName, projectRoot) {
-    try {
-        const root = projectRoot || resolveProjectRoot();
-        const result = getSkillContent(skillName, root);
-        return { success: true, data: result };
-    }
-    catch (err) {
-        const code = err.code ?? 'E_GENERAL';
-        return engineError(code, err.message);
-    }
-}
-/**
- * orchestrate.handoff - Composite session handoff + successor spawn
- *
- * Step order is explicit and fixed:
- * 1) session.context.inject
- * 2) session.end
- * 3) orchestrate.spawn
- *
- * Idempotency policy:
- * - Non-idempotent overall. A retry after step 2 can duplicate spawn output.
- * - Failures include exact step state and a safe retry entry point.
- */
-export async function orchestrateHandoff(params, projectRoot) {
-    if (!params.taskId) {
-        return engineError('E_INVALID_INPUT', 'taskId is required');
-    }
-    if (!params.protocolType) {
-        return engineError('E_INVALID_INPUT', 'protocolType is required');
-    }
-    const root = projectRoot || resolveProjectRoot();
-    const steps = {
-        contextInject: { status: 'pending', operation: 'session.context.inject' },
-        sessionEnd: { status: 'pending', operation: 'session.end' },
-        spawn: { status: 'pending', operation: 'orchestrate.spawn' },
-    };
-    const idempotency = {
-        key: params.idempotencyKey ?? null,
-        policy: 'non-idempotent',
-        safeRetryFrom: 'start',
-        reason: 'session.end and orchestrate.spawn mutate state and may be executed independently on retry',
-    };
-    let activeSessionId = null;
-    let endedSessionId = null;
-    const failWithStep = (code, message, failedStep, safeRetryFrom) => {
-        idempotency.safeRetryFrom = safeRetryFrom;
-        return engineError(code, message, {
-            details: {
-                failedStep,
-                activeSessionId,
-                endedSessionId,
-                idempotency,
-                steps,
-            },
-            fix: safeRetryFrom === 'orchestrate.spawn'
-                ? 'Retry only step 3 with mutate orchestrate spawn'
-                : 'Retry from step 1 with mutate orchestrate handoff',
-            alternatives: [
-                {
-                    action: 'Run canonical multi-op fallback manually',
-                    command: 'mutate session context.inject -> mutate session end -> mutate orchestrate spawn',
-                },
-            ],
-        });
-    };
-    const preflight = await sessionStatus(root);
-    if (!preflight.success) {
-        return failWithStep(preflight.error?.code ?? 'E_NOT_INITIALIZED', preflight.error?.message ?? 'Unable to load session status', 'session.context.inject', 'start');
-    }
-    if (!preflight.data?.hasActiveSession || !preflight.data.session?.id) {
-        steps.contextInject.status = 'skipped';
-        steps.contextInject.message = 'No active session available for handoff';
-        steps.sessionEnd.status = 'skipped';
-        steps.sessionEnd.message = 'No active session available for handoff';
-        steps.spawn.status = 'skipped';
-        steps.spawn.message = 'No active session available for handoff';
-        return failWithStep('E_SESSION_REQUIRED', 'orchestrate.handoff requires an active session', 'session.end', 'start');
-    }
-    activeSessionId = preflight.data.session.id;
-    const injectResult = sessionContextInject(params.protocolType, { taskId: params.taskId, variant: params.variant }, root);
-    if (!injectResult.success) {
-        steps.contextInject.status = 'failed';
-        steps.contextInject.message = injectResult.error?.message;
-        steps.sessionEnd.status = 'skipped';
-        steps.sessionEnd.message = 'Blocked by session.context.inject failure';
-        steps.spawn.status = 'skipped';
-        steps.spawn.message = 'Blocked by session.context.inject failure';
-        return failWithStep(injectResult.error?.code ?? 'E_GENERAL', injectResult.error?.message ?? 'Failed to inject handoff context', 'session.context.inject', 'start');
-    }
-    steps.contextInject.status = 'completed';
-    steps.contextInject.message = 'Handoff context injected';
-    const endResult = await sessionEnd(root, params.note);
-    if (!endResult.success) {
-        steps.sessionEnd.status = 'failed';
-        steps.sessionEnd.message = endResult.error?.message;
-        steps.spawn.status = 'skipped';
-        steps.spawn.message = 'Blocked by session.end failure';
-        return failWithStep(endResult.error?.code ?? 'E_GENERAL', endResult.error?.message ?? 'Failed to end predecessor session', 'session.end', 'start');
-    }
-    endedSessionId = endResult.data?.sessionId ?? null;
-    if (endedSessionId !== activeSessionId) {
-        steps.sessionEnd.status = 'failed';
-        steps.sessionEnd.message = `Ended session '${endedSessionId ?? 'null'}' does not match active session '${activeSessionId}'`;
-        steps.spawn.status = 'skipped';
-        steps.spawn.message = 'Blocked by session mismatch';
-        return failWithStep('E_CONCURRENT_SESSION', 'Active session changed during orchestrate.handoff', 'session.end', 'start');
-    }
-    steps.sessionEnd.status = 'completed';
-    steps.sessionEnd.message = `Ended session ${endedSessionId}`;
-    const spawnResult = await orchestrateSpawn(params.taskId, params.protocolType, root, params.tier);
-    if (!spawnResult.success) {
-        steps.spawn.status = 'failed';
-        steps.spawn.message = spawnResult.error?.message;
-        return failWithStep(spawnResult.error?.code ?? 'E_GENERAL', spawnResult.error?.message ?? 'Failed to prepare successor spawn context', 'orchestrate.spawn', 'orchestrate.spawn');
-    }
-    steps.spawn.status = 'completed';
-    steps.spawn.message = `Spawn prepared for ${params.taskId}`;
-    // Best-effort: record handoff event in conduit.db so orchestrators and
-    // observers can track session transitions. Never blocks the return.
-    void sendConduitEvent(root, 'cleo-core', {
-        event: 'orchestrate.handoff',
-        taskId: params.taskId,
-        protocolType: params.protocolType,
-        predecessorSessionId: activeSessionId,
-        endedSessionId,
-        note: params.note ?? null,
-        nextAction: params.nextAction ?? null,
-        handoffAt: new Date().toISOString(),
-    });
-    return {
-        success: true,
-        data: {
-            taskId: params.taskId,
-            predecessorSessionId: activeSessionId,
-            endedSessionId,
-            protocolType: params.protocolType,
-            note: params.note ?? null,
-            nextAction: params.nextAction ?? null,
-            idempotency,
-            steps,
-            contextInject: injectResult.data,
-            spawn: spawnResult.data,
-        },
-    };
-}
-//# sourceMappingURL=orchestrate-engine.js.map