@cleocode/cleo 2026.4.31 → 2026.4.36

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

@@ -0,0 +1,824 @@
+/**
+ * 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';
+/**
+ * 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
+        }
+        // Execute spawn
+        const result = await adapter.spawn(cleoSpawnContext);
+        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}`;
+    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