@kbediako/codex-orchestrator 0.1.33 → 0.1.34

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

@@ -7,6 +7,9 @@ import { isManagedCodexCliEnabled, resolveCodexCliBin, resolveCodexCliReadiness
 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',
@@ -95,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 {
@@ -120,11 +124,13 @@ export function runDoctor(cwd = process.cwd()) {
             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: {
@@ -151,7 +157,26 @@ export async function runDoctorCloudPreflight(options = {}) {
         ?? normalizeOptionalString(env.MCP_RUNNER_TASK_ID)
         ?? normalizeOptionalString(env.TASK)
         ?? normalizeOptionalString(env.CODEX_ORCHESTRATOR_TASK_ID);
-    const environmentId = normalizeOptionalString(options.environmentId)
+    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);
@@ -162,15 +187,16 @@ export async function runDoctorCloudPreflight(options = {}) {
         branch,
         env
     });
-    const guidance = buildCloudPreflightGuidance(preflight.issues);
+    const issues = planMetadataIssue ? [planMetadataIssue, ...preflight.issues] : preflight.issues;
+    const guidance = buildCloudPreflightGuidance(issues);
     return {
-        ok: preflight.ok,
+        ok: preflight.ok && planMetadataIssue === null,
         details: {
             codex_bin: preflight.details.codexBin,
             environment_id: preflight.details.environmentId,
             branch: preflight.details.branch
         },
-        issues: preflight.issues,
+        issues,
         guidance
     };
 }
@@ -283,6 +309,7 @@ export function formatDoctorSummary(result) {
     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}`);
     }
@@ -310,6 +337,53 @@ 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;
@@ -382,6 +456,9 @@ function buildCloudPreflightGuidance(issues) {
             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;
         }