@kbediako/codex-orchestrator 0.1.38 → 0.2.0

package/dist/orchestrator/src/cli/services/execRuntime.js

@@ -18,6 +18,7 @@ const sessionManager = new ExecSessionManager({
 });
 const privacyGuard = new PrivacyGuard({ mode: resolvePrivacyGuardMode() });
 const handleService = new RemoteExecHandleService({ guard: privacyGuard, now: () => new Date() });
+const POST_EXIT_STDIO_DRAIN_TIMEOUT_MS = 500;
 const cliExecutor = async (request) => {
     const hasExplicitArgs = Array.isArray(request.args);
     const child = spawn(request.command, request.args ?? [], {
@@ -34,19 +35,83 @@ const cliExecutor = async (request) => {
     child.stdout.on('data', request.onStdout);
     child.stderr.on('data', request.onStderr);
     return await new Promise((resolve, reject) => {
-        const handleExit = (exitCode, signal) => {
+        let settled = false;
+        let exited = false;
+        let exitCode = null;
+        let signal = null;
+        let stdoutEnded = false;
+        let stderrEnded = false;
+        let drainTimeout = null;
+        const finalize = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
             cleanup();
             resolve({ exitCode, signal });
         };
+        const setExitState = (nextExitCode, nextSignal) => {
+            if (exited) {
+                return;
+            }
+            exited = true;
+            exitCode = nextExitCode;
+            signal = nextSignal;
+        };
+        const maybeFinalizeAfterExit = () => {
+            if (!exited || !stdoutEnded || !stderrEnded) {
+                return;
+            }
+            finalize();
+        };
+        const armDrainTimeout = () => {
+            if (drainTimeout) {
+                return;
+            }
+            drainTimeout = setTimeout(() => {
+                finalize();
+            }, POST_EXIT_STDIO_DRAIN_TIMEOUT_MS);
+            drainTimeout.unref?.();
+        };
+        const handleExit = (nextExitCode, nextSignal) => {
+            setExitState(nextExitCode, nextSignal);
+            if (stdoutEnded && stderrEnded) {
+                finalize();
+                return;
+            }
+            armDrainTimeout();
+        };
+        const handleClose = (nextExitCode, nextSignal) => {
+            setExitState(nextExitCode, nextSignal);
+            finalize();
+        };
         const handleError = (error) => {
             cleanup();
             reject(error);
         };
+        const handleStdoutEnd = () => {
+            stdoutEnded = true;
+            maybeFinalizeAfterExit();
+        };
+        const handleStderrEnd = () => {
+            stderrEnded = true;
+            maybeFinalizeAfterExit();
+        };
         const cleanup = () => {
+            child.stdout.off('end', handleStdoutEnd);
+            child.stderr.off('end', handleStderrEnd);
             child.off('exit', handleExit);
+            child.off('close', handleClose);
             child.off('error', handleError);
+            if (drainTimeout) {
+                clearTimeout(drainTimeout);
+                drainTimeout = null;
+            }
         };
+        child.stdout.once('end', handleStdoutEnd);
+        child.stderr.once('end', handleStderrEnd);
         child.once('exit', handleExit);
+        child.once('close', handleClose);
         child.once('error', handleError);
     });
 };

package/dist/orchestrator/src/cli/services/orchestratorAutoScoutEvidenceRecorder.js

@@ -0,0 +1,71 @@
+import process from 'node:process';
+import { join } from 'node:path';
+import { writeJsonAtomic } from '../utils/fs.js';
+import { buildAutoScoutEvidence } from '../utils/advancedAutopilot.js';
+import { isoTimestamp } from '../utils/time.js';
+import { relativeToRepo } from '../run/runPaths.js';
+import { resolveCloudBranch } from './orchestratorCloudBranchResolution.js';
+import { resolveCloudEnvironmentId } from './orchestratorCloudEnvironmentResolution.js';
+const DEFAULT_AUTO_SCOUT_TIMEOUT_MS = 4000;
+function readCloudNumber(raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return parsed;
+}
+export async function recordOrchestratorAutoScoutEvidence(params) {
+    const mergedEnv = { ...process.env, ...(params.envOverrides ?? {}) };
+    const timeoutMs = readCloudNumber(mergedEnv.CODEX_ORCHESTRATOR_AUTO_SCOUT_TIMEOUT_MS, DEFAULT_AUTO_SCOUT_TIMEOUT_MS);
+    const work = async () => {
+        const cloudEnvironmentId = resolveCloudEnvironmentId(params.task, params.target, params.envOverrides);
+        const cloudBranch = resolveCloudBranch(params.envOverrides);
+        const cloudRequested = params.mode === 'cloud' || params.manifest.cloud_fallback?.mode_requested === 'cloud';
+        const evidence = buildAutoScoutEvidence({
+            taskId: params.manifest.task_id,
+            pipelineId: params.pipeline.id,
+            targetId: params.target.id,
+            targetDescription: params.target.description,
+            executionMode: params.mode,
+            cloudRequested,
+            advanced: params.advancedDecision,
+            cloudEnvironmentId,
+            cloudBranch,
+            env: mergedEnv,
+            generatedAt: isoTimestamp()
+        });
+        const evidencePath = join(params.paths.runDir, 'auto-scout.json');
+        await writeJsonAtomic(evidencePath, evidence);
+        return { status: 'recorded', path: relativeToRepo(params.env, evidencePath) };
+    };
+    try {
+        let timeoutHandle = null;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => {
+                resolve({
+                    status: 'timeout',
+                    message: `timed out after ${Math.round(timeoutMs / 1000)}s`
+                });
+            }, timeoutMs);
+            timeoutHandle.unref?.();
+        });
+        const workPromise = work().catch((error) => ({
+            status: 'error',
+            message: error?.message ?? String(error)
+        }));
+        const result = await Promise.race([workPromise, timeoutPromise]);
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+        return result;
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            message: error?.message ?? String(error)
+        };
+    }
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudBranchResolution.js

