@kbediako/codex-orchestrator 0.1.36 → 0.1.37

package/README.md

@@ -307,7 +307,7 @@ codex-orchestrator devtools setup
 - `codex-orchestrator mcp enable --servers <csv> --yes` — enable specific disabled MCP servers from existing Codex config entries.
 - `codex-orchestrator self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
-- `npm run pack:smoke` — maintainer smoke gate for packaged downstream behavior (tarball install + review/skill checks).
+- `npm run pack:smoke` — maintainer smoke gate for packaged downstream behavior (tarball install + review/skill checks). Core lane runs it on downstream-facing diffs; `.github/workflows/pack-smoke-backstop.yml` runs a weekly `main` backstop.
 
 ## What ships in the npm release
 

package/dist/bin/codex-orchestrator.js

@@ -393,6 +393,23 @@ function resolveExecutionModeFlag(flags) {
     }
     return normalized;
 }
+function resolveRuntimeModeFlag(flags) {
+    if (flags['runtime-mode'] === true) {
+        throw new Error('--runtime-mode requires a value. Expected one of: cli, appserver.');
+    }
+    const rawMode = readStringFlag(flags, 'runtime-mode');
+    if (flags['runtime-mode'] !== undefined && !rawMode) {
+        throw new Error('--runtime-mode requires a non-empty value. Expected one of: cli, appserver.');
+    }
+    if (!rawMode) {
+        return undefined;
+    }
+    const normalized = rawMode.toLowerCase();
+    if (normalized !== 'cli' && normalized !== 'appserver') {
+        throw new Error('Invalid --runtime-mode value. Expected one of: cli, appserver.');
+    }
+    return normalized;
+}
 function normalizeRlmMultiAgentValue(raw) {
     if (raw === true) {
         return 'enabled';
@@ -580,6 +597,7 @@ async function handleStart(orchestrator, rawArgs) {
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const executionMode = resolveExecutionModeFlag(flags);
+    const runtimeMode = resolveRuntimeModeFlag(flags);
     applyRepoConfigRequiredPolicy(flags);
     const autoIssueLogEnabled = resolveAutoIssueLogEnabled(flags);
     if (pipelineId === 'rlm') {
@@ -607,6 +625,7 @@ async function handleStart(orchestrator, rawArgs) {
                 approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
                 targetStageId: resolveTargetStageId(flags),
                 executionMode,
+                runtimeMode,
                 runEvents
             });
             const issueLogCapture = result.manifest.status !== 'succeeded'
@@ -618,6 +637,9 @@ async function handleStart(orchestrator, rawArgs) {
                 })
                 : { issueLog: null, issueLogError: null };
             emitRunOutput(result, format, 'Run started', issueLogCapture);
+            if (result.manifest.status === 'failed' || result.manifest.status === 'cancelled') {
+                process.exitCode = 1;
+            }
             if (result.manifest.status === 'succeeded' && result.manifest.pipeline_id !== 'rlm') {
                 await maybeEmitRunAdoptionHint({
                     format,
@@ -640,6 +662,7 @@ async function handleFrontendTest(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const devtools = Boolean(flags['devtools']);
+    const runtimeMode = resolveRuntimeModeFlag(flags);
     applyRepoConfigRequiredPolicy(flags);
     if (positionals.length > 0) {
         console.error(`[frontend-test] ignoring extra arguments: ${positionals.join(' ')}`);
@@ -656,9 +679,13 @@ async function handleFrontendTest(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),
+                runtimeMode,
                 runEvents
             });
             emitRunOutput(result, format, 'Run started');
+            if (result.manifest.status === 'failed' || result.manifest.status === 'cancelled') {
+                process.exitCode = 1;
+            }
         });
     }
     finally {
@@ -683,6 +710,7 @@ async function handleFlow(orchestrator, rawArgs) {
     }
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const executionMode = resolveExecutionModeFlag(flags);
+    const runtimeMode = resolveRuntimeModeFlag(flags);
     applyRepoConfigRequiredPolicy(flags);
     const autoIssueLogEnabled = resolveAutoIssueLogEnabled(flags);
     const taskId = typeof flags['task'] === 'string' ? flags['task'] : undefined;
@@ -699,6 +727,7 @@ async function handleFlow(orchestrator, rawArgs) {
                 approvalPolicy,
                 targetStageId: docsReviewTargetStageId,
                 executionMode,
+                runtimeMode,
                 runEvents
             });
             const docsPayload = toRunOutputPayload(docsReviewResult);
@@ -744,6 +773,7 @@ async function handleFlow(orchestrator, rawArgs) {
                 approvalPolicy,
                 targetStageId: implementationGateTargetStageId,
                 executionMode,
+                runtimeMode,
                 runEvents
             });
             const implementationPayload = toRunOutputPayload(implementationGateResult);
@@ -886,6 +916,7 @@ async function handleRlm(orchestrator, rawArgs) {
         printRlmHelp();
         return;
     }
+    const runtimeMode = resolveRuntimeModeFlag(flags);
     applyRepoConfigRequiredPolicy(flags);
     const goalFromArgs = positionals.length > 0 ? positionals.join(' ') : undefined;
     const goal = goalFromArgs ?? readStringFlag(flags, 'goal') ?? process.env.RLM_GOAL?.trim();
@@ -921,6 +952,7 @@ async function handleRlm(orchestrator, rawArgs) {
             taskId,
             parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
             approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
+            runtimeMode,
             runEvents
         });
         emitRunOutput(startResult, 'text', 'Run started');
@@ -949,6 +981,7 @@ async function handleResume(orchestrator, rawArgs) {
         printResumeHelp();
         return;
     }
+    const runtimeMode = resolveRuntimeModeFlag(flags);
     applyRepoConfigRequiredPolicy(flags);
     const runId = (flags['run'] ?? positionals[0]);
     if (!runId) {
@@ -962,6 +995,7 @@ async function handleResume(orchestrator, rawArgs) {
             actor: typeof flags['actor'] === 'string' ? flags['actor'] : undefined,
             reason: typeof flags['reason'] === 'string' ? flags['reason'] : undefined,
             targetStageId: resolveTargetStageId(flags),
+            runtimeMode,
             runEvents
         });
         emitRunOutput(result, format, 'Run resumed');
@@ -1034,6 +1068,13 @@ function emitRunOutput(result, format, label, issueLogCapture = { issueLog: null
     console.log(`Status: ${payload.status}`);
     console.log(`Manifest: ${payload.manifest}`);
     console.log(`Log: ${payload.log_path}`);
+    if (payload.runtime_mode) {
+        console.log(`Runtime: ${payload.runtime_mode}${payload.runtime_mode_requested ? ` (requested ${payload.runtime_mode_requested})` : ''}` +
+            (payload.runtime_provider ? ` via ${payload.runtime_provider}` : ''));
+        if (payload.runtime_fallback?.occurred) {
+            console.log(`Runtime fallback: ${payload.runtime_fallback.code ?? 'runtime-fallback'} (${payload.runtime_fallback.reason ?? 'n/a'})`);
+        }
+    }
     if (payload.cloud_fallback_reason) {
         console.log(`Cloud fallback: ${payload.cloud_fallback_reason}`);
     }
@@ -1060,6 +1101,10 @@ function toRunOutputPayload(result, issueLogCapture = { issueLog: null, issueLog
         manifest: `${result.manifest.artifact_root}/manifest.json`,
         log_path: result.manifest.log_path,
         summary: result.manifest.summary ?? null,
+        runtime_mode_requested: result.manifest.runtime_mode_requested ?? null,
+        runtime_mode: result.manifest.runtime_mode ?? null,
+        runtime_provider: result.manifest.runtime_provider ?? null,
+        runtime_fallback: result.manifest.runtime_fallback ?? null,
         cloud_fallback_reason: result.manifest.cloud_fallback?.reason ?? null,
         issue_log: issueLogCapture.issueLog,
         issue_log_error: issueLogCapture.issueLogError
@@ -1998,6 +2043,7 @@ Commands:
     --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.
+    --runtime-mode <cli|appserver>  Force runtime mode for this run and child subpipelines.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
     --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
     --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
@@ -2013,6 +2059,7 @@ Commands:
 
   rlm "<goal>"              Run RLM loop until validator passes.
     --task <id>             Override task identifier.
+    --runtime-mode <cli|appserver>  Force runtime mode for this run.
     --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --multi-agent [auto|true|false]  Preferred alias for multi-agent collab subagents (implies symbolic mode).
     --collab [auto|true|false]  Legacy alias for --multi-agent.
@@ -2028,6 +2075,7 @@ Commands:
   frontend-test             Run frontend testing pipeline.
     --devtools             Enable Chrome DevTools MCP for this run.
     --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+    --runtime-mode <cli|appserver>  Force runtime mode for this run.
     --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --parent-run <id>       Link run to parent run id.
     --approval-policy <p>   Record approval policy metadata.
@@ -2043,6 +2091,7 @@ Commands:
     --format json           Emit machine-readable output summary for both runs.
     --execution-mode <mcp|cloud>  Force execution mode for both runs.
     --cloud                 Shortcut for --execution-mode cloud.
+    --runtime-mode <cli|appserver>  Force runtime mode for both runs.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
     --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
     --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
@@ -2058,6 +2107,7 @@ Commands:
       --base <branch>       Review against base branch.
       --commit <sha>        Review specific commit.
       --non-interactive     Force non-interactive review behavior.
+      --runtime-mode <cli|appserver>  Force runtime mode for the underlying codex review call.
       --auto-issue-log [true|false]  Auto-capture issue bundle on review failure.
       --disable-delegation-mcp [true|false]  Disable delegation MCP for this review.
 
@@ -2080,6 +2130,7 @@ Commands:
     --actor <name>          Record who resumed the run.
     --reason <text>         Record why the run was resumed.
     --target <stage-id>     Override stage selection before resuming (alias: --target-stage).
+    --runtime-mode <cli|appserver>  Force runtime mode before resuming.
     --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --format json           Emit machine-readable output.
     --interactive | --ui    Enable read-only HUD when running in a TTY.
@@ -2226,6 +2277,7 @@ Options:
   --actor <name>        Record who resumed the run.
   --reason <text>       Record why the run was resumed.
   --target <stage-id>   Override stage selection before resuming.
+  --runtime-mode <cli|appserver>  Force runtime mode before resuming.
   --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
   --format json         Emit machine-readable output.
   --interactive | --ui  Enable read-only HUD when running in a TTY.
@@ -2281,6 +2333,7 @@ function printRlmHelp() {
 Options:
   --goal "<goal>"         Alternate way to set the goal (positional is preferred).
   --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+  --runtime-mode <cli|appserver>  Force runtime mode for this run.
   --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
   --multi-agent [auto|true|false]  Preferred alias for multi-agent collab subagents (implies symbolic mode).
   --collab [auto|true|false]  Legacy alias for --multi-agent.
@@ -2315,6 +2368,7 @@ Options:
   --format json             Emit machine-readable output for both runs.
   --execution-mode <mcp|cloud>  Force execution mode for both runs.
   --cloud                   Shortcut for --execution-mode cloud.
+  --runtime-mode <cli|appserver>  Force runtime mode for both runs.
   --target <stage-id>       Focus plan/build metadata (applies where the stage exists).
   --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
   --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
@@ -2344,6 +2398,7 @@ Common options:
   --commit <sha>                   Review a specific commit.
   --title "<text>"                 Optional review title in the prompt.
   --non-interactive                Force non-interactive behavior.
+  --runtime-mode <cli|appserver>   Force runtime mode for the underlying codex review call.
   --auto-issue-log [true|false]    Auto-capture issue bundle on review failure.
   --disable-delegation-mcp [true|false]  Disable delegation MCP for this review.
   --enable-delegation-mcp [true|false]   Legacy delegation MCP toggle (disable via false).
@@ -2373,6 +2428,7 @@ Options:
   --format json             Emit machine-readable output.
   --execution-mode <mcp|cloud>  Force execution mode for this run.
   --cloud                   Shortcut for --execution-mode cloud.
+  --runtime-mode <cli|appserver>  Force runtime mode for this run.
   --target <stage-id>       Focus plan/build metadata on a specific stage.
   --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
   --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).

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

@@ -55,11 +55,17 @@ function normalizeUserConfig(config, source) {
     if (!config) {
         return null;
     }
+    const runtimeMode = normalizeRuntimeMode(config.runtimeMode);
     const stageSets = normalizeStageSets(config.stageSets);
     const pipelines = Array.isArray(config.pipelines)
         ? config.pipelines.map((pipeline) => expandPipelineStages(pipeline, stageSets))
         : config.pipelines;
-    return { pipelines, defaultPipeline: config.defaultPipeline, source };
+    return {
+        pipelines,
+        defaultPipeline: config.defaultPipeline,
+        runtimeMode,
+        source
+    };
 }
 async function readConfig(configPath) {
     try {
@@ -111,3 +117,13 @@ function expandPipelineStages(pipeline, stageSets) {
 function isStageSetRef(stage) {
     return stage.kind === 'stage-set';
 }
+function normalizeRuntimeMode(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'cli' || normalized === 'appserver') {
+        return normalized;
+    }
+    throw new Error(`Invalid codex.orchestrator.json runtimeMode "${value}". Expected one of: cli, appserver.`);
+}

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

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { logger } from '../logger.js';
-import { resolveCodexCommand } from './utils/devtools.js';
+import { createRuntimeCodexCommandContext, formatRuntimeSelectionSummary, parseRuntimeMode, resolveRuntimeCodexCommand } from './runtime/index.js';
 const DEFAULT_PROMPT = [
     'You are running frontend testing for the current project.',
     '',
@@ -37,9 +37,9 @@ export async function loadFrontendTestingPrompt(env = process.env) {
     }
     return DEFAULT_PROMPT;
 }
-export function resolveFrontendTestingCommand(prompt, env = process.env) {
+export function resolveFrontendTestingCommand(prompt, context) {
     const args = ['exec', prompt];
-    return resolveCodexCommand(args, env);
+    return resolveRuntimeCodexCommand(args, context);
 }
 function envFlagEnabled(value) {
     if (!value) {
@@ -59,16 +59,21 @@ function shouldForceNonInteractive(env) {
 }
 export async function runFrontendTesting(env = process.env) {
     const prompt = await loadFrontendTestingPrompt(env);
-    const { command, args } = resolveFrontendTestingCommand(prompt, env);
+    const repoRoot = typeof env.CODEX_ORCHESTRATOR_ROOT === 'string' && env.CODEX_ORCHESTRATOR_ROOT.trim().length > 0
+        ? env.CODEX_ORCHESTRATOR_ROOT.trim()
+        : process.cwd();
+    const runtimeContext = await resolveFrontendTestingRuntimeContext(env, repoRoot);
+    logger.info(`[frontend-testing-runtime] ${formatRuntimeSelectionSummary(runtimeContext.runtime)}`);
+    const { command, args } = resolveFrontendTestingCommand(prompt, runtimeContext);
     const nonInteractive = shouldForceNonInteractive(env);
-    const childEnv = { ...process.env, ...env };
+    const childEnv = { ...process.env, ...env, ...runtimeContext.env };
     if (nonInteractive) {
         childEnv.CODEX_NON_INTERACTIVE = childEnv.CODEX_NON_INTERACTIVE ?? '1';
         childEnv.CODEX_NO_INTERACTIVE = childEnv.CODEX_NO_INTERACTIVE ?? '1';
         childEnv.CODEX_INTERACTIVE = childEnv.CODEX_INTERACTIVE ?? '0';
     }
     const stdio = nonInteractive ? ['ignore', 'inherit', 'inherit'] : 'inherit';
-    const child = spawn(command, args, { stdio, env: childEnv });
+    const child = spawn(command, args, { stdio, env: childEnv, cwd: repoRoot });
     await new Promise((resolvePromise, reject) => {
         child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
         child.once('exit', (code) => {
@@ -81,6 +86,19 @@ export async function runFrontendTesting(env = process.env) {
         });
     });
 }
+async function resolveFrontendTestingRuntimeContext(env, repoRoot) {
+    const requestedMode = parseRuntimeMode(env.CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE ?? env.CODEX_ORCHESTRATOR_RUNTIME_MODE ?? null);
+    const runId = typeof env.CODEX_ORCHESTRATOR_RUN_ID === 'string' && env.CODEX_ORCHESTRATOR_RUN_ID.trim().length > 0
+        ? env.CODEX_ORCHESTRATOR_RUN_ID.trim()
+        : `frontend-testing-${Date.now()}`;
+    return await createRuntimeCodexCommandContext({
+        requestedMode,
+        executionMode: 'mcp',
+        repoRoot,
+        env: { ...process.env, ...env },
+        runId
+    });
+}
 async function main() {
     await runFrontendTesting();
 }

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, applyCloudFallbackToRunSummary, applyUsageKpiToRunSummary, persistRunSummary } from './services/runSummaryWriter.js';
+import { applyRuntimeToRunSummary, 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 { formatRepoConfigRequiredError, isRepoConfigRequired } from './config/repoConfigPolicy.js';
@@ -35,6 +35,7 @@ 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 { resolveRuntimeMode, resolveRuntimeSelection } from './runtime/index.js';
 import { buildAutoScoutEvidence, resolveAdvancedAutopilotDecision } from './utils/advancedAutopilot.js';
 const resolveBaseEnvironment = () => normalizeEnvironmentPaths(resolveEnvironmentPaths());
 const CONFIG_OVERRIDE_ENV_KEYS = ['CODEX_CONFIG_OVERRIDES', 'CODEX_MCP_CONFIG_OVERRIDES'];
@@ -233,6 +234,11 @@ export class CodexOrchestrator {
             planTargetFallback: null
         });
         const runId = generateRunId();
+        const runtimeModeResolution = resolveRuntimeMode({
+            flag: options.runtimeMode,
+            env: { ...process.env, ...(preparation.envOverrides ?? {}) },
+            configDefault: preparation.runtimeModeDefault
+        });
         const { manifest, paths } = await bootstrapManifest(runId, {
             env: preparation.env,
             pipeline: preparation.pipeline,
@@ -241,6 +247,7 @@ export class CodexOrchestrator {
             approvalPolicy: options.approvalPolicy ?? null,
             planTargetId: preparation.planPreview?.targetId ?? preparation.plannerTargetId ?? null
         });
+        this.applyRequestedRuntimeMode(manifest, runtimeModeResolution.mode);
         if (preparation.configNotice) {
             appendSummary(manifest, preparation.configNotice);
         }
@@ -305,6 +312,8 @@ export class CodexOrchestrator {
                 onEventEntry,
                 persister,
                 envOverrides: preparation.envOverrides,
+                runtimeModeRequested: runtimeModeResolution.mode,
+                runtimeModeSource: runtimeModeResolution.source,
                 executionModeOverride: options.executionMode
             });
         }
@@ -362,6 +371,7 @@ export class CodexOrchestrator {
         const preparation = await prepareRun({
             baseEnv: actualEnv,
             pipeline,
+            runtimeModeDefault: userConfig?.runtimeMode ?? null,
             resolver,
             taskIdOverride: manifest.task_id,
             targetStageId: options.targetStageId,
@@ -371,6 +381,14 @@ export class CodexOrchestrator {
         if (preparation.configNotice && !(manifest.summary ?? '').includes(preparation.configNotice)) {
             appendSummary(manifest, preparation.configNotice);
         }
+        const runtimeModeResolution = resolveRuntimeMode({
+            flag: options.runtimeMode,
+            env: { ...process.env, ...(preparation.envOverrides ?? {}) },
+            configDefault: preparation.runtimeModeDefault,
+            manifestMode: manifest.runtime_mode_requested ?? manifest.runtime_mode ?? null,
+            preferManifest: true
+        });
+        this.applyRequestedRuntimeMode(manifest, runtimeModeResolution.mode);
         manifest.plan_target_id = preparation.planPreview?.targetId ?? preparation.plannerTargetId ?? null;
         const persister = new ManifestPersister({
             manifest,
@@ -433,7 +451,9 @@ export class CodexOrchestrator {
                 eventStream: stream,
                 onEventEntry,
                 persister,
-                envOverrides: preparation.envOverrides
+                envOverrides: preparation.envOverrides,
+                runtimeModeRequested: runtimeModeResolution.mode,
+                runtimeModeSource: runtimeModeResolution.source
             });
         }
         finally {
@@ -582,21 +602,52 @@ export class CodexOrchestrator {
         return Boolean(task.metadata?.execution?.parallel);
     }
     async executePipeline(options) {
+        const baseEnvOverrides = { ...(options.envOverrides ?? {}) };
+        const mergedEnv = { ...process.env, ...baseEnvOverrides };
+        let runtimeSelection;
+        try {
+            runtimeSelection = await resolveRuntimeSelection({
+                requestedMode: options.runtimeModeRequested,
+                source: options.runtimeModeSource,
+                executionMode: options.mode,
+                repoRoot: options.env.repoRoot,
+                env: mergedEnv,
+                runId: options.manifest.run_id
+            });
+        }
+        catch (error) {
+            const detail = `Runtime selection failed: ${error?.message ?? String(error)}`;
+            finalizeStatus(options.manifest, 'failed', 'runtime-selection-failed');
+            appendSummary(options.manifest, detail);
+            logger.error(detail);
+            return {
+                success: false,
+                notes: [detail],
+                manifest: options.manifest,
+                manifestPath: options.paths.manifestPath,
+                logPath: options.paths.logPath
+            };
+        }
+        this.applyRuntimeSelection(options.manifest, runtimeSelection);
+        const effectiveEnvOverrides = {
+            ...baseEnvOverrides,
+            ...runtimeSelection.env_overrides
+        };
+        const effectiveMergedEnv = { ...process.env, ...effectiveEnvOverrides };
         if (options.mode === 'cloud') {
-            const environmentId = resolveCloudEnvironmentId(options.task, options.target, options.envOverrides);
-            const branch = readCloudString(options.envOverrides?.CODEX_CLOUD_BRANCH) ??
+            const environmentId = resolveCloudEnvironmentId(options.task, options.target, effectiveEnvOverrides);
+            const branch = readCloudString(effectiveEnvOverrides.CODEX_CLOUD_BRANCH) ??
                 readCloudString(process.env.CODEX_CLOUD_BRANCH);
-            const mergedEnv = { ...process.env, ...(options.envOverrides ?? {}) };
-            const codexBin = resolveCodexCliBin(mergedEnv);
+            const codexBin = resolveCodexCliBin(effectiveMergedEnv);
             const preflight = await runCloudPreflight({
                 repoRoot: options.env.repoRoot,
                 codexBin,
                 environmentId,
                 branch,
-                env: mergedEnv
+                env: effectiveMergedEnv
             });
             if (!preflight.ok) {
-                if (!allowCloudFallback(options.envOverrides)) {
+                if (!allowCloudFallback(effectiveEnvOverrides)) {
                     const detail = `Cloud preflight failed and cloud fallback is disabled. ` +
                         preflight.issues.map((issue) => issue.message).join(' ');
                     finalizeStatus(options.manifest, 'failed', 'cloud-preflight-failed');
@@ -621,21 +672,35 @@ export class CodexOrchestrator {
                 };
                 appendSummary(options.manifest, detail);
                 logger.warn(detail);
-                const fallback = await this.executePipeline({ ...options, mode: 'mcp', executionModeOverride: 'mcp' });
+                const fallback = await this.executePipeline({
+                    ...options,
+                    mode: 'mcp',
+                    executionModeOverride: 'mcp',
+                    runtimeModeRequested: runtimeSelection.selected_mode,
+                    runtimeModeSource: runtimeSelection.source,
+                    envOverrides: effectiveEnvOverrides
+                });
                 fallback.notes.unshift(detail);
                 return fallback;
             }
-            return await this.executeCloudPipeline(options);
+            return await this.executeCloudPipeline({ ...options, envOverrides: effectiveEnvOverrides });
         }
-        const { env, pipeline, manifest, paths, runEvents, envOverrides } = options;
+        const { env, pipeline, manifest, paths, runEvents } = options;
         const notes = [];
         let success = true;
         manifest.guardrail_status = undefined;
+        if (runtimeSelection.fallback.occurred) {
+            const fallbackCode = runtimeSelection.fallback.code ?? 'runtime-fallback';
+            const fallbackReason = runtimeSelection.fallback.reason ?? 'runtime fallback occurred';
+            const fallbackSummary = `Runtime fallback (${fallbackCode}): ${fallbackReason}`;
+            appendSummary(manifest, fallbackSummary);
+            notes.push(fallbackSummary);
+        }
         const advancedDecision = resolveAdvancedAutopilotDecision({
             pipelineId: pipeline.id,
             targetMetadata: (options.target.metadata ?? null),
             taskMetadata: (options.task.metadata ?? null),
-            env: { ...process.env, ...(envOverrides ?? {}) }
+            env: effectiveMergedEnv
         });
         if (advancedDecision.enabled || advancedDecision.source !== 'default') {
             const advancedSummary = `Advanced mode (${advancedDecision.mode}) ${advancedDecision.enabled ? 'enabled' : 'disabled'}: ${advancedDecision.reason}.`;
@@ -673,7 +738,7 @@ export class CodexOrchestrator {
                 pipeline,
                 target: options.target,
                 task: options.task,
-                envOverrides,
+                envOverrides: effectiveEnvOverrides,
                 advancedDecision
             });
             const scoutMessage = scoutOutcome.status === 'recorded'
@@ -719,7 +784,9 @@ export class CodexOrchestrator {
                             index: entry.index,
                             events: runEvents,
                             persister,
-                            envOverrides
+                            envOverrides: effectiveEnvOverrides,
+                            runtimeMode: runtimeSelection.selected_mode,
+                            runtimeSessionId: runtimeSelection.runtime_session_id
                         });
                         notes.push(`${stage.title}: ${result.summary}`);
                         const updatedEntry = manifest.commands[i];
@@ -769,7 +836,8 @@ export class CodexOrchestrator {
                             pipelineId: stage.pipeline,
                             parentRunId: manifest.run_id,
                             format: 'json',
-                            executionMode: options.executionModeOverride
+                            executionMode: options.executionModeOverride,
+                            runtimeMode: options.runtimeModeRequested
                         });
                         entry.completed_at = isoTimestamp();
                         entry.sub_run_id = child.manifest.run_id;
@@ -1184,7 +1252,7 @@ export class CodexOrchestrator {
         }
     }
     async performRunLifecycle(context) {
-        const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides, executionModeOverride } = context;
+        const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides, runtimeModeRequested, runtimeModeSource, executionModeOverride } = context;
         let latestPipelineResult = null;
         const executingByKey = new Map();
         const executePipeline = async (input) => {
@@ -1199,6 +1267,8 @@ export class CodexOrchestrator {
                 manifest,
                 paths,
                 mode: input.mode,
+                runtimeModeRequested,
+                runtimeModeSource,
                 executionModeOverride,
                 target: input.target,
                 task: taskContext,
@@ -1254,6 +1324,7 @@ export class CodexOrchestrator {
             persister
         });
         this.scheduler.applySchedulerToRunSummary(runSummary, schedulerPlan);
+        applyRuntimeToRunSummary(runSummary, manifest);
         applyHandlesToRunSummary(runSummary, manifest);
         applyPrivacyToRunSummary(runSummary, manifest);
         applyCloudExecutionToRunSummary(runSummary, manifest);
@@ -1283,6 +1354,25 @@ export class CodexOrchestrator {
             });
         });
     }
+    applyRequestedRuntimeMode(manifest, mode) {
+        manifest.runtime_mode_requested = mode;
+        manifest.runtime_mode = mode;
+        manifest.runtime_provider = mode === 'appserver' ? 'AppServerRuntimeProvider' : 'CliRuntimeProvider';
+        manifest.runtime_fallback = {
+            occurred: false,
+            code: null,
+            reason: null,
+            from_mode: null,
+            to_mode: null,
+            checked_at: isoTimestamp()
+        };
+    }
+    applyRuntimeSelection(manifest, selection) {
+        manifest.runtime_mode_requested = selection.requested_mode;
+        manifest.runtime_mode = selection.selected_mode;
+        manifest.runtime_provider = selection.provider;
+        manifest.runtime_fallback = selection.fallback;
+    }
     async validateResumeToken(paths, manifest, provided) {
         let stored = manifest.resume_token;
         if (!stored) {
@@ -1311,6 +1401,10 @@ export class CodexOrchestrator {
             activity,
             commands: manifest.commands,
             child_runs: manifest.child_runs,
+            runtime_mode_requested: manifest.runtime_mode_requested,
+            runtime_mode: manifest.runtime_mode,
+            runtime_provider: manifest.runtime_provider,
+            runtime_fallback: manifest.runtime_fallback ?? null,
             cloud_execution: manifest.cloud_execution ?? null,
             cloud_fallback: manifest.cloud_fallback ?? null
         };
@@ -1321,6 +1415,15 @@ 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.runtime_mode || manifest.runtime_mode_requested || manifest.runtime_provider) {
+            const selectedMode = manifest.runtime_mode ?? 'unknown';
+            logger.info(`Runtime: ${selectedMode}${manifest.runtime_mode_requested ? ` (requested ${manifest.runtime_mode_requested})` : ''}` +
+                (manifest.runtime_provider ? ` via ${manifest.runtime_provider}` : ''));
+        }
+        if (manifest.runtime_fallback?.occurred) {
+            const fallbackCode = manifest.runtime_fallback.code ?? 'runtime-fallback';
+            logger.info(`Runtime fallback: ${fallbackCode} — ${manifest.runtime_fallback.reason ?? 'n/a'}`);
+        }
         if (activity.observed_at) {
             const staleSuffix = activity.stale === null ? '' : activity.stale ? ' [stale]' : ' [active]';
             const sourceLabel = activity.observed_source ? ` via ${activity.observed_source}` : '';