@kbediako/codex-orchestrator 0.1.13 → 0.1.14-alpha.1

package/README.md

@@ -59,6 +59,11 @@ Use this when you want Codex to drive work inside another repo with the CO defau
    ```bash
    codex-orchestrator codex setup
    ```
+4. Optional (fast refresh helper for downstream users):
+   ```bash
+   scripts/codex-cli-refresh.sh --repo /path/to/codex
+   ```
+   Repo-only helper (not included in npm package). Set `CODEX_REPO` or `CODEX_CLI_SOURCE` to avoid passing `--repo` each time.
 
 ## Delegation MCP server
 

package/dist/bin/codex-orchestrator.js

@@ -140,6 +140,24 @@ function readStringFlag(flags, key) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function resolveExecutionModeFlag(flags) {
+    const cloudShortcut = flags['cloud'] === true;
+    const rawMode = readStringFlag(flags, 'execution-mode');
+    if (cloudShortcut) {
+        if (rawMode && rawMode.toLowerCase() !== 'cloud') {
+            throw new Error('Cannot combine --cloud with --execution-mode values other than cloud.');
+        }
+        return 'cloud';
+    }
+    if (!rawMode) {
+        return undefined;
+    }
+    const normalized = rawMode.toLowerCase();
+    if (normalized !== 'mcp' && normalized !== 'cloud') {
+        throw new Error('Invalid --execution-mode value. Expected one of: mcp, cloud.');
+    }
+    return normalized;
+}
 function applyRlmEnvOverrides(flags, goal) {
     if (goal) {
         process.env.RLM_GOAL = goal;
@@ -202,6 +220,7 @@ async function handleStart(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
+    const executionMode = resolveExecutionModeFlag(flags);
     if (pipelineId === 'rlm') {
         const goal = readStringFlag(flags, 'goal');
         applyRlmEnvOverrides(flags, goal);
@@ -221,6 +240,7 @@ async function handleStart(orchestrator, rawArgs) {
             parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
             approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
             targetStageId: resolveTargetStageId(flags),
+            executionMode,
             runEvents
         });
         emitRunOutput(result, format, 'Run started');
@@ -746,6 +766,8 @@ Commands:
     --parent-run <id>       Link run to parent run id.
     --approval-policy <p>   Record approval policy metadata.
     --format json           Emit machine-readable output.
+    --execution-mode <mcp|cloud>  Force execution mode for this run and child subpipelines.
+    --cloud                 Shortcut for --execution-mode cloud.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
     --goal "<goal>"         When pipeline is rlm, set the RLM goal.
     --validator <cmd|none>  When pipeline is rlm, set the validator command.

package/dist/orchestrator/src/cli/adapters/CommandBuilder.js

@@ -4,17 +4,41 @@ export class CommandBuilder {
         this.executePipeline = executePipeline;
     }
     async build(input) {
-        const result = await this.executePipeline();
+        const result = await this.executePipeline(input);
         return {
             subtaskId: input.target.id,
             artifacts: [
                 { path: result.manifestPath, description: 'CLI run manifest' },
-                { path: result.logPath, description: 'Runner log (ndjson)' }
+                { path: result.logPath, description: 'Runner log (ndjson)' },
+                ...(result.manifest.cloud_execution?.diff_path
+                    ? [{ path: result.manifest.cloud_execution.diff_path, description: 'Cloud diff artifact' }]
+                    : [])
             ],
             mode: input.mode,
             runId: input.runId,
             success: result.success,
-            notes: result.notes.join('\n') || undefined
+            notes: result.notes.join('\n') || undefined,
+            cloudExecution: result.manifest.cloud_execution
+                ? {
+                    taskId: result.manifest.cloud_execution.task_id,
+                    environmentId: result.manifest.cloud_execution.environment_id,
+                    status: result.manifest.cloud_execution.status,
+                    statusUrl: result.manifest.cloud_execution.status_url,
+                    submittedAt: result.manifest.cloud_execution.submitted_at,
+                    completedAt: result.manifest.cloud_execution.completed_at,
+                    lastPolledAt: result.manifest.cloud_execution.last_polled_at,
+                    pollCount: result.manifest.cloud_execution.poll_count,
+                    pollIntervalSeconds: result.manifest.cloud_execution.poll_interval_seconds,
+                    timeoutSeconds: result.manifest.cloud_execution.timeout_seconds,
+                    attempts: result.manifest.cloud_execution.attempts,
+                    diffPath: result.manifest.cloud_execution.diff_path,
+                    diffUrl: result.manifest.cloud_execution.diff_url,
+                    diffStatus: result.manifest.cloud_execution.diff_status,
+                    applyStatus: result.manifest.cloud_execution.apply_status,
+                    logPath: result.manifest.cloud_execution.log_path,
+                    error: result.manifest.cloud_execution.error
+                }
+                : null
         };
     }
 }

package/dist/orchestrator/src/cli/adapters/CommandPlanner.js

@@ -43,6 +43,9 @@ export class CommandPlanner {
         if (stagePlanHints.executionMode) {
             metadata.executionMode = stagePlanHints.executionMode;
         }
+        if (stagePlanHints.cloudEnvId) {
+            metadata.cloudEnvId = stagePlanHints.cloudEnvId;
+        }
         metadata.requiresCloud = requiresCloud;
         return {
             id: `${this.pipeline.id}:${stage.id}`,
@@ -117,12 +120,25 @@ function extractStagePlanHints(stage) {
     const executionMode = typeof rawExecutionMode === 'string'
         ? rawExecutionMode.trim().toLowerCase() || null
         : null;
+    const rawCloudEnvId = typeof planConfig.cloudEnvId === 'string'
+        ? planConfig.cloudEnvId
+        : typeof planConfig.cloud_env_id === 'string'
+            ? planConfig.cloud_env_id
+            : typeof stageRecord.cloudEnvId === 'string'
+                ? stageRecord.cloudEnvId
+                : typeof stageRecord.cloud_env_id === 'string'
+                    ? stageRecord.cloud_env_id
+                    : undefined;
+    const cloudEnvId = typeof rawCloudEnvId === 'string'
+        ? rawCloudEnvId.trim() || null
+        : null;
     return {
         runnable: planConfig.runnable,
         defaultTarget,
         aliases,
         requiresCloud,
-        executionMode
+        executionMode,
+        cloudEnvId
     };
 }
 function resolveStageRequiresCloud(stage, hints) {

package/dist/orchestrator/src/cli/adapters/CommandReviewer.js

@@ -1,11 +1,46 @@
+import { diagnoseCloudFailure } from './cloudFailureDiagnostics.js';
 export class CommandReviewer {
     getResult;
     constructor(getResult) {
         this.getResult = getResult;
     }
     async review(input) {
-        void input;
         const result = this.requireResult();
+        if (input.mode === 'cloud') {
+            const cloudExecution = result.manifest.cloud_execution;
+            const status = cloudExecution?.status ?? 'unknown';
+            const cloudTask = cloudExecution?.task_id ?? '<unknown>';
+            const approved = status === 'ready' && result.success;
+            const diagnosis = diagnoseCloudFailure({
+                status,
+                statusDetail: result.manifest.status_detail ?? null,
+                error: cloudExecution?.error ?? null
+            });
+            const summaryLines = [
+                approved
+                    ? `Cloud task ${cloudTask} completed successfully.`
+                    : `Cloud task ${cloudTask} did not complete successfully (${status}).`,
+                `Manifest: ${result.manifestPath}`,
+                `Runner log: ${result.logPath}`,
+                ...(cloudExecution?.status_url ? [`Cloud status URL: ${cloudExecution.status_url}`] : [])
+            ];
+            if (!approved) {
+                summaryLines.push(`Failure class: ${diagnosis.category}`);
+                summaryLines.push(`Guidance: ${diagnosis.guidance}`);
+            }
+            const feedbackLines = [cloudExecution?.error ?? (result.notes.join('\n') || undefined)].filter((line) => Boolean(line && line.trim().length > 0));
+            if (!approved) {
+                feedbackLines.push(`Failure class: ${diagnosis.category}`);
+                feedbackLines.push(`Guidance: ${diagnosis.guidance}`);
+            }
+            return {
+                summary: summaryLines.join('\n'),
+                decision: {
+                    approved,
+                    feedback: feedbackLines.length > 0 ? feedbackLines.join('\n') : undefined
+                }
+            };
+        }
         const summaryLines = [
             result.success
                 ? 'Diagnostics pipeline succeeded.'

package/dist/orchestrator/src/cli/adapters/CommandTester.js

@@ -1,4 +1,5 @@
 import { ensureGuardrailStatus } from '../run/manifest.js';
+import { diagnoseCloudFailure } from './cloudFailureDiagnostics.js';
 export class CommandTester {
     getResult;
     constructor(getResult) {
@@ -6,6 +7,33 @@ export class CommandTester {
     }
     async test(input) {
         const result = this.requireResult();
+        if (input.mode === 'cloud') {
+            const cloudExecution = result.manifest.cloud_execution;
+            const status = cloudExecution?.status ?? 'unknown';
+            const passed = status === 'ready' && result.success;
+            const diagnosis = diagnoseCloudFailure({
+                status,
+                statusDetail: result.manifest.status_detail ?? null,
+                error: cloudExecution?.error ?? null
+            });
+            const failureDetails = cloudExecution?.error ??
+                `Cloud task status: ${status}${cloudExecution?.task_id ? ` (${cloudExecution.task_id})` : ''}`;
+            const reports = [
+                {
+                    name: 'cloud-task',
+                    status: passed ? 'passed' : 'failed',
+                    details: passed
+                        ? failureDetails
+                        : `${failureDetails}\nFailure class: ${diagnosis.category}. ${diagnosis.guidance}`
+                }
+            ];
+            return {
+                subtaskId: input.build.subtaskId,
+                success: passed,
+                reports,
+                runId: input.runId
+            };
+        }
         const guardrailStatus = ensureGuardrailStatus(result.manifest);
         const reports = [
             {

package/dist/orchestrator/src/cli/adapters/cloudFailureDiagnostics.js

@@ -0,0 +1,45 @@
+const CLOUD_FAILURE_RULES = [
+    {
+        category: 'configuration',
+        patterns: ['cloud-env-missing', 'codex_cloud_env_id', 'no environment id is configured', '--env'],
+        guidance: 'Set CODEX_CLOUD_ENV_ID (or metadata.cloudEnvId) to a valid cloud environment id before re-running.'
+    },
+    {
+        category: 'credentials',
+        patterns: ['unauthorized', 'forbidden', 'not logged in', 'login', 'api key', 'credential', 'token'],
+        guidance: 'Ensure Codex Cloud credentials are available to the runner and have access to the configured environment.'
+    },
+    {
+        category: 'connectivity',
+        patterns: ['enotfound', 'econn', 'timed out', 'timeout', 'network', '502', '503', '504'],
+        guidance: 'Cloud endpoint connectivity looks unstable; retry and inspect network/endpoint health.'
+    }
+];
+const TERMINAL_FAILURE_STATUSES = new Set(['failed', 'error', 'cancelled']);
+export function diagnoseCloudFailure(options) {
+    const signal = [options.status ?? null, options.statusDetail ?? null, options.error ?? null]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join('\n');
+    const normalized = signal.toLowerCase();
+    for (const rule of CLOUD_FAILURE_RULES) {
+        if (rule.patterns.some((pattern) => normalized.includes(pattern))) {
+            return {
+                category: rule.category,
+                guidance: rule.guidance,
+                signal
+            };
+        }
+    }
+    if (options.status && TERMINAL_FAILURE_STATUSES.has(options.status.toLowerCase())) {
+        return {
+            category: 'execution',
+            guidance: 'Inspect manifest cloud_execution.error and cloud command logs for the terminal cloud failure.',
+            signal
+        };
+    }
+    return {
+        category: 'unknown',
+        guidance: 'Inspect manifest status_detail plus cloud command logs to classify this failure.',
+        signal
+    };
+}

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

@@ -20,7 +20,7 @@ import { PipelineResolver } from './services/pipelineResolver.js';
 import { ControlPlaneService } from './services/controlPlaneService.js';
 import { ControlWatcher } from './control/controlWatcher.js';
 import { SchedulerService } from './services/schedulerService.js';
-import { applyHandlesToRunSummary, applyPrivacyToRunSummary, persistRunSummary } from './services/runSummaryWriter.js';
+import { applyHandlesToRunSummary, applyPrivacyToRunSummary, applyCloudExecutionToRunSummary, persistRunSummary } from './services/runSummaryWriter.js';
 import { prepareRun, resolvePipelineForResume, overrideTaskEnvironment } from './services/runPreparation.js';
 import { loadPackageConfig, loadUserConfig } from './config/userConfig.js';
 import { loadDelegationConfigFiles, computeEffectiveDelegationConfig, parseDelegationConfigOverride, splitDelegationConfigOverrides } from './config/delegationConfig.js';
@@ -28,8 +28,13 @@ import { ControlServer } from './control/controlServer.js';
 import { RunEventEmitter, RunEventPublisher, snapshotStages } from './events/runEvents.js';
 import { RunEventStream, attachRunEventAdapter } from './events/runEventStream.js';
 import { CLI_EXECUTION_MODE_PARSER, resolveRequiresCloudPolicy } from '../utils/executionMode.js';
+import { resolveCodexCliBin } from './utils/codexCli.js';
+import { CodexCloudTaskExecutor } from '../cloud/CodexCloudTaskExecutor.js';
 const resolveBaseEnvironment = () => normalizeEnvironmentPaths(resolveEnvironmentPaths());
 const CONFIG_OVERRIDE_ENV_KEYS = ['CODEX_CONFIG_OVERRIDES', 'CODEX_MCP_CONFIG_OVERRIDES'];
+const DEFAULT_CLOUD_POLL_INTERVAL_SECONDS = 10;
+const DEFAULT_CLOUD_TIMEOUT_SECONDS = 1800;
+const DEFAULT_CLOUD_ATTEMPTS = 1;
 function collectDelegationEnvOverrides(env = process.env) {
     const layers = [];
     for (const key of CONFIG_OVERRIDE_ENV_KEYS) {
@@ -52,6 +57,37 @@ function collectDelegationEnvOverrides(env = process.env) {
     }
     return layers;
 }
+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 resolveCloudEnvironmentId(task, target, envOverrides) {
+    const metadata = (target.metadata ?? {});
+    const taskMetadata = (task.metadata ?? {});
+    const taskCloud = (taskMetadata.cloud ?? null);
+    const candidates = [
+        readCloudString(metadata.cloudEnvId),
+        readCloudString(metadata.cloud_env_id),
+        readCloudString(metadata.envId),
+        readCloudString(metadata.environmentId),
+        readCloudString(taskCloud?.envId),
+        readCloudString(taskCloud?.environmentId),
+        readCloudString(taskMetadata.cloudEnvId),
+        readCloudString(taskMetadata.cloud_env_id),
+        readCloudString(envOverrides?.CODEX_CLOUD_ENV_ID),
+        readCloudString(process.env.CODEX_CLOUD_ENV_ID)
+    ];
+    return candidates.find((candidate) => candidate !== null) ?? null;
+}
 export class CodexOrchestrator {
     baseEnv;
     controlPlane = new ControlPlaneService();
@@ -136,7 +172,8 @@ export class CodexOrchestrator {
                 eventStream: stream,
                 onEventEntry,
                 persister,
-                envOverrides: preparation.envOverrides
+                envOverrides: preparation.envOverrides,
+                executionModeOverride: options.executionMode
             });
         }
         finally {
@@ -360,7 +397,7 @@ export class CodexOrchestrator {
             logPath: params.paths.logPath
         });
     }
-    createTaskManager(runId, pipeline, executePipeline, getResult, plannerInstance, env) {
+    createTaskManager(runId, pipeline, executePipeline, getResult, plannerInstance, env, modeOverride) {
         const planner = plannerInstance ?? new CommandPlanner(pipeline);
         const builder = new CommandBuilder(executePipeline);
         const tester = new CommandTester(getResult);
@@ -373,12 +410,15 @@ export class CodexOrchestrator {
             tester,
             reviewer,
             runIdFactory: () => runId,
-            modePolicy: (task, subtask) => this.determineMode(task, subtask),
+            modePolicy: (task, subtask) => this.determineMode(task, subtask, modeOverride),
             persistence: { autoStart: true, stateStore, manifestWriter }
         };
         return new TaskManager(options);
     }
-    determineMode(task, subtask) {
+    determineMode(task, subtask, overrideMode) {
+        if (overrideMode) {
+            return overrideMode;
+        }
         if (this.requiresCloudExecution(task, subtask)) {
             return 'cloud';
         }
@@ -402,6 +442,9 @@ export class CodexOrchestrator {
         return Boolean(task.metadata?.execution?.parallel);
     }
     async executePipeline(options) {
+        if (options.mode === 'cloud') {
+            return await this.executeCloudPipeline(options);
+        }
         const { env, pipeline, manifest, paths, runEvents, envOverrides } = options;
         const notes = [];
         let success = true;
@@ -513,7 +556,8 @@ export class CodexOrchestrator {
                             taskId: env.taskId,
                             pipelineId: stage.pipeline,
                             parentRunId: manifest.run_id,
-                            format: 'json'
+                            format: 'json',
+                            executionMode: options.executionModeOverride
                         });
                         entry.completed_at = isoTimestamp();
                         entry.sub_run_id = child.manifest.run_id;
@@ -607,31 +651,251 @@ export class CodexOrchestrator {
             logPath: relativeToRepo(env, paths.logPath)
         };
     }
+    async executeCloudPipeline(options) {
+        const { env, pipeline, manifest, paths, runEvents, target, task, envOverrides } = options;
+        const notes = [];
+        let success = true;
+        manifest.guardrail_status = undefined;
+        const persister = options.persister ??
+            new ManifestPersister({
+                manifest,
+                paths,
+                persistIntervalMs: Math.max(1000, manifest.heartbeat_interval_seconds * 1000)
+            });
+        const schedulePersist = (persistOptions = {}) => persister.schedule(persistOptions);
+        const pushHeartbeat = (forceManifest = false) => {
+            updateHeartbeat(manifest);
+            return schedulePersist({ manifest: forceManifest, heartbeat: true, force: forceManifest });
+        };
+        const controlWatcher = new ControlWatcher({
+            paths,
+            manifest,
+            eventStream: options.eventStream,
+            onEntry: options.onEventEntry,
+            persist: () => schedulePersist({ manifest: true, force: true })
+        });
+        manifest.status = 'in_progress';
+        updateHeartbeat(manifest);
+        await schedulePersist({ manifest: true, heartbeat: true, force: true });
+        runEvents?.runStarted(snapshotStages(manifest, pipeline), manifest.status);
+        const heartbeatInterval = setInterval(() => {
+            void pushHeartbeat(false).catch((error) => {
+                logger.warn(`Heartbeat update failed for run ${manifest.run_id}: ${error?.message ?? String(error)}`);
+            });
+        }, manifest.heartbeat_interval_seconds * 1000);
+        const targetStageId = this.resolveTargetStageId(target, pipeline);
+        const targetStage = targetStageId
+            ? pipeline.stages.find((stage) => stage.id === targetStageId)
+            : undefined;
+        const targetEntry = targetStageId
+            ? manifest.commands.find((command) => command.id === targetStageId)
+            : undefined;
+        try {
+            await controlWatcher.sync();
+            await controlWatcher.waitForResume();
+            if (controlWatcher.isCanceled()) {
+                manifest.status_detail = 'run-canceled';
+                success = false;
+            }
+            else if (!targetStage || targetStage.kind !== 'command' || !targetEntry) {
+                success = false;
+                manifest.status_detail = 'cloud-target-missing';
+                const detail = targetStageId
+                    ? `Cloud execution target "${targetStageId}" could not be resolved to a command stage.`
+                    : `Cloud execution target "${target.id}" could not be resolved.`;
+                appendSummary(manifest, detail);
+                notes.push(detail);
+            }
+            else {
+                for (let i = 0; i < manifest.commands.length; i += 1) {
+                    const entry = 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}).`;
+                }
+                const environmentId = resolveCloudEnvironmentId(task, target, envOverrides);
+                if (!environmentId) {
+                    success = false;
+                    manifest.status_detail = 'cloud-env-missing';
+                    const detail = 'Cloud execution requested but no environment id is configured. Set CODEX_CLOUD_ENV_ID or provide target metadata.cloudEnvId.';
+                    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(manifest, detail);
+                    notes.push(detail);
+                    targetEntry.status = 'failed';
+                    targetEntry.started_at = targetEntry.started_at ?? isoTimestamp();
+                    targetEntry.completed_at = isoTimestamp();
+                    targetEntry.exit_code = 1;
+                    targetEntry.summary = detail;
+                }
+                else {
+                    targetEntry.status = 'running';
+                    targetEntry.started_at = isoTimestamp();
+                    await schedulePersist({ manifest: true, force: true });
+                    runEvents?.stageStarted({
+                        stageId: targetStage.id,
+                        stageIndex: targetEntry.index,
+                        title: targetStage.title,
+                        kind: 'command',
+                        logPath: targetEntry.log_path,
+                        status: targetEntry.status
+                    });
+                    const executor = new CodexCloudTaskExecutor();
+                    const prompt = this.buildCloudPrompt(task, target, pipeline, targetStage);
+                    const pollIntervalSeconds = readCloudNumber(envOverrides?.CODEX_CLOUD_POLL_INTERVAL_SECONDS ?? process.env.CODEX_CLOUD_POLL_INTERVAL_SECONDS, DEFAULT_CLOUD_POLL_INTERVAL_SECONDS);
+                    const timeoutSeconds = readCloudNumber(envOverrides?.CODEX_CLOUD_TIMEOUT_SECONDS ?? process.env.CODEX_CLOUD_TIMEOUT_SECONDS, DEFAULT_CLOUD_TIMEOUT_SECONDS);
+                    const attempts = readCloudNumber(envOverrides?.CODEX_CLOUD_EXEC_ATTEMPTS ?? process.env.CODEX_CLOUD_EXEC_ATTEMPTS, DEFAULT_CLOUD_ATTEMPTS);
+                    const branch = readCloudString(envOverrides?.CODEX_CLOUD_BRANCH) ??
+                        readCloudString(process.env.CODEX_CLOUD_BRANCH);
+                    const codexBin = resolveCodexCliBin({ ...process.env, ...(envOverrides ?? {}) });
+                    const cloudResult = await executor.execute({
+                        codexBin,
+                        prompt,
+                        environmentId,
+                        repoRoot: env.repoRoot,
+                        runDir: paths.runDir,
+                        pollIntervalSeconds,
+                        timeoutSeconds,
+                        attempts,
+                        branch,
+                        env: envOverrides
+                    });
+                    success = cloudResult.success;
+                    notes.push(...cloudResult.notes);
+                    manifest.cloud_execution = cloudResult.cloudExecution;
+                    targetEntry.log_path = cloudResult.cloudExecution.log_path;
+                    targetEntry.completed_at = isoTimestamp();
+                    targetEntry.exit_code = cloudResult.success ? 0 : 1;
+                    targetEntry.status = cloudResult.success ? 'succeeded' : 'failed';
+                    targetEntry.summary = cloudResult.summary;
+                    if (!cloudResult.success) {
+                        manifest.status_detail = `cloud:${targetStage.id}:failed`;
+                        appendSummary(manifest, cloudResult.summary);
+                    }
+                    await schedulePersist({ manifest: true, force: true });
+                    runEvents?.stageCompleted({
+                        stageId: targetStage.id,
+                        stageIndex: targetEntry.index,
+                        title: targetStage.title,
+                        kind: 'command',
+                        status: targetEntry.status,
+                        exitCode: targetEntry.exit_code,
+                        summary: targetEntry.summary,
+                        logPath: targetEntry.log_path
+                    });
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeatInterval);
+            await schedulePersist({ force: true });
+        }
+        await controlWatcher.sync();
+        if (controlWatcher.isCanceled()) {
+            finalizeStatus(manifest, 'cancelled', manifest.status_detail ?? 'run-canceled');
+        }
+        else if (success) {
+            finalizeStatus(manifest, 'succeeded');
+        }
+        else {
+            finalizeStatus(manifest, 'failed', manifest.status_detail ?? 'cloud-execution-failed');
+        }
+        updateHeartbeat(manifest);
+        await schedulePersist({ manifest: true, heartbeat: true, force: true }).catch((error) => {
+            logger.warn(`Heartbeat update failed for run ${manifest.run_id}: ${error?.message ?? String(error)}`);
+        });
+        await schedulePersist({ force: true });
+        await appendMetricsEntry(env, paths, manifest, persister);
+        return {
+            success,
+            notes,
+            manifest,
+            manifestPath: relativeToRepo(env, paths.manifestPath),
+            logPath: relativeToRepo(env, paths.logPath)
+        };
+    }
+    resolveTargetStageId(target, pipeline) {
+        const metadataStageId = typeof target.metadata?.stageId === 'string' ? target.metadata.stageId : null;
+        if (metadataStageId && pipeline.stages.some((stage) => stage.id === metadataStageId)) {
+            return metadataStageId;
+        }
+        if (target.id.includes(':')) {
+            const suffix = target.id.split(':').pop() ?? null;
+            if (suffix && pipeline.stages.some((stage) => stage.id === suffix)) {
+                return suffix;
+            }
+        }
+        if (pipeline.stages.some((stage) => stage.id === target.id)) {
+            return target.id;
+        }
+        return null;
+    }
+    buildCloudPrompt(task, target, pipeline, stage) {
+        const lines = [
+            `Task ID: ${task.id}`,
+            `Task title: ${task.title}`,
+            task.description ? `Task description: ${task.description}` : null,
+            `Pipeline: ${pipeline.id}`,
+            `Target stage: ${stage.id} (${target.description})`,
+            '',
+            'Apply the required repository changes for this target stage and produce a diff.'
+        ].filter((line) => Boolean(line));
+        return lines.join('\n');
+    }
     async performRunLifecycle(context) {
-        const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides } = context;
-        let pipelineResult = null;
-        let executing = null;
-        const executePipeline = async () => {
-            if (!executing) {
-                executing = this.executePipeline({
-                    env,
-                    pipeline,
-                    manifest,
-                    paths,
-                    runEvents: context.runEvents,
-                    eventStream: context.eventStream,
-                    onEventEntry: context.onEventEntry,
-                    persister,
-                    envOverrides
-                }).then((result) => {
-                    pipelineResult = result;
-                    return result;
-                });
+        const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides, executionModeOverride } = context;
+        let latestPipelineResult = null;
+        const executingByKey = new Map();
+        const executePipeline = async (input) => {
+            const key = `${input.mode}:${input.target.id}`;
+            const existing = executingByKey.get(key);
+            if (existing) {
+                return existing;
             }
+            const executing = this.executePipeline({
+                env,
+                pipeline,
+                manifest,
+                paths,
+                mode: input.mode,
+                executionModeOverride,
+                target: input.target,
+                task: taskContext,
+                runEvents: context.runEvents,
+                eventStream: context.eventStream,
+                onEventEntry: context.onEventEntry,
+                persister,
+                envOverrides
+            }).then((result) => {
+                latestPipelineResult = result;
+                return result;
+            });
+            executingByKey.set(key, executing);
             return executing;
         };
-        const getResult = () => pipelineResult;
-        const manager = this.createTaskManager(runId, pipeline, executePipeline, getResult, planner, env);
+        const getResult = () => latestPipelineResult;
+        const manager = this.createTaskManager(runId, pipeline, executePipeline, getResult, planner, env, executionModeOverride);
         this.attachPlanTargetTracker(manager, manifest, paths, persister);
         getPrivacyGuard().reset();
         const controlPlaneResult = await this.controlPlane.guard({
@@ -672,6 +936,7 @@ export class CodexOrchestrator {
         this.scheduler.applySchedulerToRunSummary(runSummary, schedulerPlan);
         applyHandlesToRunSummary(runSummary, manifest);
         applyPrivacyToRunSummary(runSummary, manifest);
+        applyCloudExecutionToRunSummary(runSummary, manifest);
         this.controlPlane.applyControlPlaneToRunSummary(runSummary, controlPlaneResult);
         await persistRunSummary(env, paths, manifest, runSummary, persister);
         context.runEvents?.runCompleted({
@@ -722,7 +987,8 @@ export class CodexOrchestrator {
             log_path: manifest.log_path,
             heartbeat_at: manifest.heartbeat_at,
             commands: manifest.commands,
-            child_runs: manifest.child_runs
+            child_runs: manifest.child_runs,
+            cloud_execution: manifest.cloud_execution ?? null
         };
     }
     renderStatus(manifest) {
@@ -731,6 +997,10 @@ export class CodexOrchestrator {
         logger.info(`Started: ${manifest.started_at}`);
         logger.info(`Completed: ${manifest.completed_at ?? 'in-progress'}`);
         logger.info(`Manifest: ${manifest.artifact_root}/manifest.json`);
+        if (manifest.cloud_execution?.task_id) {
+            logger.info(`Cloud: ${manifest.cloud_execution.task_id} [${manifest.cloud_execution.status}]` +
+                (manifest.cloud_execution.status_url ? ` ${manifest.cloud_execution.status_url}` : ''));
+        }
         logger.info('Commands:');
         for (const command of manifest.commands) {
             const summary = command.summary ? ` — ${command.summary}` : '';

package/dist/orchestrator/src/cli/run/manifest.js

@@ -55,6 +55,7 @@ export async function bootstrapManifest(runId, options) {
         instructions_sources: [],
         prompt_packs: [],
         guardrails_required: pipeline.guardrailsRequired !== false,
+        cloud_execution: null,
         learning: {
             validation: {
                 mode: 'per-task',
@@ -170,6 +171,7 @@ export function resetForResume(manifest) {
     manifest.status = 'in_progress';
     manifest.status_detail = 'resuming';
     manifest.guardrail_status = undefined;
+    manifest.cloud_execution = null;
 }
 export function recordResumeEvent(manifest, event) {
     manifest.resume_events.push({ ...event, timestamp: isoTimestamp() });

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

@@ -27,6 +27,30 @@ export function applyPrivacyToRunSummary(runSummary, manifest) {
         allowedFrames: manifest.privacy.totals.allowed_frames
     };
 }
+export function applyCloudExecutionToRunSummary(runSummary, manifest) {
+    if (!manifest.cloud_execution) {
+        return;
+    }
+    runSummary.cloudExecution = {
+        taskId: manifest.cloud_execution.task_id,
+        environmentId: manifest.cloud_execution.environment_id,
+        status: manifest.cloud_execution.status,
+        statusUrl: manifest.cloud_execution.status_url,
+        submittedAt: manifest.cloud_execution.submitted_at,
+        completedAt: manifest.cloud_execution.completed_at,
+        lastPolledAt: manifest.cloud_execution.last_polled_at,
+        pollCount: manifest.cloud_execution.poll_count,
+        pollIntervalSeconds: manifest.cloud_execution.poll_interval_seconds,
+        timeoutSeconds: manifest.cloud_execution.timeout_seconds,
+        attempts: manifest.cloud_execution.attempts,
+        diffPath: manifest.cloud_execution.diff_path,
+        diffUrl: manifest.cloud_execution.diff_url,
+        diffStatus: manifest.cloud_execution.diff_status,
+        applyStatus: manifest.cloud_execution.apply_status,
+        logPath: manifest.cloud_execution.log_path,
+        error: manifest.cloud_execution.error
+    };
+}
 export async function persistRunSummary(env, paths, manifest, runSummary, persister) {
     const summaryPath = join(paths.runDir, 'run-summary.json');
     await writeJsonAtomic(summaryPath, runSummary);

package/dist/orchestrator/src/cloud/CodexCloudTaskExecutor.js

@@ -0,0 +1,255 @@
+import { spawn } from 'node:child_process';
+import { appendFile, mkdir, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isoTimestamp } from '../cli/utils/time.js';
+const TASK_ID_PATTERN = /\btask_[a-z]_[a-f0-9]+\b/i;
+const MAX_LOG_CHARS = 32 * 1024;
+const STATUS_RETRY_LIMIT = 3;
+const STATUS_RETRY_BACKOFF_MS = 1500;
+const DEFAULT_LIST_LIMIT = 20;
+export function extractCloudTaskId(text) {
+    const match = TASK_ID_PATTERN.exec(text);
+    if (!match?.[0]) {
+        return null;
+    }
+    return match[0];
+}
+export function parseCloudStatusToken(text) {
+    const match = /^\s*\[([A-Z_]+)\]/m.exec(text);
+    if (!match?.[1]) {
+        return null;
+    }
+    return match[1].toUpperCase();
+}
+export function mapCloudStatusToken(token) {
+    if (!token) {
+        return 'unknown';
+    }
+    switch (token) {
+        case 'READY':
+        case 'COMPLETED':
+        case 'SUCCEEDED':
+            return 'ready';
+        case 'RUNNING':
+        case 'IN_PROGRESS':
+            return 'running';
+        case 'QUEUED':
+        case 'PENDING':
+            return 'queued';
+        case 'ERROR':
+            return 'error';
+        case 'FAILED':
+            return 'failed';
+        case 'CANCELLED':
+        case 'CANCELED':
+            return 'cancelled';
+        default:
+            return 'unknown';
+    }
+}
+export class CodexCloudTaskExecutor {
+    commandRunner;
+    now;
+    sleepFn;
+    constructor(options = {}) {
+        this.commandRunner = options.commandRunner ?? defaultCloudCommandRunner;
+        this.now = options.now ?? isoTimestamp;
+        this.sleepFn = options.sleepFn ?? sleep;
+    }
+    async execute(input) {
+        const cloudDir = join(input.runDir, 'cloud');
+        await mkdir(cloudDir, { recursive: true });
+        const commandLogPath = join(cloudDir, 'commands.ndjson');
+        const env = { ...process.env, ...(input.env ?? {}) };
+        const notes = [];
+        const cloudExecution = {
+            task_id: null,
+            environment_id: input.environmentId,
+            status: 'queued',
+            status_url: null,
+            submitted_at: null,
+            completed_at: null,
+            last_polled_at: null,
+            poll_count: 0,
+            poll_interval_seconds: Math.max(1, input.pollIntervalSeconds),
+            timeout_seconds: Math.max(1, input.timeoutSeconds),
+            attempts: Math.max(1, input.attempts),
+            diff_path: null,
+            diff_url: null,
+            diff_status: 'pending',
+            apply_status: 'not_requested',
+            log_path: relative(input.repoRoot, commandLogPath),
+            error: null
+        };
+        const runCloudCommand = async (args) => {
+            const result = await this.commandRunner({
+                command: input.codexBin,
+                args,
+                cwd: input.repoRoot,
+                env
+            });
+            await appendFile(commandLogPath, `${JSON.stringify({
+                timestamp: this.now(),
+                command: input.codexBin,
+                args,
+                exit_code: result.exitCode,
+                stdout: truncate(result.stdout),
+                stderr: truncate(result.stderr)
+            })}\n`, 'utf8');
+            return result;
+        };
+        try {
+            const execArgs = ['cloud', 'exec', '--env', input.environmentId, '--attempts', String(cloudExecution.attempts)];
+            if (input.branch && input.branch.trim()) {
+                execArgs.push('--branch', input.branch.trim());
+            }
+            execArgs.push(input.prompt);
+            const execResult = await runCloudCommand(execArgs);
+            if (execResult.exitCode !== 0) {
+                throw new Error(`codex cloud exec failed with exit ${execResult.exitCode}: ${compactError(execResult.stderr, execResult.stdout)}`);
+            }
+            const taskId = extractCloudTaskId(`${execResult.stdout}\n${execResult.stderr}`);
+            if (!taskId) {
+                throw new Error('Unable to parse cloud task id from codex cloud exec output.');
+            }
+            cloudExecution.task_id = taskId;
+            cloudExecution.status = 'running';
+            cloudExecution.submitted_at = this.now();
+            notes.push(`Cloud task submitted: ${taskId}`);
+            const metadata = await this.lookupTaskMetadata(taskId, runCloudCommand);
+            if (metadata?.url) {
+                cloudExecution.status_url = metadata.url;
+            }
+            const timeoutAt = Date.now() + cloudExecution.timeout_seconds * 1000;
+            let statusRetries = 0;
+            while (Date.now() < timeoutAt) {
+                const statusResult = await runCloudCommand(['cloud', 'status', taskId]);
+                cloudExecution.last_polled_at = this.now();
+                cloudExecution.poll_count += 1;
+                const token = parseCloudStatusToken(`${statusResult.stdout}\n${statusResult.stderr}`);
+                const mapped = mapCloudStatusToken(token);
+                // `codex cloud status` may return a non-zero exit while the task is still pending.
+                // Treat non-zero as a retry only when no recognizable status token is present.
+                if (statusResult.exitCode !== 0 && mapped === 'unknown') {
+                    statusRetries += 1;
+                    if (statusRetries > STATUS_RETRY_LIMIT) {
+                        throw new Error(`codex cloud status failed ${statusRetries} times: ${compactError(statusResult.stderr, statusResult.stdout)}`);
+                    }
+                    await this.sleepFn(STATUS_RETRY_BACKOFF_MS * statusRetries);
+                    continue;
+                }
+                statusRetries = 0;
+                if (mapped !== 'unknown') {
+                    cloudExecution.status = mapped;
+                }
+                if (mapped === 'ready') {
+                    notes.push(`Cloud task completed: ${taskId}`);
+                    break;
+                }
+                if (mapped === 'error' || mapped === 'failed' || mapped === 'cancelled') {
+                    cloudExecution.error = `Cloud task ended with status ${mapped}.`;
+                    break;
+                }
+                await this.sleepFn(cloudExecution.poll_interval_seconds * 1000);
+            }
+            if (cloudExecution.status === 'running' || cloudExecution.status === 'queued') {
+                cloudExecution.status = 'failed';
+                cloudExecution.error = `Timed out waiting for cloud task completion after ${cloudExecution.timeout_seconds}s.`;
+            }
+            if (cloudExecution.status === 'ready') {
+                const diffResult = await runCloudCommand(['cloud', 'diff', taskId]);
+                if (diffResult.exitCode === 0 && diffResult.stdout.trim().length > 0) {
+                    const diffPath = join(cloudDir, `${taskId}.diff.patch`);
+                    await writeFile(diffPath, diffResult.stdout, 'utf8');
+                    cloudExecution.diff_path = relative(input.repoRoot, diffPath);
+                    cloudExecution.diff_status = 'available';
+                    cloudExecution.diff_url = cloudExecution.status_url;
+                    notes.push(`Cloud diff captured: ${cloudExecution.diff_path}`);
+                }
+                else {
+                    cloudExecution.diff_status = 'unavailable';
+                    if (diffResult.exitCode !== 0) {
+                        notes.push(`Cloud diff unavailable (exit ${diffResult.exitCode}).`);
+                    }
+                    else {
+                        notes.push('Cloud diff unavailable (empty payload).');
+                    }
+                }
+            }
+            else {
+                cloudExecution.diff_status = 'unavailable';
+            }
+            cloudExecution.completed_at = this.now();
+            const success = cloudExecution.status === 'ready';
+            const summary = success
+                ? `Cloud task ${cloudExecution.task_id} completed successfully.`
+                : `Cloud task ${cloudExecution.task_id ?? '<unknown>'} failed (${cloudExecution.status}).`;
+            return { success, summary, notes, cloudExecution };
+        }
+        catch (error) {
+            // Preserve non-queued status to reflect last known remote state at failure time.
+            cloudExecution.status = cloudExecution.status === 'queued' ? 'failed' : cloudExecution.status;
+            cloudExecution.diff_status = 'unavailable';
+            cloudExecution.error = error?.message ?? String(error);
+            cloudExecution.completed_at = this.now();
+            const summary = `Cloud execution failed: ${cloudExecution.error}`;
+            notes.push(summary);
+            return { success: false, summary, notes, cloudExecution };
+        }
+    }
+    async lookupTaskMetadata(taskId, runCloudCommand) {
+        const listResult = await runCloudCommand(['cloud', 'list', '--json', '--limit', String(DEFAULT_LIST_LIMIT)]);
+        if (listResult.exitCode !== 0) {
+            return null;
+        }
+        try {
+            const payload = JSON.parse(listResult.stdout);
+            const match = payload.tasks?.find((task) => task.id === taskId) ?? null;
+            return { url: match?.url ?? null };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export async function defaultCloudCommandRunner(request) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(request.command, request.args, {
+            cwd: request.cwd,
+            env: request.env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.once('error', (error) => {
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+        child.once('close', (code) => {
+            resolve({
+                exitCode: typeof code === 'number' ? code : 1,
+                stdout,
+                stderr
+            });
+        });
+    });
+}
+function truncate(value) {
+    if (value.length <= MAX_LOG_CHARS) {
+        return value;
+    }
+    return `${value.slice(0, MAX_LOG_CHARS)}…`;
+}
+function compactError(...values) {
+    const merged = values
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .join(' | ');
+    return merged.length > 0 ? truncate(merged) : 'no stderr/stdout captured';
+}

package/dist/orchestrator/src/manager.js

@@ -151,6 +151,7 @@ export class TaskManager {
             build,
             test,
             review,
+            cloudExecution: build.cloudExecution ?? null,
             timestamp
         };
     }

package/docs/README.md

@@ -21,6 +21,7 @@ Codex Orchestrator is the coordination layer that glues together Codex-driven ag
 
 ## Release Notes
 - Shipped skills note: `docs/release-notes-template-addendum.md`.
+- Optional overview override: add and commit a release overview file at .github/release-overview.md before tagging; the release workflow uses it when present.
 
 ## How It Works
 - **Planner → Builder → Tester → Reviewer:** The core `TaskManager` (see `orchestrator/src/manager.ts`) wires together agent interfaces that decide *what* to run (planner), execute the selected pipeline stage (builder), verify results (tester), and give a final decision (reviewer).
@@ -146,6 +147,7 @@ Notes:
 - `/prompts:diagnostics` takes `TASK=<task-id> MANIFEST=<path> [NOTES=<free text>]`, exports `MCP_RUNNER_TASK_ID=$TASK`, runs `npx @kbediako/codex-orchestrator start diagnostics --format json`, tails `.runs/$TASK/cli/<run-id>/manifest.json` (or `npx @kbediako/codex-orchestrator status --run <run-id> --watch --interval 10`), and records evidence to `/tasks`, `docs/TASKS.md`, `.agent/task/...`, `.runs/$TASK/metrics.json`, and `out/$TASK/state.json` using `$MANIFEST`.
 - `/prompts:review-handoff` takes `TASK=<task-id> MANIFEST=<path> NOTES=<goal + summary + risks + optional questions>`, re-exports `MCP_RUNNER_TASK_ID`, and (repo-only) runs `node scripts/delegation-guard.mjs`, `node scripts/spec-guard.mjs --dry-run`, `npm run lint`, `npm run test`, optional `npm run eval:test`, plus `npm run review` (wraps `codex review` against the current diff and includes the latest run manifest path as evidence). It also reminds you to log approvals in `$MANIFEST` and mirror the evidence to the same docs/metrics/state targets.
 - In CI / `--no-interactive` pipelines (or when stdin is not a TTY, or `CODEX_REVIEW_NON_INTERACTIVE=1` / `CODEX_NON_INTERACTIVE=1` / `CODEX_NO_INTERACTIVE=1`), `npm run review` prints the review handoff prompt (including evidence paths) and exits successfully instead of invoking `codex review`. Set `FORCE_CODEX_REVIEW=1` to run `codex review` in those environments.
+- When forcing non-interactive review execution, `npm run review` enforces a timeout (`CODEX_REVIEW_TIMEOUT_SECONDS`, default `900`). Set `CODEX_REVIEW_TIMEOUT_SECONDS=0` to disable the timeout.
 - Always trigger diagnostics and review workflows through these prompts whenever you run the orchestrator so contributors consistently execute the required command sequences and capture auditable manifests.
 
 ### Identifier Guardrails
@@ -195,6 +197,7 @@ Note: the commands below assume a source checkout; `scripts/` helpers are not in
 | `npm run eval:test` | Optional evaluation harness (enable when `evaluation/fixtures/**` is populated). |
 | `npm run docs:check` | Deterministically validates scripts/pipelines/paths referenced in agent-facing docs. |
 | `npm run docs:freshness` | Validates docs registry coverage + review recency; writes `out/<task-id>/docs-freshness.json`. |
+| `npm run ci:cloud-canary` | Runs the cloud canary harness (`scripts/cloud-canary-ci.mjs`) to verify cloud lifecycle manifest + run-summary evidence; credential-gated by `CODEX_CLOUD_ENV_ID` and optional auth secrets (`CODEX_CLOUD_BRANCH` defaults to `main`). |
 | `node scripts/delegation-guard.mjs` | Enforces subagent delegation evidence before review (repo-only). |
 | `node scripts/spec-guard.mjs --dry-run` | Validates spec freshness; required before review (repo-only). |
 | `node scripts/diff-budget.mjs` | Guards against oversized diffs before review (repo-only; defaults: 25 files / 800 lines; supports explicit overrides). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.13",
+  "version": "0.1.14-alpha.1",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -40,6 +40,7 @@
     "docs:archive-tasks": "node scripts/tasks-archive.mjs",
     "docs:freshness": "node scripts/docs-freshness.mjs --check",
     "docs:sync": "node --loader ts-node/esm scripts/docs-hygiene.ts --sync",
+    "ci:cloud-canary": "node scripts/cloud-canary-ci.mjs",
     "prelint": "node scripts/build-patterns-if-needed.mjs",
     "lint": "eslint orchestrator/src orchestrator/tests packages/orchestrator/src packages/orchestrator/tests packages/shared adapters evaluation/harness evaluation/tests --ext .ts,.tsx",
     "pack:audit": "node scripts/pack-audit.mjs",
@@ -75,6 +76,9 @@
     "eslint-plugin-patterns": "file:eslint-plugin-patterns",
     "jscodeshift": "^0.15.2",
     "json-schema-to-typescript": "^14.0.0",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.57.0",
+    "pngjs": "^7.0.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.0",
     "vitest": "^1.3.1"

package/schemas/manifest.json

@@ -317,6 +317,51 @@
         }
       }
     },
+    "cloud_execution": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": [
+        "task_id",
+        "environment_id",
+        "status",
+        "status_url",
+        "submitted_at",
+        "completed_at",
+        "last_polled_at",
+        "poll_count",
+        "poll_interval_seconds",
+        "timeout_seconds",
+        "attempts",
+        "diff_path",
+        "diff_url",
+        "diff_status",
+        "apply_status",
+        "log_path",
+        "error"
+      ],
+      "properties": {
+        "task_id": { "type": ["string", "null"] },
+        "environment_id": { "type": ["string", "null"] },
+        "status": {
+          "type": "string",
+          "enum": ["queued", "running", "ready", "error", "failed", "cancelled", "unknown"]
+        },
+        "status_url": { "type": ["string", "null"] },
+        "submitted_at": { "type": ["string", "null"] },
+        "completed_at": { "type": ["string", "null"] },
+        "last_polled_at": { "type": ["string", "null"] },
+        "poll_count": { "type": "integer", "minimum": 0 },
+        "poll_interval_seconds": { "type": "integer", "minimum": 1 },
+        "timeout_seconds": { "type": "integer", "minimum": 1 },
+        "attempts": { "type": "integer", "minimum": 1 },
+        "diff_path": { "type": ["string", "null"] },
+        "diff_url": { "type": ["string", "null"] },
+        "diff_status": { "type": "string", "enum": ["pending", "available", "unavailable"] },
+        "apply_status": { "type": "string", "enum": ["not_requested", "succeeded", "failed"] },
+        "log_path": { "type": ["string", "null"] },
+        "error": { "type": ["string", "null"] }
+      }
+    },
     "privacy": {
       "type": ["object", "null"],
       "additionalProperties": false,

package/skills/delegation-usage/SKILL.md

@@ -158,6 +158,7 @@ repeat:
 
 - **Long waits:** `wait_ms` never blocks longer than 10s per call; use polling.
 - **Long-running delegate.spawn:** Prefer `start_only=true` (default) to avoid tool-call timeouts. If you must use `start_only=false`, keep runs short or run long jobs outside delegation (no question queue).
+- **Cloud run branch mismatch:** cloud-mode orchestration against a local-only branch can fail with `couldn't find remote ref ...`; set `CODEX_CLOUD_BRANCH` to a pushed branch (typically `main`) before cloud execution.
 - **Tool profile mismatch:** child tool profile must be allowed by repo policy; invalid or unsafe names are ignored.
 - **Confirmation misuse:** never pass `confirm_nonce` from model/tool input; it is runner‑injected only.
 - **Secrets exposure:** never include secrets/tokens/PII in delegate prompts or files.

package/skills/docs-first/SKILL.md

@@ -25,6 +25,7 @@ Use this skill when a task needs a spec-driven workflow. The objective is to cre
 
 3) Run docs-review before implementation
 - `npx codex-orchestrator start docs-review --format json --no-interactive --task <task-id>`
+- If running in cloud mode, ensure the branch exists on remote. For local-only branches, set `CODEX_CLOUD_BRANCH=main` (or another pushed branch).
 - Link the manifest path in the checklists.
 
 4) Implement and validate