@@ -0,0 +1,8 @@
+import process from 'node:process';
+function readCloudBranchString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+export function resolveCloudBranch(envOverrides) {
+    return (readCloudBranchString(envOverrides?.CODEX_CLOUD_BRANCH) ??
+        readCloudBranchString(process.env.CODEX_CLOUD_BRANCH));
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudEnvironmentResolution.js

@@ -0,0 +1,22 @@
+import process from 'node:process';
+function readCloudEnvironmentString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+export function resolveCloudEnvironmentId(task, target, envOverrides) {
+    const metadata = (target.metadata ?? {});
+    const taskMetadata = (task.metadata ?? {});
+    const taskCloud = (taskMetadata.cloud ?? null);
+    const candidates = [
+        readCloudEnvironmentString(metadata.cloudEnvId),
+        readCloudEnvironmentString(metadata.cloud_env_id),
+        readCloudEnvironmentString(metadata.envId),
+        readCloudEnvironmentString(metadata.environmentId),
+        readCloudEnvironmentString(taskCloud?.envId),
+        readCloudEnvironmentString(taskCloud?.environmentId),
+        readCloudEnvironmentString(taskMetadata.cloudEnvId),
+        readCloudEnvironmentString(taskMetadata.cloud_env_id),
+        readCloudEnvironmentString(envOverrides?.CODEX_CLOUD_ENV_ID),
+        readCloudEnvironmentString(process.env.CODEX_CLOUD_ENV_ID)
+    ];
+    return candidates.find((candidate) => candidate !== null) ?? null;
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudExecutionLifecycleShell.js

@@ -0,0 +1,39 @@
+import process from 'node:process';
+import { executeOrchestratorCloudTarget } from './orchestratorCloudTargetExecutor.js';
+import { runOrchestratorExecutionLifecycle } from './orchestratorExecutionLifecycle.js';
+export async function runOrchestratorCloudExecutionLifecycleShell(options) {
+    const { env, pipeline, manifest, paths, runEvents, target, task, envOverrides } = options;
+    return runOrchestratorExecutionLifecycle({
+        env,
+        pipeline,
+        manifest,
+        paths,
+        mode: options.mode,
+        target,
+        task,
+        runEvents,
+        eventStream: options.eventStream,
+        onEventEntry: options.onEventEntry,
+        persister: options.persister,
+        envOverrides,
+        advancedDecisionEnv: { ...process.env, ...(envOverrides ?? {}) },
+        defaultFailureStatusDetail: 'cloud-execution-failed',
+        runAutoScout: options.runAutoScout,
+        executeBody: async ({ notes, controlWatcher, schedulePersist }) => {
+            const cloudResult = await executeOrchestratorCloudTarget({
+                env,
+                pipeline,
+                manifest,
+                paths,
+                target,
+                task,
+                envOverrides,
+                runEvents,
+                controlWatcher,
+                schedulePersist
+            });
+            notes.push(...cloudResult.notes);
+            return cloudResult.success;
+        }
+    });
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudPromptBuilder.js

@@ -0,0 +1,37 @@
+import { buildRunMemoryPromptLines, selectRunMemoryForRole } from '../run/runMemoryController.js';
+import { readPromptPackIdFromTaskMemoryRefId, readSelectedMemoryRefs, TASK_MEMORY_SOURCE0_REF_ID } from './plannerMemory.js';
+export function buildCloudPrompt(params) {
+    const lines = [
+        `Task ID: ${params.task.id}`,
+        `Task title: ${params.task.title}`,
+        params.task.description ? `Task description: ${params.task.description}` : null,
+        `Pipeline: ${params.pipeline.id}`,
+        `Target stage: ${params.stage.id} (${params.target.description})`,
+        '',
+        'Apply the required repository changes for this target stage and produce a diff.'
+    ].filter((line) => Boolean(line));
+    const selectedMemoryRefs = readSelectedMemoryRefs(params.target);
+    const includeSource0 = selectedMemoryRefs.length === 0 || selectedMemoryRefs.includes(TASK_MEMORY_SOURCE0_REF_ID);
+    const preferredPromptPackIds = selectedMemoryRefs
+        .map((refId) => readPromptPackIdFromTaskMemoryRefId(refId))
+        .filter((packId) => packId !== null);
+    const runMemoryPromptLines = buildRunMemoryPromptLines(selectRunMemoryForRole({
+        role: 'executor',
+        manifest: params.manifest,
+        hints: [
+            params.pipeline.id,
+            params.pipeline.title,
+            ...(params.pipeline.tags ?? []),
+            params.target.id,
+            params.target.description ?? '',
+            params.stage.id,
+            params.stage.title
+        ],
+        include_source_0: includeSource0,
+        preferred_prompt_pack_ids: preferredPromptPackIds
+    }));
+    if (runMemoryPromptLines.length > 0) {
+        lines.push('', ...runMemoryPromptLines);
+    }
+    return lines.join('\n');
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudRouteFallbackContract.js

@@ -0,0 +1,45 @@
+import process from 'node:process';
+import { isoTimestamp } from '../utils/time.js';
+function readCloudString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function normalizeCloudFallbackIssues(issues) {
+    return issues.map((issue) => ({ code: issue.code, message: issue.message }));
+}
+export function allowCloudFallback(envOverrides) {
+    const raw = readCloudString(envOverrides?.CODEX_ORCHESTRATOR_CLOUD_FALLBACK) ??
+        readCloudString(process.env.CODEX_ORCHESTRATOR_CLOUD_FALLBACK);
+    if (!raw) {
+        return true;
+    }
+    const normalized = raw.toLowerCase();
+    return !['0', 'false', 'off', 'deny', 'disabled', 'never', 'strict'].includes(normalized);
+}
+export function buildCloudPreflightFailureContract(input, issues) {
+    const issueSummary = issues.map((issue) => issue.message).join(' ');
+    if (!allowCloudFallback(input.envOverrides)) {
+        return {
+            outcome: 'fail',
+            detail: `Cloud preflight failed and cloud fallback is disabled. ${issueSummary}`
+        };
+    }
+    const detail = `Cloud preflight failed; falling back to mcp. ${issueSummary}`;
+    return {
+        outcome: 'fallback',
+        detail,
+        manifestFallback: {
+            mode_requested: 'cloud',
+            mode_used: 'mcp',
+            reason: detail,
+            issues: normalizeCloudFallbackIssues(issues),
+            checked_at: isoTimestamp()
+        },
+        reroute: {
+            mode: 'mcp',
+            executionModeOverride: 'mcp',
+            runtimeModeRequested: input.runtimeModeRequested,
+            runtimeModeSource: input.runtimeModeSource,
+            envOverrides: input.envOverrides
+        }
+    };
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudRouteShell.js

@@ -0,0 +1,36 @@
+import { logger } from '../../logger.js';
+import { appendSummary } from '../run/manifest.js';
+import { buildCloudPreflightRequest, runCloudPreflight } from '../utils/cloudPreflight.js';
+import { resolveCloudBranch } from './orchestratorCloudBranchResolution.js';
+import { resolveCloudEnvironmentId } from './orchestratorCloudEnvironmentResolution.js';
+import { buildCloudPreflightFailureContract } from './orchestratorCloudRouteFallbackContract.js';
+function buildExecutionRouteCloudPreflightRequest(options) {
+    const environmentId = resolveCloudEnvironmentId(options.task, options.target, options.state.effectiveEnvOverrides);
+    const branch = resolveCloudBranch(options.state.effectiveEnvOverrides);
+    return buildCloudPreflightRequest({
+        repoRoot: options.repoRoot,
+        environmentId,
+        branch,
+        env: options.state.effectiveMergedEnv
+    });
+}
+export async function executeOrchestratorCloudRouteShell(options) {
+    const preflight = await runCloudPreflight(buildExecutionRouteCloudPreflightRequest(options));
+    if (!preflight.ok) {
+        const contract = buildCloudPreflightFailureContract({
+            runtimeModeRequested: options.state.runtimeSelection.selected_mode,
+            runtimeModeSource: options.state.runtimeSelection.source,
+            envOverrides: options.state.effectiveEnvOverrides
+        }, preflight.issues);
+        if (contract.outcome === 'fail') {
+            return options.failExecutionRoute('cloud-preflight-failed', contract.detail);
+        }
+        options.manifest.cloud_fallback = contract.manifestFallback;
+        appendSummary(options.manifest, contract.detail);
+        logger.warn(contract.detail);
+        const fallback = await options.reroute(contract.reroute);
+        fallback.notes.unshift(contract.detail);
+        return fallback;
+    }
+    return await options.executeCloudPipeline(options.state.effectiveEnvOverrides);
+}

package/dist/orchestrator/src/cli/services/orchestratorCloudTargetExecutor.js

@@ -0,0 +1,277 @@
+import process from 'node:process';
+import { appendSummary } from '../run/manifest.js';
+import { isoTimestamp } from '../utils/time.js';
+import { resolveCodexCliBin } from '../utils/codexCli.js';
+import { resolveCloudBranch } from './orchestratorCloudBranchResolution.js';
+import { resolveCloudEnvironmentId } from './orchestratorCloudEnvironmentResolution.js';
+import { buildCloudPrompt } from './orchestratorCloudPromptBuilder.js';
+import { CodexCloudTaskExecutor } from '../../cloud/CodexCloudTaskExecutor.js';
+const DEFAULT_CLOUD_POLL_INTERVAL_SECONDS = 10;
+const DEFAULT_CLOUD_TIMEOUT_SECONDS = 1800;
+const DEFAULT_CLOUD_ATTEMPTS = 1;
+const DEFAULT_CLOUD_STATUS_RETRY_LIMIT = 12;
+const DEFAULT_CLOUD_STATUS_RETRY_BACKOFF_MS = 1500;
+function readCloudString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function readCloudNumber(raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return parsed;
+}
+function readCloudFeatureList(raw) {
+    if (!raw) {
+        return [];
+    }
+    const seen = new Set();
+    const features = [];
+    for (const token of raw.split(/[,\s]+/u)) {
+        const feature = token.trim();
+        if (!feature || seen.has(feature)) {
+            continue;
+        }
+        seen.add(feature);
+        features.push(feature);
+    }
+    return features;
+}
+function resolveCloudTargetStage(params) {
+    const metadataStageId = typeof params.target.metadata?.stageId === 'string' ? params.target.metadata.stageId : null;
+    let targetStageId = null;
+    if (metadataStageId && params.pipeline.stages.some((stage) => stage.id === metadataStageId)) {
+        targetStageId = metadataStageId;
+    }
+    else if (params.target.id.includes(':')) {
+        const suffix = params.target.id.split(':').pop() ?? null;
+        if (suffix && params.pipeline.stages.some((stage) => stage.id === suffix)) {
+            targetStageId = suffix;
+        }
+    }
+    else if (params.pipeline.stages.some((stage) => stage.id === params.target.id)) {
+        targetStageId = params.target.id;
+    }
+    const targetStage = targetStageId
+        ? params.pipeline.stages.find((stage) => stage.id === targetStageId)
+        : undefined;
+    const targetEntry = targetStageId
+        ? params.manifest.commands.find((command) => command.id === targetStageId)
+        : undefined;
+    return { targetStageId, targetStage, targetEntry };
+}
+async function prepareCloudTargetPreflight(params) {
+    const notes = [];
+    const { targetStageId, targetStage, targetEntry } = resolveCloudTargetStage({
+        target: params.target,
+        pipeline: params.pipeline,
+        manifest: params.manifest
+    });
+    await params.controlWatcher.sync();
+    await params.controlWatcher.waitForResume();
+    if (params.controlWatcher.isCanceled()) {
+        params.manifest.status_detail = 'run-canceled';
+        return { success: false, notes };
+    }
+    if (!targetStageId || !targetStage || targetStage.kind !== 'command' || !targetEntry) {
+        const detail = targetStageId
+            ? `Cloud execution target "${targetStageId}" could not be resolved to a command stage.`
+            : `Cloud execution target "${params.target.id}" could not be resolved.`;
+        params.manifest.status_detail = 'cloud-target-missing';
+        appendSummary(params.manifest, detail);
+        notes.push(detail);
+        return { success: false, notes };
+    }
+    for (let i = 0; i < params.manifest.commands.length; i += 1) {
+        const entry = params.manifest.commands[i];
+        if (!entry || entry.id === targetStageId) {
+            continue;
+        }
+        entry.status = 'skipped';
+        entry.started_at = entry.started_at ?? isoTimestamp();
+        entry.completed_at = isoTimestamp();
+        entry.summary = `Skipped in cloud mode (target stage: ${targetStageId}).`;
+    }
+    return {
+        success: true,
+        targetStage,
+        targetEntry
+    };
+}
+function buildCloudTaskExecutorRequest(params) {
+    const prompt = buildCloudPrompt({
+        task: params.task,
+        target: params.target,
+        pipeline: params.pipeline,
+        stage: params.stage,
+        manifest: params.manifest
+    });
+    const pollIntervalSeconds = readCloudNumber(params.envOverrides?.CODEX_CLOUD_POLL_INTERVAL_SECONDS ?? process.env.CODEX_CLOUD_POLL_INTERVAL_SECONDS, DEFAULT_CLOUD_POLL_INTERVAL_SECONDS);
+    const timeoutSeconds = readCloudNumber(params.envOverrides?.CODEX_CLOUD_TIMEOUT_SECONDS ?? process.env.CODEX_CLOUD_TIMEOUT_SECONDS, DEFAULT_CLOUD_TIMEOUT_SECONDS);
+    const attempts = readCloudNumber(params.envOverrides?.CODEX_CLOUD_EXEC_ATTEMPTS ?? process.env.CODEX_CLOUD_EXEC_ATTEMPTS, DEFAULT_CLOUD_ATTEMPTS);
+    const statusRetryLimit = readCloudNumber(params.envOverrides?.CODEX_CLOUD_STATUS_RETRY_LIMIT ?? process.env.CODEX_CLOUD_STATUS_RETRY_LIMIT, DEFAULT_CLOUD_STATUS_RETRY_LIMIT);
+    const statusRetryBackoffMs = readCloudNumber(params.envOverrides?.CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS ?? process.env.CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS, DEFAULT_CLOUD_STATUS_RETRY_BACKOFF_MS);
+    const branch = resolveCloudBranch(params.envOverrides);
+    const enableFeatures = readCloudFeatureList(readCloudString(params.envOverrides?.CODEX_CLOUD_ENABLE_FEATURES) ??
+        readCloudString(process.env.CODEX_CLOUD_ENABLE_FEATURES));
+    const disableFeatures = readCloudFeatureList(readCloudString(params.envOverrides?.CODEX_CLOUD_DISABLE_FEATURES) ??
+        readCloudString(process.env.CODEX_CLOUD_DISABLE_FEATURES));
+    const codexBin = resolveCodexCliBin({ ...process.env, ...(params.envOverrides ?? {}) });
+    const cloudEnvOverrides = {
+        ...(params.envOverrides ?? {}),
+        CODEX_NON_INTERACTIVE: readCloudString(params.envOverrides?.CODEX_NON_INTERACTIVE) ??
+            readCloudString(process.env.CODEX_NON_INTERACTIVE) ??
+            '1',
+        CODEX_NO_INTERACTIVE: readCloudString(params.envOverrides?.CODEX_NO_INTERACTIVE) ??
+            readCloudString(process.env.CODEX_NO_INTERACTIVE) ??
+            '1',
+        CODEX_INTERACTIVE: readCloudString(params.envOverrides?.CODEX_INTERACTIVE) ??
+            readCloudString(process.env.CODEX_INTERACTIVE) ??
+            '0'
+    };
+    return {
+        codexBin,
+        prompt,
+        environmentId: params.environmentId,
+        repoRoot: params.env.repoRoot,
+        runDir: params.runDir,
+        pollIntervalSeconds,
+        timeoutSeconds,
+        attempts,
+        statusRetryLimit,
+        statusRetryBackoffMs,
+        branch,
+        enableFeatures,
+        disableFeatures,
+        env: cloudEnvOverrides
+    };
+}
+function applyMissingCloudEnvironmentFailure(params) {
+    const detail = 'Cloud execution requested but no environment id is configured. Set CODEX_CLOUD_ENV_ID or provide target metadata.cloudEnvId.';
+    params.manifest.status_detail = 'cloud-env-missing';
+    params.manifest.cloud_execution = {
+        task_id: null,
+        environment_id: null,
+        status: 'failed',
+        status_url: null,
+        submitted_at: null,
+        completed_at: isoTimestamp(),
+        last_polled_at: null,
+        poll_count: 0,
+        poll_interval_seconds: DEFAULT_CLOUD_POLL_INTERVAL_SECONDS,
+        timeout_seconds: DEFAULT_CLOUD_TIMEOUT_SECONDS,
+        attempts: DEFAULT_CLOUD_ATTEMPTS,
+        diff_path: null,
+        diff_url: null,
+        diff_status: 'unavailable',
+        apply_status: 'not_requested',
+        log_path: null,
+        error: detail
+    };
+    appendSummary(params.manifest, detail);
+    params.notes.push(detail);
+    params.targetEntry.status = 'failed';
+    params.targetEntry.started_at = params.targetEntry.started_at ?? isoTimestamp();
+    params.targetEntry.completed_at = isoTimestamp();
+    params.targetEntry.exit_code = 1;
+    params.targetEntry.summary = detail;
+}
+async function startCloudTargetAndBuildUpdateHandler(params) {
+    params.targetEntry.status = 'running';
+    params.targetEntry.started_at = isoTimestamp();
+    await params.schedulePersist({ manifest: true, force: true });
+    params.runEvents?.stageStarted({
+        stageId: params.targetStage.id,
+        stageIndex: params.targetEntry.index,
+        title: params.targetStage.title,
+        kind: 'command',
+        logPath: params.targetEntry.log_path,
+        status: params.targetEntry.status
+    });
+    return async (cloudExecution) => {
+        params.manifest.cloud_execution = cloudExecution;
+        params.targetEntry.log_path = cloudExecution.log_path;
+        await params.schedulePersist({ manifest: true, force: true });
+    };
+}
+async function applyCloudTargetCompletion(params) {
+    params.manifest.cloud_execution = params.cloudResult.cloudExecution;
+    params.targetEntry.log_path = params.cloudResult.cloudExecution.log_path;
+    params.targetEntry.completed_at = isoTimestamp();
+    params.targetEntry.exit_code = params.cloudResult.success ? 0 : 1;
+    params.targetEntry.status = params.cloudResult.success ? 'succeeded' : 'failed';
+    params.targetEntry.summary = params.cloudResult.summary;
+    if (!params.cloudResult.success) {
+        params.manifest.status_detail = `cloud:${params.targetStage.id}:failed`;
+        appendSummary(params.manifest, params.cloudResult.summary);
+    }
+    await params.schedulePersist({ manifest: true, force: true });
+    params.runEvents?.stageCompleted({
+        stageId: params.targetStage.id,
+        stageIndex: params.targetEntry.index,
+        title: params.targetStage.title,
+        kind: 'command',
+        status: params.targetEntry.status,
+        exitCode: params.targetEntry.exit_code,
+        summary: params.targetEntry.summary,
+        logPath: params.targetEntry.log_path
+    });
+}
+export async function executeOrchestratorCloudTarget(options) {
+    const notes = [];
+    let success = true;
+    const { manifest, pipeline, target, task, runEvents, controlWatcher, schedulePersist } = options;
+    const preflight = await prepareCloudTargetPreflight({
+        manifest,
+        pipeline,
+        target,
+        controlWatcher
+    });
+    if (!preflight.success) {
+        return preflight;
+    }
+    const { targetStage, targetEntry } = preflight;
+    const environmentId = resolveCloudEnvironmentId(task, target, options.envOverrides);
+    if (!environmentId) {
+        success = false;
+        applyMissingCloudEnvironmentFailure({ manifest, notes, targetEntry });
+        return { success, notes };
+    }
+    const onUpdate = await startCloudTargetAndBuildUpdateHandler({
+        manifest,
+        targetStage,
+        targetEntry,
+        schedulePersist,
+        runEvents
+    });
+    const request = buildCloudTaskExecutorRequest({
+        env: options.env,
+        runDir: options.paths.runDir,
+        task,
+        target,
+        pipeline,
+        stage: targetStage,
+        manifest,
+        environmentId,
+        envOverrides: options.envOverrides
+    });
+    const executor = new CodexCloudTaskExecutor();
+    const cloudResult = await executor.execute({
+        ...request,
+        onUpdate
+    });
+    success = cloudResult.success;
+    notes.push(...cloudResult.notes);
+    await applyCloudTargetCompletion({
+        manifest,
+        targetStage,
+        targetEntry,
+        cloudResult,
+        schedulePersist,
+        runEvents
+    });
+    return { success, notes };
+}