@kbediako/codex-orchestrator 0.1.32 → 0.1.34

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

@@ -86,6 +86,7 @@ export function formatCodexCliSetupSummary(result) {
         lines.push(`- Installed SHA256: ${result.install.sha256}`);
     }
     lines.push(`- Command: ${result.plan.commandLine}`);
+    lines.push('- Selection: stock `codex` stays default. Set CODEX_CLI_USE_MANAGED=1 to use this managed binary.');
     if (result.status === 'planned') {
         lines.push('Run with --yes to apply this setup.');
     }

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

@@ -0,0 +1,22 @@
+import { join } from 'node:path';
+import process from 'node:process';
+export const REPO_CONFIG_REQUIRED_ENV_KEY = 'CODEX_ORCHESTRATOR_REPO_CONFIG_REQUIRED';
+const REPO_CONFIG_REQUIRED_TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+export function isRepoConfigRequired(env = process.env) {
+    const raw = env[REPO_CONFIG_REQUIRED_ENV_KEY];
+    if (typeof raw !== 'string') {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    return REPO_CONFIG_REQUIRED_TRUE_VALUES.has(normalized);
+}
+export function formatRepoConfigRequiredError(repoRoot) {
+    return [
+        `Repo-local codex.orchestrator.json is required when ${REPO_CONFIG_REQUIRED_ENV_KEY}=1.`,
+        `Expected: ${join(repoRoot, 'codex.orchestrator.json')}.`,
+        'Run `codex-orchestrator init codex` to scaffold repo-local config.'
+    ].join(' ');
+}

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

@@ -2,17 +2,21 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { logger } from '../../logger.js';
 import { findPackageRoot } from '../utils/packageInfo.js';
-export async function loadRepoConfig(env) {
+export async function loadRepoConfig(env, options = {}) {
     const repoConfigPath = join(env.repoRoot, 'codex.orchestrator.json');
     const repoConfig = await readConfig(repoConfigPath);
     if (repoConfig) {
-        logger.info(`[codex-config] Loaded user config from ${repoConfigPath}`);
+        if (!options.quiet) {
+            logger.info(`[codex-config] Loaded user config from ${repoConfigPath}`);
+        }
         return normalizeUserConfig(repoConfig, 'repo');
     }
-    logger.warn(`[codex-config] Missing codex.orchestrator.json at ${repoConfigPath}`);
+    if (!options.quiet) {
+        logger.warn(`[codex-config] Missing codex.orchestrator.json at ${repoConfigPath}`);
+    }
     return null;
 }
-export async function loadPackageConfig(env) {
+export async function loadPackageConfig(env, options = {}) {
     const repoConfigPath = join(env.repoRoot, 'codex.orchestrator.json');
     const packageRoot = findPackageRoot();
     const packageConfigPath = join(packageRoot, 'codex.orchestrator.json');
@@ -21,18 +25,25 @@ export async function loadPackageConfig(env) {
     }
     const packageConfig = await readConfig(packageConfigPath);
     if (packageConfig) {
-        logger.info(`[codex-config] Loaded user config from ${packageConfigPath}`);
+        if (!options.quiet) {
+            logger.info(`[codex-config] Loaded user config from ${packageConfigPath}`);
+        }
         return normalizeUserConfig(packageConfig, 'package');
     }
-    logger.warn(`[codex-config] Missing codex.orchestrator.json at ${packageConfigPath}`);
+    if (!options.quiet) {
+        logger.warn(`[codex-config] Missing package config at ${packageConfigPath}`);
+    }
     return null;
 }
-export async function loadUserConfig(env) {
-    const repoConfig = await loadRepoConfig(env);
+export async function loadUserConfig(env, options = {}) {
+    const repoConfig = await loadRepoConfig(env, options);
     if (repoConfig) {
         return repoConfig;
     }
-    return await loadPackageConfig(env);
+    if (options.allowPackageFallback === false) {
+        return null;
+    }
+    return await loadPackageConfig(env, options);
 }
 export function findPipeline(config, id) {
     if (!config?.pipelines) {

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

@@ -4,9 +4,10 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { resolveCodexCliBin } from './utils/codexCli.js';
 import { resolveCodexHome } from './utils/codexPaths.js';
+import { buildCommandPreview } from './utils/commandPreview.js';
 export async function runDelegationSetup(options = {}) {
     const env = options.env ?? process.env;
-    const repoRoot = options.repoRoot ?? process.cwd();
+    const repoRoot = resolve(options.repoRoot ?? process.cwd());
     const codexBin = resolveCodexCliBin(env);
     const codexHome = resolveCodexHome(env);
     const configPath = join(codexHome, 'config.toml');
@@ -14,7 +15,16 @@ export async function runDelegationSetup(options = {}) {
         codexBin,
         codexHome,
         repoRoot,
-        commandLine: `"${codexBin}" mcp add delegation -- codex-orchestrator delegate-server`
+        commandLine: buildCommandPreview(codexBin, [
+            'mcp',
+            'add',
+            'delegation',
+            '--',
+            'codex-orchestrator',
+            'delegate-server',
+            '--repo',
+            repoRoot
+        ])
     };
     const probe = inspectDelegationReadiness({ codexBin, configPath, repoRoot, env });
     const readiness = { configured: probe.configured, configPath };
@@ -24,7 +34,7 @@ export async function runDelegationSetup(options = {}) {
     if (probe.configured) {
         return { status: 'skipped', reason: probe.reason ?? 'Delegation MCP is already configured.', plan, readiness };
     }
-    await applyDelegationSetup({ codexBin, removeExisting: probe.removeExisting, envVars: probe.envVars }, env);
+    await applyDelegationSetup({ codexBin, repoRoot, removeExisting: probe.removeExisting, envVars: probe.envVars }, env);
     const configuredAfter = inspectDelegationReadiness({ codexBin, configPath, repoRoot, env }).configured;
     return {
         status: 'applied',
@@ -79,15 +89,14 @@ function inspectDelegationReadiness(options) {
             };
         }
         return {
-            configured: true,
-            removeExisting: false,
+            configured: false,
+            removeExisting: true,
             envVars,
-            reason: 'Delegation MCP is already configured.'
+            reason: `Existing delegation MCP entry is not pinned; reconfiguring to ${requestedRepo}.`
         };
     }
     // Fall back to directly scanning config.toml when the Codex CLI probe is unavailable.
-    const configured = isDelegationConfiguredFallback(options.configPath);
-    return { configured, removeExisting: false, envVars: {} };
+    return inspectDelegationReadinessFallback(options.configPath, requestedRepo);
 }
 function applyDelegationSetup(plan, env) {
     const envFlags = [];
@@ -96,7 +105,17 @@ function applyDelegationSetup(plan, env) {
     }
     return new Promise((resolve, reject) => {
         const runAdd = () => {
-            const child = spawn(plan.codexBin, ['mcp', 'add', 'delegation', ...envFlags, '--', 'codex-orchestrator', 'delegate-server'], { stdio: 'inherit', env });
+            const child = spawn(plan.codexBin, [
+                'mcp',
+                'add',
+                'delegation',
+                ...envFlags,
+                '--',
+                'codex-orchestrator',
+                'delegate-server',
+                '--repo',
+                plan.repoRoot
+            ], { stdio: 'inherit', env });
             child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
             child.once('exit', (code) => {
                 if (code === 0) {
@@ -167,18 +186,96 @@ function readPinnedRepo(args) {
     const candidate = args[index + 1];
     return typeof candidate === 'string' && candidate.trim().length > 0 ? candidate.trim() : null;
 }
-function isDelegationConfiguredFallback(configPath) {
+function inspectDelegationReadinessFallback(configPath, requestedRepo) {
+    const config = readDelegationFallbackConfig(configPath);
+    if (!config) {
+        return { configured: false, removeExisting: false, envVars: {} };
+    }
+    const pinnedRepo = readPinnedRepo(config.args);
+    if (!pinnedRepo) {
+        return {
+            configured: false,
+            removeExisting: true,
+            envVars: config.envVars,
+            reason: `Existing delegation MCP entry is not pinned; reconfiguring to ${requestedRepo}.`
+        };
+    }
+    const normalizedPinned = resolve(pinnedRepo);
+    if (normalizedPinned !== requestedRepo) {
+        return {
+            configured: false,
+            removeExisting: true,
+            envVars: config.envVars,
+            reason: `Existing delegation MCP entry is pinned to ${pinnedRepo}; reconfiguring.`
+        };
+    }
+    return {
+        configured: true,
+        removeExisting: false,
+        envVars: config.envVars,
+        reason: `Delegation MCP is already configured (pinned to ${pinnedRepo}).`
+    };
+}
+function readDelegationFallbackConfig(configPath) {
     if (!existsSync(configPath)) {
-        return false;
+        return null;
     }
     try {
-        // Keep parsing loose; we only need to know whether a delegation entry exists.
         const raw = readFileSync(configPath, 'utf8');
-        return hasMcpServerEntry(raw, 'delegation');
+        if (!hasMcpServerEntry(raw, 'delegation')) {
+            return null;
+        }
+        return {
+            args: readDelegationArgsFromConfig(raw),
+            envVars: readDelegationEnvVarsFromConfig(raw)
+        };
     }
     catch {
-        return false;
+        return null;
+    }
+}
+function readDelegationArgsFromConfig(raw) {
+    const sectionMatch = raw.match(/\[mcp_servers(?:\.delegation|\."delegation"|.'delegation')\]([\s\S]*?)(?=\n\[|$)/u);
+    if (!sectionMatch) {
+        return [];
+    }
+    const section = sectionMatch[1] ?? '';
+    const argsMatch = section.match(/^\s*args\s*=\s*\[([\s\S]*?)\]/mu);
+    if (!argsMatch) {
+        return [];
+    }
+    const argsRaw = argsMatch[1] ?? '';
+    const args = [];
+    const tokenPattern = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'/gu;
+    let token = tokenPattern.exec(argsRaw);
+    while (token) {
+        const quoted = token[1] ?? token[2] ?? '';
+        const decoded = quoted.replace(/\\"/gu, '"').replace(/\\'/gu, '\'');
+        args.push(decoded);
+        token = tokenPattern.exec(argsRaw);
+    }
+    return args;
+}
+function readDelegationEnvVarsFromConfig(raw) {
+    const envVars = {};
+    const sectionMatch = raw.match(/\[mcp_servers(?:\.delegation|\."delegation"|.'delegation')\.env\]([\s\S]*?)(?=\n\[|$)/u);
+    if (!sectionMatch) {
+        return envVars;
+    }
+    const section = sectionMatch[1] ?? '';
+    const linePattern = /^\s*([A-Za-z0-9_.-]+)\s*=\s*("(?:\\"|[^"])*"|'(?:\\'|[^'])*')\s*$/gmu;
+    let match = linePattern.exec(section);
+    while (match) {
+        const key = match[1];
+        const rawValue = match[2] ?? '';
+        if (key) {
+            const unquoted = rawValue.slice(1, -1);
+            const decoded = unquoted.replace(/\\"/gu, '"').replace(/\\'/gu, '\'');
+            envVars[key] = decoded;
+        }
+        match = linePattern.exec(section);
     }
+    return envVars;
 }
 function hasMcpServerEntry(raw, serverName) {
     const lines = raw.split('\n');

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

@@ -1,11 +1,15 @@
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { buildDevtoolsSetupPlan, DEVTOOLS_SKILL_NAME, resolveDevtoolsReadiness } from './utils/devtools.js';
-import { resolveCodexCliBin, resolveCodexCliReadiness } from './utils/codexCli.js';
+import { isManagedCodexCliEnabled, resolveCodexCliBin, resolveCodexCliReadiness } from './utils/codexCli.js';
 import { resolveCodexHome } from './utils/codexPaths.js';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
+import { runCloudPreflight } from './utils/cloudPreflight.js';
+import { CommandPlanner } from './adapters/CommandPlanner.js';
+import { PipelineResolver } from './services/pipelineResolver.js';
+import { isRepoConfigRequired } from './config/repoConfigPolicy.js';
 const OPTIONAL_DEPENDENCIES = [
     {
         name: 'playwright',
@@ -72,9 +76,21 @@ export function runDoctor(cwd = process.cwd()) {
         missing.push(`${DEVTOOLS_SKILL_NAME}-config`);
     }
     const codexBin = resolveCodexCliBin(process.env);
+    const managedOptIn = isManagedCodexCliEnabled(process.env);
     const managedCodex = resolveCodexCliReadiness(process.env);
     const features = readCodexFeatureFlags(codexBin);
-    const collabEnabled = features?.collab ?? null;
+    const collabFeatureKey = features === null
+        ? null
+        : Object.prototype.hasOwnProperty.call(features, 'multi_agent')
+            ? 'multi_agent'
+            : Object.prototype.hasOwnProperty.call(features, 'collab')
+                ? 'collab'
+                : null;
+    const collabEnabled = collabFeatureKey === 'multi_agent'
+        ? features?.multi_agent ?? null
+        : collabFeatureKey === 'collab'
+            ? features?.collab ?? null
+            : null;
     const collabStatus = features === null ? 'unavailable' : collabEnabled ? 'ok' : 'disabled';
     const cloudCmdAvailable = canRunCommand(codexBin, ['cloud', '--help']);
     const cloudEnvIdConfigured = typeof process.env.CODEX_CLOUD_ENV_ID === 'string' && process.env.CODEX_CLOUD_ENV_ID.trim().length > 0;
@@ -82,6 +98,7 @@ export function runDoctor(cwd = process.cwd()) {
         ? process.env.CODEX_CLOUD_BRANCH.trim().replace(/^refs\/heads\//u, '')
         : null;
     const cloudStatus = !cloudCmdAvailable ? 'unavailable' : cloudEnvIdConfigured ? 'ok' : 'not_configured';
+    const cloudFallbackPolicy = resolveCloudFallbackPolicy();
     const delegationConfig = inspectDelegationConfig();
     const delegationStatus = delegationConfig.status === 'ok' ? 'ok' : 'missing-config';
     return {
@@ -90,27 +107,30 @@ export function runDoctor(cwd = process.cwd()) {
         dependencies,
         devtools,
         codex_cli: {
-            active: { command: codexBin },
+            active: { command: codexBin, managed_opt_in: managedOptIn },
             managed: managedCodex
         },
         collab: {
             status: collabStatus,
             enabled: collabEnabled,
+            feature_key: collabFeatureKey,
             enablement: [
-                'Enable collab for symbolic RLM runs with: codex-orchestrator rlm --collab auto "<goal>"',
-                'Or set: RLM_SYMBOLIC_COLLAB=1 (implies symbolic mode when using --collab).',
-                'If collab is disabled in codex features: codex features enable collab'
+                'Enable collab for symbolic RLM runs with: codex-orchestrator rlm --multi-agent auto "<goal>" (legacy: --collab auto).',
+                'Or set: RLM_SYMBOLIC_MULTI_AGENT=1 (legacy alias: RLM_SYMBOLIC_COLLAB=1).',
+                'If multi-agent is disabled in codex features: codex features enable multi_agent (legacy alias: collab)'
             ]
         },
         cloud: {
             status: cloudStatus,
             env_id_configured: cloudEnvIdConfigured,
             branch: cloudBranch,
+            fallback_policy: cloudFallbackPolicy,
             enablement: [
                 'Set CODEX_CLOUD_ENV_ID to a valid Codex Cloud environment id.',
                 'Optional: set CODEX_CLOUD_BRANCH (must exist on origin).',
                 'Then run a pipeline stage in cloud mode with: codex-orchestrator start <pipeline> --cloud --target <stage-id>',
-                'If cloud preflight fails, CO falls back to mcp and records the reason in manifest.summary (surfaced in start output).'
+                'Cloud fallback is a compatibility safety net; prefer fail-fast lanes with CODEX_ORCHESTRATOR_CLOUD_FALLBACK=deny.',
+                'If cloud preflight fails and fallback is allowed, CO falls back to mcp and records the reason in manifest.summary (surfaced in start output).'
             ]
         },
         delegation: {
@@ -126,6 +146,95 @@ export function runDoctor(cwd = process.cwd()) {
         }
     };
 }
+export async function runDoctorCloudPreflight(options = {}) {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const configuredRoot = normalizeOptionalString(env.CODEX_ORCHESTRATOR_ROOT);
+    const rootHint = configuredRoot ? resolve(cwd, configuredRoot) : cwd;
+    const repoRoot = resolveDoctorRepoRoot(rootHint);
+    const codexBin = resolveCodexCliBin(env);
+    const taskId = normalizeOptionalString(options.taskId)
+        ?? normalizeOptionalString(env.MCP_RUNNER_TASK_ID)
+        ?? normalizeOptionalString(env.TASK)
+        ?? normalizeOptionalString(env.CODEX_ORCHESTRATOR_TASK_ID);
+    const explicitEnvironmentId = normalizeOptionalString(options.environmentId);
+    const strictRepoConfigRequired = isRepoConfigRequired(env);
+    let planMetadataEnvironmentId = null;
+    let planMetadataIssue = null;
+    if (!explicitEnvironmentId || strictRepoConfigRequired) {
+        try {
+            planMetadataEnvironmentId = await resolvePlanMetadataCloudEnvironmentId(repoRoot, taskId, env);
+        }
+        catch (error) {
+            if (strictRepoConfigRequired) {
+                const detail = error instanceof Error ? error.message : String(error);
+                planMetadataIssue = {
+                    code: 'pipeline_resolution_failed',
+                    message: `Pipeline resolution failed during doctor cloud preflight: ${detail}`
+                };
+            }
+        }
+    }
+    const environmentId = explicitEnvironmentId
+        ?? planMetadataEnvironmentId
+        ?? normalizeOptionalString(env.CODEX_CLOUD_ENV_ID)
+        ?? resolveTaskMetadataCloudEnvironmentId(repoRoot, taskId);
+    const branch = normalizeOptionalBranch(options.branch) ?? normalizeOptionalBranch(env.CODEX_CLOUD_BRANCH);
+    const preflight = await runCloudPreflight({
+        repoRoot,
+        codexBin,
+        environmentId,
+        branch,
+        env
+    });
+    const issues = planMetadataIssue ? [planMetadataIssue, ...preflight.issues] : preflight.issues;
+    const guidance = buildCloudPreflightGuidance(issues);
+    return {
+        ok: preflight.ok && planMetadataIssue === null,
+        details: {
+            codex_bin: preflight.details.codexBin,
+            environment_id: preflight.details.environmentId,
+            branch: preflight.details.branch
+        },
+        issues,
+        guidance
+    };
+}
+function resolveDoctorRepoRoot(cwd) {
+    const fallback = resolve(cwd);
+    let current = fallback;
+    while (current) {
+        if (existsSync(join(current, 'tasks', 'index.json'))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return fallback;
+}
+export function formatDoctorCloudPreflightSummary(result) {
+    const lines = [];
+    lines.push(`Cloud preflight: ${result.ok ? 'ok' : 'failed'}`);
+    lines.push(`  - codex bin: ${result.details.codex_bin}`);
+    lines.push(`  - environment id: ${result.details.environment_id ?? '<unset>'}`);
+    lines.push(`  - branch: ${result.details.branch ?? '<unset>'}`);
+    if (result.issues.length > 0) {
+        lines.push('  - issues:');
+        for (const issue of result.issues) {
+            lines.push(`    - [${issue.code}] ${issue.message}`);
+        }
+    }
+    if (result.guidance.length > 0) {
+        lines.push('  - guidance:');
+        for (const item of result.guidance) {
+            lines.push(`    - ${item}`);
+        }
+    }
+    return lines;
+}
 export function formatDoctorSummary(result) {
     const lines = [];
     lines.push(`Status: ${result.status}`);
@@ -173,12 +282,16 @@ export function formatDoctorSummary(result) {
         lines.push(`  - ${line}`);
     }
     lines.push(`Codex CLI: ${result.codex_cli.active.command}`);
+    lines.push(`  - managed opt-in: ${result.codex_cli.active.managed_opt_in ? 'enabled' : 'disabled'} (set CODEX_CLI_USE_MANAGED=1)`);
     lines.push(`  - managed: ${result.codex_cli.managed.status} (${result.codex_cli.managed.config.path})`);
     if (result.codex_cli.managed.status === 'invalid' && result.codex_cli.managed.config.error) {
         lines.push(`    error: ${result.codex_cli.managed.config.error}`);
     }
     if (result.codex_cli.managed.status === 'ok') {
         lines.push(`  - binary: ${result.codex_cli.managed.binary.status} (${result.codex_cli.managed.binary.path})`);
+        if (!result.codex_cli.active.managed_opt_in) {
+            lines.push('  - note: managed binary is installed but inactive; stock codex is currently selected.');
+        }
         if (result.codex_cli.managed.install?.version) {
             lines.push(`  - version: ${result.codex_cli.managed.install.version}`);
         }
@@ -187,12 +300,16 @@ export function formatDoctorSummary(result) {
     if (result.collab.enabled !== null) {
         lines.push(`  - enabled: ${result.collab.enabled}`);
     }
+    if (result.collab.feature_key) {
+        lines.push(`  - feature key: ${result.collab.feature_key}`);
+    }
     for (const line of result.collab.enablement) {
         lines.push(`  - ${line}`);
     }
     lines.push(`Cloud: ${result.cloud.status}`);
     lines.push(`  - CODEX_CLOUD_ENV_ID: ${result.cloud.env_id_configured ? 'set' : 'missing'}`);
     lines.push(`  - CODEX_CLOUD_BRANCH: ${result.cloud.branch ?? '<unset>'}`);
+    lines.push(`  - fallback policy: ${result.cloud.fallback_policy}`);
     for (const line of result.cloud.enablement) {
         lines.push(`  - ${line}`);
     }
@@ -209,6 +326,145 @@ export function formatDoctorSummary(result) {
     }
     return lines;
 }
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeOptionalBranch(value) {
+    const normalized = normalizeOptionalString(value);
+    return normalized ? normalized.replace(/^refs\/heads\//u, '') : null;
+}
+function resolveCloudFallbackPolicy(env = process.env) {
+    const raw = normalizeOptionalString(env.CODEX_ORCHESTRATOR_CLOUD_FALLBACK);
+    if (!raw) {
+        return 'allow';
+    }
+    const normalized = raw.toLowerCase();
+    if (['0', 'false', 'off', 'deny', 'disabled', 'never', 'strict'].includes(normalized)) {
+        return 'deny';
+    }
+    return 'allow';
+}
+async function resolvePlanMetadataCloudEnvironmentId(repoRoot, taskId, processEnv = process.env) {
+    const env = {
+        repoRoot,
+        runsRoot: join(repoRoot, '.runs'),
+        outRoot: join(repoRoot, 'out'),
+        taskId: taskId ?? '0101'
+    };
+    const resolver = new PipelineResolver();
+    const resolution = await resolver.resolve(env, { quiet: true, processEnv });
+    const planner = new CommandPlanner(resolution.pipeline);
+    const context = {
+        id: env.taskId,
+        title: env.taskId,
+        metadata: {}
+    };
+    const plan = await planner.plan(context);
+    const selected = plan.items.find((item) => item.id === plan.targetId)
+        ?? plan.items[0]
+        ?? null;
+    if (!selected || !selected.metadata || typeof selected.metadata !== 'object') {
+        return null;
+    }
+    return resolveCloudEnvironmentIdFromMetadata(selected.metadata);
+}
+function resolveCloudEnvironmentIdFromMetadata(metadata) {
+    const stagePlan = metadata.plan && typeof metadata.plan === 'object'
+        ? metadata.plan
+        : null;
+    const candidates = [
+        normalizeOptionalString(typeof stagePlan?.cloudEnvId === 'string' ? stagePlan.cloudEnvId : null),
+        normalizeOptionalString(typeof stagePlan?.cloud_env_id === 'string' ? stagePlan.cloud_env_id : null),
+        normalizeOptionalString(typeof metadata.cloudEnvId === 'string' ? metadata.cloudEnvId : null),
+        normalizeOptionalString(typeof metadata.cloud_env_id === 'string' ? metadata.cloud_env_id : null)
+    ];
+    return candidates.find((value) => Boolean(value)) ?? null;
+}
+function resolveTaskMetadataCloudEnvironmentId(repoRoot, taskId) {
+    if (!taskId) {
+        return null;
+    }
+    const tasksPath = join(repoRoot, 'tasks', 'index.json');
+    if (!existsSync(tasksPath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(tasksPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const items = Array.isArray(parsed.items) ? parsed.items : [];
+        const match = items.find((item) => {
+            if (!item || typeof item !== 'object') {
+                return false;
+            }
+            const record = item;
+            return matchesTaskIdentifier(record.id, taskId) || matchesTaskIdentifier(record.slug, taskId);
+        });
+        if (!match || typeof match !== 'object') {
+            return null;
+        }
+        const record = match;
+        const metadata = (record.metadata ?? null);
+        const cloudMetadata = metadata && typeof metadata.cloud === 'object' && metadata.cloud
+            ? metadata.cloud
+            : null;
+        const candidates = [
+            normalizeOptionalString(typeof metadata?.cloudEnvId === 'string' ? metadata.cloudEnvId : null),
+            normalizeOptionalString(typeof metadata?.cloud_env_id === 'string' ? metadata.cloud_env_id : null),
+            normalizeOptionalString(typeof metadata?.envId === 'string' ? metadata.envId : null),
+            normalizeOptionalString(typeof metadata?.environmentId === 'string' ? metadata.environmentId : null),
+            normalizeOptionalString(typeof cloudMetadata?.envId === 'string' ? cloudMetadata.envId : null),
+            normalizeOptionalString(typeof cloudMetadata?.environmentId === 'string' ? cloudMetadata.environmentId : null),
+            normalizeOptionalString(typeof cloudMetadata?.cloudEnvId === 'string' ? cloudMetadata.cloudEnvId : null),
+            normalizeOptionalString(typeof cloudMetadata?.cloud_env_id === 'string' ? cloudMetadata.cloud_env_id : null)
+        ];
+        return candidates.find((value) => Boolean(value)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function matchesTaskIdentifier(value, taskId) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return false;
+    }
+    return normalized === taskId || taskId.startsWith(`${normalized}-`);
+}
+function buildCloudPreflightGuidance(issues) {
+    if (issues.length === 0) {
+        return ['Cloud preflight passed. You can run cloud mode with `--cloud --target <stage-id>`.'];
+    }
+    const guidance = [];
+    for (const issue of issues) {
+        switch (issue.code) {
+            case 'missing_environment':
+                guidance.push('Set CODEX_CLOUD_ENV_ID or provide target metadata.cloudEnvId.');
+                break;
+            case 'branch_missing':
+                guidance.push('Push the branch to origin or set CODEX_CLOUD_BRANCH to an existing remote branch.');
+                break;
+            case 'codex_unavailable':
+                guidance.push('Install Codex CLI or set CODEX_CLI_BIN to a valid codex binary.');
+                break;
+            case 'git_unavailable':
+                guidance.push('Install git or run with CODEX_CLOUD_BRANCH unset to skip remote branch verification.');
+                break;
+            case 'pipeline_resolution_failed':
+                guidance.push('Fix pipeline/config resolution errors before cloud runs (run `codex-orchestrator init codex`).');
+                break;
+            default:
+                break;
+        }
+    }
+    return [...new Set(guidance)];
+}
 function readCodexFeatureFlags(codexBin) {
     const result = spawnSync(codexBin, ['features', 'list'], {
         encoding: 'utf8',