@kbediako/codex-orchestrator 0.1.32 → 0.1.33

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

@@ -0,0 +1,392 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { resolveCodexCliBin } from './utils/codexCli.js';
+const DEFAULT_MCP_COMMAND_TIMEOUT_MS = 30_000;
+export async function runMcpEnable(options = {}) {
+    const env = options.env ?? process.env;
+    const codexBin = resolveCodexCliBin(env);
+    const commandRunner = options.commandRunner ?? defaultMcpCommandRunner;
+    const listResult = await commandRunner({
+        command: codexBin,
+        args: ['mcp', 'list', '--json'],
+        env
+    });
+    if (listResult.exitCode !== 0) {
+        throw new Error(`codex mcp list failed: ${compactError(listResult.stderr, listResult.stdout)}`);
+    }
+    let servers;
+    try {
+        servers = parseMcpServerList(listResult.stdout);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`codex mcp list --json returned invalid output: ${reason}`);
+    }
+    const requestedNames = dedupeNames(options.serverNames ?? []);
+    const targetNames = requestedNames.length > 0
+        ? requestedNames
+        : servers
+            .filter((server) => !server.enabled)
+            .map((server) => server.name);
+    const actions = [];
+    for (const targetName of targetNames) {
+        const server = servers.find((item) => item.name === targetName);
+        if (!server) {
+            actions.push({
+                name: targetName,
+                status: 'missing',
+                reason: 'MCP server not found in codex mcp list output.'
+            });
+            continue;
+        }
+        if (server.enabled) {
+            actions.push({ name: targetName, status: 'already_enabled' });
+            continue;
+        }
+        const enablePlan = buildEnablePlan(server);
+        if (!enablePlan.ok) {
+            actions.push({
+                name: targetName,
+                status: 'unsupported',
+                reason: enablePlan.reason
+            });
+            continue;
+        }
+        if (!options.apply) {
+            const displayArgs = redactArgsForDisplay(enablePlan.args);
+            actions.push({
+                name: targetName,
+                status: 'planned',
+                command_line: `${shellEscape(codexBin)} ${displayArgs.map(shellEscape).join(' ')}`
+            });
+            continue;
+        }
+        const applyResult = await commandRunner({
+            command: codexBin,
+            args: enablePlan.args,
+            env
+        });
+        if (applyResult.exitCode !== 0) {
+            actions.push({
+                name: targetName,
+                status: 'failed',
+                reason: compactError(applyResult.stderr, applyResult.stdout)
+            });
+            continue;
+        }
+        actions.push({ name: targetName, status: 'enabled' });
+    }
+    return {
+        status: options.apply ? 'applied' : 'planned',
+        codex_bin: codexBin,
+        targets: targetNames,
+        actions
+    };
+}
+export function formatMcpEnableSummary(result) {
+    const lines = [];
+    lines.push(`MCP enable: ${result.status}`);
+    lines.push(`- Codex bin: ${result.codex_bin}`);
+    lines.push(`- Targets: ${result.targets.length > 0 ? result.targets.join(', ') : '<none>'}`);
+    const byStatus = summarizeByStatus(result.actions);
+    lines.push(`- Results: enabled=${byStatus.enabled}, planned=${byStatus.planned}, already_enabled=${byStatus.already_enabled}, missing=${byStatus.missing}, unsupported=${byStatus.unsupported}, failed=${byStatus.failed}`);
+    for (const action of result.actions) {
+        if (action.status === 'planned' && action.command_line) {
+            lines.push(`  - ${action.name}: planned -> ${action.command_line}`);
+            continue;
+        }
+        if (action.reason) {
+            lines.push(`  - ${action.name}: ${action.status} (${action.reason})`);
+            continue;
+        }
+        lines.push(`  - ${action.name}: ${action.status}`);
+    }
+    if (result.status === 'planned' && byStatus.planned > 0) {
+        lines.push('Run with --yes to apply.');
+    }
+    return lines;
+}
+function parseMcpServerList(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('invalid JSON payload.');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('expected top-level JSON array.');
+    }
+    const servers = [];
+    for (const item of parsed) {
+        if (!item || typeof item !== 'object') {
+            continue;
+        }
+        const record = item;
+        const name = typeof record.name === 'string' ? record.name.trim() : '';
+        if (!name) {
+            continue;
+        }
+        if (typeof record.enabled !== 'boolean') {
+            throw new Error(`expected boolean "enabled" for server "${name}".`);
+        }
+        servers.push({
+            name,
+            enabled: record.enabled,
+            startupTimeoutSec: typeof record.startup_timeout_sec === 'number' && Number.isFinite(record.startup_timeout_sec)
+                ? record.startup_timeout_sec
+                : null,
+            toolTimeoutSec: typeof record.tool_timeout_sec === 'number' && Number.isFinite(record.tool_timeout_sec)
+                ? record.tool_timeout_sec
+                : null,
+            transport: record.transport ?? undefined
+        });
+    }
+    return servers;
+}
+function buildEnablePlan(server) {
+    if (server.startupTimeoutSec !== null || server.toolTimeoutSec !== null) {
+        return {
+            ok: false,
+            reason: 'Server defines startup/tool timeout settings; codex mcp add cannot preserve those fields. Enable this server manually.'
+        };
+    }
+    const transport = server.transport;
+    if (!transport || typeof transport !== 'object') {
+        return { ok: false, reason: 'Server transport details are missing.' };
+    }
+    const type = typeof transport.type === 'string' ? transport.type.trim() : '';
+    if (type === 'stdio') {
+        const command = typeof transport.command === 'string' ? transport.command.trim() : '';
+        if (!command) {
+            return { ok: false, reason: 'stdio transport is missing command.' };
+        }
+        const hasUnsupportedStdioFields = Array.isArray(transport.env_vars) && transport.env_vars.length > 0
+            || hasRecordEntries(transport.env_vars)
+            || (typeof transport.cwd === 'string' && transport.cwd.trim().length > 0);
+        if (hasUnsupportedStdioFields) {
+            return {
+                ok: false,
+                reason: 'stdio env_vars/cwd settings are configured; codex mcp add cannot preserve these fields. Enable this server manually.'
+            };
+        }
+        const args = ['mcp', 'add', server.name];
+        const envObject = normalizeStringRecord(transport.env);
+        for (const [key, value] of Object.entries(envObject)) {
+            args.push('--env', `${key}=${value}`);
+        }
+        args.push('--', command, ...normalizeStringArray(transport.args));
+        return { ok: true, args };
+    }
+    if (type === 'streamable_http') {
+        const url = typeof transport.url === 'string' ? transport.url.trim() : '';
+        if (!url) {
+            return { ok: false, reason: 'streamable_http transport is missing url.' };
+        }
+        const args = ['mcp', 'add', server.name, '--url', url];
+        const bearerTokenEnvVar = typeof transport.bearer_token_env_var === 'string' ? transport.bearer_token_env_var.trim() : '';
+        if (bearerTokenEnvVar) {
+            args.push('--bearer-token-env-var', bearerTokenEnvVar);
+        }
+        const hasUnsupportedHeaders = hasRecordEntries(transport.http_headers)
+            || hasRecordEntries(transport.env_http_headers)
+            || (Array.isArray(transport.http_headers) && transport.http_headers.length > 0)
+            || (Array.isArray(transport.env_http_headers) && transport.env_http_headers.length > 0);
+        if (hasUnsupportedHeaders) {
+            return {
+                ok: false,
+                reason: 'streamable_http headers/env_http_headers are configured; codex mcp add does not expose equivalent flags. Enable this server manually.'
+            };
+        }
+        return { ok: true, args };
+    }
+    return { ok: false, reason: `Unsupported transport type "${type || 'unknown'}".` };
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => (typeof item === 'string' ? item.trim() : ''))
+        .filter((item) => item.length > 0);
+}
+function normalizeStringRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const record = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== 'string') {
+            continue;
+        }
+        const normalizedKey = key.trim();
+        if (!normalizedKey) {
+            continue;
+        }
+        record[normalizedKey] = entry;
+    }
+    return record;
+}
+function hasRecordEntries(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return Object.keys(value).length > 0;
+}
+function dedupeNames(items) {
+    const seen = new Set();
+    const normalized = [];
+    for (const item of items) {
+        const value = item.trim();
+        if (!value || seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        normalized.push(value);
+    }
+    return normalized;
+}
+function summarizeByStatus(actions) {
+    return actions.reduce((acc, action) => {
+        acc[action.status] += 1;
+        return acc;
+    }, {
+        planned: 0,
+        enabled: 0,
+        already_enabled: 0,
+        missing: 0,
+        unsupported: 0,
+        failed: 0
+    });
+}
+async function defaultMcpCommandRunner(request) {
+    return await new Promise((resolve) => {
+        const child = spawn(request.command, request.args, {
+            env: request.env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        const timeoutMs = Math.max(1, request.timeoutMs ?? DEFAULT_MCP_COMMAND_TIMEOUT_MS);
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finalize = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeoutHandle);
+            resolve(result);
+        };
+        const timeoutHandle = setTimeout(() => {
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                if (!settled) {
+                    child.kill('SIGKILL');
+                }
+            }, 2_000).unref();
+            finalize({
+                exitCode: 124,
+                stdout,
+                stderr: `${stderr}\ncommand timed out after ${timeoutMs}ms`.trim()
+            });
+        }, timeoutMs);
+        timeoutHandle.unref();
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.once('error', (error) => {
+            finalize({
+                exitCode: 1,
+                stdout,
+                stderr: `${stderr}\n${error.message}`.trim()
+            });
+        });
+        child.once('close', (code) => {
+            finalize({
+                exitCode: typeof code === 'number' ? code : 1,
+                stdout,
+                stderr
+            });
+        });
+    });
+}
+function compactError(...values) {
+    const text = values
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .join(' | ');
+    return text.length > 0 ? text : 'no stderr/stdout captured';
+}
+function shellEscape(value) {
+    if (/^[A-Za-z0-9_./:-]+$/u.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function redactArgsForDisplay(args) {
+    const redacted = [...args];
+    for (let index = 0; index < redacted.length - 1; index += 1) {
+        if (redacted[index] !== '--env') {
+            continue;
+        }
+        const envPair = redacted[index + 1];
+        if (!envPair) {
+            continue;
+        }
+        const delimiter = envPair.indexOf('=');
+        if (delimiter <= 0) {
+            redacted[index + 1] = '<redacted>';
+            continue;
+        }
+        const key = envPair.slice(0, delimiter);
+        redacted[index + 1] = `${key}=<redacted>`;
+    }
+    for (let index = 0; index < redacted.length; index += 1) {
+        const token = redacted[index] ?? '';
+        const longWithEquals = token.match(/^--([^=\s]+)=(.+)$/u);
+        if (longWithEquals
+            && (looksSensitiveFlag(longWithEquals[1] ?? '') || looksSensitiveValue(longWithEquals[2] ?? ''))) {
+            redacted[index] = `--${longWithEquals[1]}=<redacted>`;
+            continue;
+        }
+        const longFlag = token.match(/^--([A-Za-z0-9_.-]+)$/u);
+        if (!longFlag) {
+            continue;
+        }
+        const next = redacted[index + 1];
+        if (!next || next.startsWith('-')) {
+            continue;
+        }
+        if (!looksSensitiveFlag(longFlag[1] ?? '') && !looksSensitiveValue(next)) {
+            continue;
+        }
+        redacted[index + 1] = '<redacted>';
+    }
+    // Command payload after "--" can contain arbitrary user args. Keep only the
+    // command token + first argument for operator context, redact the rest.
+    const separatorIndex = redacted.indexOf('--');
+    if (separatorIndex >= 0) {
+        const commandIndex = separatorIndex + 1;
+        if (commandIndex < redacted.length && looksSensitiveValue(redacted[commandIndex] ?? '')) {
+            redacted[commandIndex] = '<redacted>';
+        }
+        for (let index = separatorIndex + 2; index < redacted.length; index += 1) {
+            redacted[index] = '<redacted>';
+        }
+    }
+    return redacted;
+}
+function looksSensitiveFlag(flagName) {
+    const normalized = flagName.toLowerCase();
+    return /(api[-_]?key|token|secret|password|passwd|bearer|auth|cookie|credential)/u.test(normalized);
+}
+function looksSensitiveValue(value) {
+    const normalized = value.toLowerCase();
+    if (/(api[-_]?key|token|secret|password|passwd|bearer|auth|cookie|credential)/u.test(normalized)) {
+        return true;
+    }
+    return /^[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^@\s]+@/iu.test(value);
+}

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

@@ -21,7 +21,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, applyCloudExecutionToRunSummary, persistRunSummary } from './services/runSummaryWriter.js';
+import { applyHandlesToRunSummary, applyPrivacyToRunSummary, applyCloudExecutionToRunSummary, applyCloudFallbackToRunSummary, applyUsageKpiToRunSummary, 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';
@@ -33,11 +33,16 @@ import { resolveCodexCliBin } from './utils/codexCli.js';
 import { CodexCloudTaskExecutor } from '../cloud/CodexCloudTaskExecutor.js';
 import { persistPipelineExperience } from './services/pipelineExperience.js';
 import { runCloudPreflight } from './utils/cloudPreflight.js';
+import { writeJsonAtomic } from './utils/fs.js';
+import { buildAutoScoutEvidence, resolveAdvancedAutopilotDecision } from './utils/advancedAutopilot.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;
+const DEFAULT_CLOUD_STATUS_RETRY_LIMIT = 12;
+const DEFAULT_CLOUD_STATUS_RETRY_BACKOFF_MS = 1500;
+const DEFAULT_AUTO_SCOUT_TIMEOUT_MS = 4000;
 const MAX_CLOUD_PROMPT_EXPERIENCES = 3;
 const MAX_CLOUD_PROMPT_EXPERIENCE_CHARS = 320;
 function collectDelegationEnvOverrides(env = process.env) {
@@ -75,6 +80,18 @@ function readCloudNumber(raw, fallback) {
     }
     return parsed;
 }
+function allowCloudFallback(envOverrides) {
+    const raw = readCloudString(envOverrides?.CODEX_ORCHESTRATOR_CLOUD_FALLBACK) ??
+        readCloudString(process.env.CODEX_ORCHESTRATOR_CLOUD_FALLBACK);
+    if (!raw) {
+        return true;
+    }
+    const normalized = raw.toLowerCase();
+    return !['0', 'false', 'off', 'deny', 'disabled', 'never', 'strict'].includes(normalized);
+}
+function normalizeCloudFallbackIssues(issues) {
+    return issues.map((issue) => ({ code: issue.code, message: issue.message }));
+}
 function readCloudFeatureList(raw) {
     if (!raw) {
         return [];
@@ -568,8 +585,29 @@ export class CodexOrchestrator {
                 env: mergedEnv
             });
             if (!preflight.ok) {
+                if (!allowCloudFallback(options.envOverrides)) {
+                    const detail = `Cloud preflight failed and cloud fallback is disabled. ` +
+                        preflight.issues.map((issue) => issue.message).join(' ');
+                    finalizeStatus(options.manifest, 'failed', 'cloud-preflight-failed');
+                    appendSummary(options.manifest, detail);
+                    logger.error(detail);
+                    return {
+                        success: false,
+                        notes: [detail],
+                        manifest: options.manifest,
+                        manifestPath: options.paths.manifestPath,
+                        logPath: options.paths.logPath
+                    };
+                }
                 const detail = `Cloud preflight failed; falling back to mcp. ` +
                     preflight.issues.map((issue) => issue.message).join(' ');
+                options.manifest.cloud_fallback = {
+                    mode_requested: 'cloud',
+                    mode_used: 'mcp',
+                    reason: detail,
+                    issues: normalizeCloudFallbackIssues(preflight.issues),
+                    checked_at: isoTimestamp()
+                };
                 appendSummary(options.manifest, detail);
                 logger.warn(detail);
                 const fallback = await this.executePipeline({ ...options, mode: 'mcp', executionModeOverride: 'mcp' });
@@ -582,6 +620,17 @@ export class CodexOrchestrator {
         const notes = [];
         let success = true;
         manifest.guardrail_status = undefined;
+        const advancedDecision = resolveAdvancedAutopilotDecision({
+            pipelineId: pipeline.id,
+            targetMetadata: (options.target.metadata ?? null),
+            taskMetadata: (options.task.metadata ?? null),
+            env: { ...process.env, ...(envOverrides ?? {}) }
+        });
+        if (advancedDecision.enabled || advancedDecision.source !== 'default') {
+            const advancedSummary = `Advanced mode (${advancedDecision.mode}) ${advancedDecision.enabled ? 'enabled' : 'disabled'}: ${advancedDecision.reason}.`;
+            appendSummary(manifest, advancedSummary);
+            notes.push(advancedSummary);
+        }
         const persister = options.persister ??
             new ManifestPersister({
                 manifest,
@@ -604,6 +653,25 @@ export class CodexOrchestrator {
         updateHeartbeat(manifest);
         await schedulePersist({ manifest: true, heartbeat: true, force: true });
         runEvents?.runStarted(snapshotStages(manifest, pipeline), manifest.status);
+        if (advancedDecision.autoScout) {
+            const scoutOutcome = await this.runAutoScout({
+                env,
+                paths,
+                manifest,
+                mode: options.mode,
+                pipeline,
+                target: options.target,
+                task: options.task,
+                envOverrides,
+                advancedDecision
+            });
+            const scoutMessage = scoutOutcome.status === 'recorded'
+                ? `Auto scout: evidence recorded at ${scoutOutcome.path}.`
+                : `Auto scout: ${scoutOutcome.message} (non-blocking).`;
+            appendSummary(manifest, scoutMessage);
+            notes.push(scoutMessage);
+            await schedulePersist({ manifest: true, force: true });
+        }
         const heartbeatInterval = setInterval(() => {
             void pushHeartbeat(false).catch((error) => {
                 logger.warn(`Heartbeat update failed for run ${manifest.run_id}: ${error?.message ?? String(error)}`);
@@ -812,6 +880,37 @@ export class CodexOrchestrator {
         updateHeartbeat(manifest);
         await schedulePersist({ manifest: true, heartbeat: true, force: true });
         runEvents?.runStarted(snapshotStages(manifest, pipeline), manifest.status);
+        const advancedDecision = resolveAdvancedAutopilotDecision({
+            pipelineId: pipeline.id,
+            targetMetadata: (target.metadata ?? null),
+            taskMetadata: (task.metadata ?? null),
+            env: { ...process.env, ...(envOverrides ?? {}) }
+        });
+        if (advancedDecision.enabled || advancedDecision.source !== 'default') {
+            const advancedSummary = `Advanced mode (${advancedDecision.mode}) ${advancedDecision.enabled ? 'enabled' : 'disabled'}: ${advancedDecision.reason}.`;
+            appendSummary(manifest, advancedSummary);
+            notes.push(advancedSummary);
+            await schedulePersist({ manifest: true, force: true });
+        }
+        if (advancedDecision.autoScout) {
+            const scoutOutcome = await this.runAutoScout({
+                env,
+                paths,
+                manifest,
+                mode: options.mode,
+                pipeline,
+                target,
+                task,
+                envOverrides,
+                advancedDecision
+            });
+            const scoutMessage = scoutOutcome.status === 'recorded'
+                ? `Auto scout: evidence recorded at ${scoutOutcome.path}.`
+                : `Auto scout: ${scoutOutcome.message} (non-blocking).`;
+            appendSummary(manifest, scoutMessage);
+            notes.push(scoutMessage);
+            await schedulePersist({ manifest: true, force: true });
+        }
         const heartbeatInterval = setInterval(() => {
             void pushHeartbeat(false).catch((error) => {
                 logger.warn(`Heartbeat update failed for run ${manifest.run_id}: ${error?.message ?? String(error)}`);
@@ -900,6 +999,8 @@ export class CodexOrchestrator {
                     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 statusRetryLimit = readCloudNumber(envOverrides?.CODEX_CLOUD_STATUS_RETRY_LIMIT ?? process.env.CODEX_CLOUD_STATUS_RETRY_LIMIT, DEFAULT_CLOUD_STATUS_RETRY_LIMIT);
+                    const statusRetryBackoffMs = readCloudNumber(envOverrides?.CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS ?? process.env.CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS, DEFAULT_CLOUD_STATUS_RETRY_BACKOFF_MS);
                     const branch = readCloudString(envOverrides?.CODEX_CLOUD_BRANCH) ??
                         readCloudString(process.env.CODEX_CLOUD_BRANCH);
                     const enableFeatures = readCloudFeatureList(readCloudString(envOverrides?.CODEX_CLOUD_ENABLE_FEATURES) ??
@@ -922,6 +1023,8 @@ export class CodexOrchestrator {
                         pollIntervalSeconds,
                         timeoutSeconds,
                         attempts,
+                        statusRetryLimit,
+                        statusRetryBackoffMs,
                         branch,
                         enableFeatures,
                         disableFeatures,
@@ -1011,6 +1114,59 @@ export class CodexOrchestrator {
         lines.push(...buildCloudExperiencePromptLines({ manifest, pipeline, target, stage }));
         return lines.join('\n');
     }
+    async runAutoScout(params) {
+        const mergedEnv = { ...process.env, ...(params.envOverrides ?? {}) };
+        const timeoutMs = readCloudNumber(mergedEnv.CODEX_ORCHESTRATOR_AUTO_SCOUT_TIMEOUT_MS, DEFAULT_AUTO_SCOUT_TIMEOUT_MS);
+        const work = async () => {
+            const cloudEnvironmentId = resolveCloudEnvironmentId(params.task, params.target, params.envOverrides);
+            const cloudBranch = readCloudString(params.envOverrides?.CODEX_CLOUD_BRANCH) ??
+                readCloudString(process.env.CODEX_CLOUD_BRANCH);
+            const cloudRequested = params.mode === 'cloud' || params.manifest.cloud_fallback?.mode_requested === 'cloud';
+            const evidence = buildAutoScoutEvidence({
+                taskId: params.manifest.task_id,
+                pipelineId: params.pipeline.id,
+                targetId: params.target.id,
+                targetDescription: params.target.description,
+                executionMode: params.mode,
+                cloudRequested,
+                advanced: params.advancedDecision,
+                cloudEnvironmentId,
+                cloudBranch,
+                env: mergedEnv,
+                generatedAt: isoTimestamp()
+            });
+            const evidencePath = join(params.paths.runDir, 'auto-scout.json');
+            await writeJsonAtomic(evidencePath, evidence);
+            return { status: 'recorded', path: relativeToRepo(params.env, evidencePath) };
+        };
+        try {
+            let timeoutHandle = null;
+            const timeoutPromise = new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => {
+                    resolve({
+                        status: 'timeout',
+                        message: `timed out after ${Math.round(timeoutMs / 1000)}s`
+                    });
+                }, timeoutMs);
+                timeoutHandle.unref?.();
+            });
+            const workPromise = work().catch((error) => ({
+                status: 'error',
+                message: error?.message ?? String(error)
+            }));
+            const result = await Promise.race([workPromise, timeoutPromise]);
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            return result;
+        }
+        catch (error) {
+            return {
+                status: 'error',
+                message: error?.message ?? String(error)
+            };
+        }
+    }
     async performRunLifecycle(context) {
         const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides, executionModeOverride } = context;
         let latestPipelineResult = null;
@@ -1085,6 +1241,8 @@ export class CodexOrchestrator {
         applyHandlesToRunSummary(runSummary, manifest);
         applyPrivacyToRunSummary(runSummary, manifest);
         applyCloudExecutionToRunSummary(runSummary, manifest);
+        applyCloudFallbackToRunSummary(runSummary, manifest);
+        applyUsageKpiToRunSummary(runSummary, manifest);
         this.controlPlane.applyControlPlaneToRunSummary(runSummary, controlPlaneResult);
         await persistRunSummary(env, paths, manifest, runSummary, persister);
         context.runEvents?.runCompleted({
@@ -1137,7 +1295,8 @@ export class CodexOrchestrator {
             activity,
             commands: manifest.commands,
             child_runs: manifest.child_runs,
-            cloud_execution: manifest.cloud_execution ?? null
+            cloud_execution: manifest.cloud_execution ?? null,
+            cloud_fallback: manifest.cloud_fallback ?? null
         };
     }
     renderStatus(manifest, activity) {