@kbediako/codex-orchestrator 0.1.36 → 0.1.37

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

@@ -7,7 +7,7 @@ import { promisify } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 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';
 import { detectValidator } from './rlm/validator.js';
 import { buildRlmPrompt } from './rlm/prompt.js';
 import { runRlmLoop } from './rlm/runner.js';
@@ -57,6 +57,8 @@ const COLLAB_FEATURE_CANONICAL = 'multi_agent';
 const COLLAB_FEATURE_LEGACY = 'collab';
 const COLLAB_ROLE_TAG_PATTERN = /^\s*\[(?:agent_type|role)\s*:\s*([a-z0-9._-]+)\]/i;
 const COLLAB_ROLE_TOKEN_PATTERN = /^[a-z0-9._-]+$/;
+let runtimeCodexContextPromise = null;
+let runtimeCodexContextLogged = false;
 function parseArgs(argv) {
     const parsed = {};
     for (let i = 0; i < argv.length; i += 1) {
@@ -332,8 +334,9 @@ async function runCodexAgent(input, env, repoRoot, nonInteractive, subagentsEnab
     return { output };
 }
 async function runCodexExec(args, env, repoRoot, nonInteractive, subagentsEnabled, mirrorOutput) {
-    const { command, args: resolvedArgs } = resolveCodexCommand(args, env);
-    const childEnv = { ...process.env, ...env };
+    const runtimeContext = await resolveRlmRuntimeCodexContext(env, repoRoot);
+    const { command, args: resolvedArgs } = resolveRuntimeCodexCommand(args, runtimeContext);
+    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';
@@ -370,6 +373,27 @@ async function runCodexExec(args, env, repoRoot, nonInteractive, subagentsEnable
     });
     return { stdout, stderr };
 }
+async function resolveRlmRuntimeCodexContext(env, repoRoot) {
+    if (!runtimeCodexContextPromise) {
+        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()
+            : `rlm-${Date.now()}`;
+        runtimeCodexContextPromise = createRuntimeCodexCommandContext({
+            requestedMode,
+            executionMode: 'mcp',
+            repoRoot,
+            env: { ...process.env, ...env },
+            runId
+        });
+    }
+    const runtimeContext = await runtimeCodexContextPromise;
+    if (!runtimeCodexContextLogged) {
+        logger.info(`[rlm-runtime] ${formatRuntimeSelectionSummary(runtimeContext.runtime)}`);
+        runtimeCodexContextLogged = true;
+    }
+    return runtimeContext;
+}
 async function runCodexCompletion(prompt, env, repoRoot, nonInteractive, subagentsEnabled, mirrorOutput) {
     const { stdout, stderr } = await runCodexExec(['exec', prompt], env, repoRoot, nonInteractive, subagentsEnabled, mirrorOutput);
     return [stdout.trim(), stderr.trim()].filter(Boolean).join('\n');

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

@@ -13,6 +13,19 @@ const HEARTBEAT_INTERVAL_SECONDS = 5;
 const HEARTBEAT_STALE_AFTER_SECONDS = 30;
 const MAX_ERROR_DETAIL_CHARS = 8 * 1024;
 const DEFAULT_MIN_EXPERIENCE_REWARD = 0.1;
+function createDefaultRuntimeFallback() {
+    return {
+        occurred: false,
+        code: null,
+        reason: null,
+        from_mode: null,
+        to_mode: null,
+        checked_at: isoTimestamp()
+    };
+}
+function runtimeProviderForMode(mode) {
+    return mode === 'appserver' ? 'AppServerRuntimeProvider' : 'CliRuntimeProvider';
+}
 export async function bootstrapManifest(runId, options) {
     const { env, pipeline, parentRunId = null, taskSlug, approvalPolicy = null } = options;
     const paths = resolveRunPaths(env, runId);
@@ -57,6 +70,10 @@ export async function bootstrapManifest(runId, options) {
         instructions_sources: [],
         prompt_packs: [],
         guardrails_required: pipeline.guardrailsRequired !== false,
+        runtime_mode_requested: 'appserver',
+        runtime_mode: 'appserver',
+        runtime_provider: runtimeProviderForMode('appserver'),
+        runtime_fallback: createDefaultRuntimeFallback(),
         cloud_execution: null,
         cloud_fallback: null,
         learning: {
@@ -192,6 +209,8 @@ export function resetForResume(manifest) {
     manifest.status = 'in_progress';
     manifest.status_detail = 'resuming';
     manifest.guardrail_status = undefined;
+    manifest.runtime_provider = runtimeProviderForMode(manifest.runtime_mode);
+    manifest.runtime_fallback = createDefaultRuntimeFallback();
     manifest.cloud_execution = null;
     manifest.cloud_fallback = null;
 }

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

@@ -0,0 +1,39 @@
+import { resolveCodexCommand } from '../utils/devtools.js';
+import { resolveRuntimeMode } from './mode.js';
+import { resolveRuntimeSelection } from './provider.js';
+export async function createRuntimeCodexCommandContext(options) {
+    const runtimeEnv = options.env ?? process.env;
+    const modeResolution = resolveRuntimeMode({
+        flag: options.requestedMode,
+        env: runtimeEnv,
+        configDefault: options.configDefault
+    });
+    const runtime = await resolveRuntimeSelection({
+        requestedMode: modeResolution.mode,
+        source: modeResolution.source,
+        executionMode: options.executionMode ?? 'mcp',
+        repoRoot: options.repoRoot,
+        env: runtimeEnv,
+        runId: options.runId,
+        allowFallback: options.allowFallback
+    });
+    return {
+        runtime,
+        env: {
+            ...runtimeEnv,
+            ...runtime.env_overrides
+        }
+    };
+}
+export function resolveRuntimeCodexCommand(args, context) {
+    return resolveCodexCommand(args, context.env);
+}
+export function formatRuntimeSelectionSummary(selection) {
+    const base = `runtime requested=${selection.requested_mode} selected=${selection.selected_mode} provider=${selection.provider}`;
+    if (!selection.fallback.occurred) {
+        return base;
+    }
+    const code = selection.fallback.code ?? 'unknown';
+    const reason = selection.fallback.reason ?? 'fallback occurred';
+    return `${base} fallback=${code} (${reason})`;
+}

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

@@ -0,0 +1,3 @@
+export { parseRuntimeMode, resolveRuntimeMode, DEFAULT_RUNTIME_MODE, DEFAULT_RUNTIME_MODE_ENV_KEY } from './mode.js';
+export { resolveRuntimeSelection } from './provider.js';
+export { createRuntimeCodexCommandContext, resolveRuntimeCodexCommand, formatRuntimeSelectionSummary } from './codexCommand.js';

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

@@ -0,0 +1,53 @@
+const RUNTIME_MODES = new Set(['cli', 'appserver']);
+const DEFAULT_RUNTIME_MODE = 'appserver';
+const DEFAULT_RUNTIME_MODE_ENV_KEY = 'CODEX_ORCHESTRATOR_RUNTIME_MODE';
+function normalizeRuntimeMode(value) {
+    const normalized = value.trim().toLowerCase();
+    return RUNTIME_MODES.has(normalized) ? normalized : null;
+}
+function parseRuntimeModeFromSource(value, sourceLabel) {
+    const parsed = normalizeRuntimeMode(value);
+    if (!parsed) {
+        throw new Error(`Invalid runtime mode "${value}" from ${sourceLabel}. Expected one of: cli, appserver.`);
+    }
+    return parsed;
+}
+export function parseRuntimeMode(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return null;
+    }
+    return normalizeRuntimeMode(value);
+}
+export function resolveRuntimeMode(options = {}) {
+    if (typeof options.flag === 'string' && options.flag.trim().length > 0) {
+        return {
+            mode: parseRuntimeModeFromSource(options.flag, 'CLI flag'),
+            source: 'flag'
+        };
+    }
+    const envKey = options.envKey ?? DEFAULT_RUNTIME_MODE_ENV_KEY;
+    const envValue = options.env?.[envKey] ?? process.env[envKey];
+    if (typeof envValue === 'string' && envValue.trim().length > 0) {
+        return {
+            mode: parseRuntimeModeFromSource(envValue, `env ${envKey}`),
+            source: 'env'
+        };
+    }
+    if (typeof options.configDefault === 'string' && options.configDefault.trim().length > 0) {
+        return {
+            mode: parseRuntimeModeFromSource(options.configDefault, 'config default'),
+            source: 'config'
+        };
+    }
+    if (options.preferManifest && typeof options.manifestMode === 'string' && options.manifestMode.trim().length > 0) {
+        return {
+            mode: parseRuntimeModeFromSource(options.manifestMode, 'manifest'),
+            source: 'manifest'
+        };
+    }
+    return {
+        mode: DEFAULT_RUNTIME_MODE,
+        source: 'default'
+    };
+}
+export { DEFAULT_RUNTIME_MODE, DEFAULT_RUNTIME_MODE_ENV_KEY };

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

@@ -0,0 +1,205 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolveCodexCliBin } from '../utils/codexCli.js';
+import { isoTimestamp } from '../utils/time.js';
+const execFileAsync = promisify(execFile);
+const APP_SERVER_HELP_TIMEOUT_MS = 8000;
+const LOGIN_STATUS_TIMEOUT_MS = 8000;
+function envFlagEnabled(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+function allowRuntimeFallback(env, override) {
+    if (typeof override === 'boolean') {
+        return override;
+    }
+    const raw = env.CODEX_ORCHESTRATOR_RUNTIME_FALLBACK;
+    if (!raw) {
+        return true;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return !['0', 'false', 'off', 'deny', 'disabled', 'never', 'strict'].includes(normalized);
+}
+function createNoFallback(now) {
+    return {
+        occurred: false,
+        code: null,
+        reason: null,
+        from_mode: null,
+        to_mode: null,
+        checked_at: now()
+    };
+}
+function createFallback(params) {
+    return {
+        occurred: true,
+        code: params.code,
+        reason: params.reason,
+        from_mode: params.fromMode,
+        to_mode: params.toMode,
+        checked_at: params.now()
+    };
+}
+function summarizePreflightFailures(issues) {
+    const codes = issues.map((issue) => issue.code).join(', ');
+    const messages = issues.map((issue) => issue.message).join(' ');
+    return `Appserver preflight failed (${codes}). ${messages}`.trim();
+}
+function resolveRequestedMode(options) {
+    if (options.executionMode === 'cloud' &&
+        options.requestedMode === 'appserver' &&
+        (options.source === 'default' || options.source === 'manifest')) {
+        return 'cli';
+    }
+    return options.requestedMode;
+}
+async function runCodexProbe(command, args, cwd, env, timeoutMs) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args, {
+            cwd,
+            env,
+            timeout: timeoutMs,
+            maxBuffer: 256 * 1024
+        });
+        return {
+            ok: true,
+            stdout: stdout.toString(),
+            stderr: stderr.toString(),
+            code: 'ok'
+        };
+    }
+    catch (error) {
+        const typed = error;
+        const stdout = typeof typed.stdout === 'string' ? typed.stdout : typed.stdout?.toString() ?? '';
+        const stderr = typeof typed.stderr === 'string' ? typed.stderr : typed.stderr?.toString() ?? '';
+        const timeout = typed.signal === 'SIGTERM' || typed.killed === true;
+        return {
+            ok: false,
+            stdout,
+            stderr,
+            code: timeout ? 'timeout' : typed.code ?? 'failed'
+        };
+    }
+}
+async function runAppserverPreflight(params) {
+    const codexBin = resolveCodexCliBin(params.env);
+    const issues = [];
+    if (envFlagEnabled(params.env.CODEX_ORCHESTRATOR_APPSERVER_FORCE_PRECHECK_FAIL)) {
+        issues.push({
+            code: 'forced-preflight-failure',
+            message: 'Forced appserver preflight failure via CODEX_ORCHESTRATOR_APPSERVER_FORCE_PRECHECK_FAIL.'
+        });
+        return {
+            ok: false,
+            issues
+        };
+    }
+    const appServerHelp = await runCodexProbe(codexBin, ['app-server', '--help'], params.repoRoot, params.env, APP_SERVER_HELP_TIMEOUT_MS);
+    if (!appServerHelp.ok) {
+        issues.push({
+            code: 'appserver-command-unavailable',
+            message: appServerHelp.code === 'timeout'
+                ? 'Timed out probing `codex app-server --help`.'
+                : 'Failed probing `codex app-server --help`.'
+        });
+    }
+    if (!envFlagEnabled(params.env.CODEX_ORCHESTRATOR_APPSERVER_SKIP_LOGIN_CHECK)) {
+        const loginStatus = await runCodexProbe(codexBin, ['login', 'status'], params.repoRoot, params.env, LOGIN_STATUS_TIMEOUT_MS);
+        if (!loginStatus.ok) {
+            issues.push({
+                code: 'login-status-failed',
+                message: loginStatus.code === 'timeout'
+                    ? 'Timed out probing `codex login status`.'
+                    : 'Failed probing `codex login status`.'
+            });
+        }
+        else {
+            const text = `${loginStatus.stdout}\n${loginStatus.stderr}`.toLowerCase();
+            const loggedIn = text.includes('logged in');
+            const loggedOut = text.includes('not logged') || text.includes('logged out');
+            if (!loggedIn || loggedOut) {
+                issues.push({
+                    code: 'login-required',
+                    message: '`codex login status` did not report an active ChatGPT login.'
+                });
+            }
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        issues
+    };
+}
+export async function resolveRuntimeSelection(options) {
+    const now = options.now ?? isoTimestamp;
+    const requestedMode = resolveRequestedMode(options);
+    if (options.executionMode === 'cloud' && requestedMode === 'appserver') {
+        throw new Error('Unsupported mode combination: executionMode=cloud does not support runtimeMode=appserver. ' +
+            'Use --runtime-mode cli or remove the runtime override for cloud execution.');
+    }
+    if (requestedMode === 'cli') {
+        return {
+            requested_mode: 'cli',
+            selected_mode: 'cli',
+            source: options.source,
+            provider: 'CliRuntimeProvider',
+            env_overrides: {
+                CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE: 'cli',
+                CODEX_ORCHESTRATOR_RUNTIME_MODE: 'cli',
+                CODEX_RUNTIME_MODE: 'cli',
+                CODEX_ORCHESTRATOR_APPSERVER_SESSION_ID: ''
+            },
+            runtime_session_id: null,
+            fallback: createNoFallback(now)
+        };
+    }
+    const preflight = await runAppserverPreflight({
+        repoRoot: options.repoRoot,
+        env: options.env
+    });
+    if (preflight.ok) {
+        const runtimeSessionId = `appserver-${options.runId}`;
+        return {
+            requested_mode: 'appserver',
+            selected_mode: 'appserver',
+            source: options.source,
+            provider: 'AppServerRuntimeProvider',
+            env_overrides: {
+                CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE: 'appserver',
+                CODEX_ORCHESTRATOR_RUNTIME_MODE: 'appserver',
+                CODEX_ORCHESTRATOR_APPSERVER_SESSION_ID: runtimeSessionId,
+                CODEX_RUNTIME_MODE: 'appserver'
+            },
+            runtime_session_id: runtimeSessionId,
+            fallback: createNoFallback(now)
+        };
+    }
+    const reason = summarizePreflightFailures(preflight.issues);
+    const fallbackAllowed = allowRuntimeFallback(options.env, options.allowFallback);
+    if (!fallbackAllowed) {
+        throw new Error(`${reason} Runtime fallback is disabled by CODEX_ORCHESTRATOR_RUNTIME_FALLBACK.`);
+    }
+    return {
+        requested_mode: 'appserver',
+        selected_mode: 'cli',
+        source: options.source,
+        provider: 'CliRuntimeProvider',
+        env_overrides: {
+            CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE: 'cli',
+            CODEX_ORCHESTRATOR_RUNTIME_MODE: 'cli',
+            CODEX_RUNTIME_MODE: 'cli',
+            CODEX_ORCHESTRATOR_APPSERVER_SESSION_ID: ''
+        },
+        runtime_session_id: null,
+        fallback: createFallback({
+            code: preflight.issues[0]?.code ?? 'appserver-preflight-failed',
+            reason,
+            fromMode: 'appserver',
+            toMode: 'cli',
+            now
+        })
+    };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -154,10 +154,13 @@ export async function runCommandStage(context, hooks = {}) {
     const unsubscribe = runner.on(handleEvent);
     try {
         const sessionConfig = stage.session ?? {};
-        const sessionId = sessionConfig.id;
-        const wantsPersist = Boolean(sessionConfig.persist || sessionConfig.reuse);
-        const persistSession = Boolean(sessionId && wantsPersist);
-        const reuseSession = Boolean(sessionId && (sessionConfig.reuse ?? persistSession));
+        const stageSessionId = runtimeSessionIdOrNull(sessionConfig.id);
+        const inheritedRuntimeSessionId = runtimeSessionIdOrNull(context.runtimeSessionId);
+        const effectiveSessionId = stageSessionId ?? inheritedRuntimeSessionId;
+        const usesInheritedRuntimeSession = !stageSessionId && Boolean(inheritedRuntimeSessionId);
+        const wantsPersist = Boolean(sessionConfig.persist || sessionConfig.reuse || usesInheritedRuntimeSession);
+        const persistSession = Boolean(effectiveSessionId && wantsPersist);
+        const reuseSession = Boolean(effectiveSessionId && (sessionConfig.reuse ?? persistSession));
         const baseEnv = {
             ...process.env,
             ...(envOverrides ?? {}),
@@ -172,6 +175,10 @@ export async function runCommandStage(context, hooks = {}) {
             CODEX_ORCHESTRATOR_ROOT: env.repoRoot,
             CODEX_ORCHESTRATOR_PACKAGE_ROOT: PACKAGE_ROOT
         };
+        baseEnv.CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE =
+            context.runtimeMode ?? (manifest.runtime_mode === 'appserver' ? 'appserver' : 'cli');
+        // Keep both keys during migration because downstream tools still read either name.
+        baseEnv.CODEX_ORCHESTRATOR_RUNTIME_MODE = baseEnv.CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE;
         const execEnv = { ...baseEnv, ...stage.env };
         const invocationId = `cli-command:${manifest.run_id}:${stage.id}:${Date.now()}`;
         let result;
@@ -181,7 +188,7 @@ export async function runCommandStage(context, hooks = {}) {
                 command: stage.command,
                 cwd: stage.cwd ?? env.repoRoot,
                 env: execEnv,
-                sessionId: sessionId ?? undefined,
+                sessionId: effectiveSessionId ?? undefined,
                 persistSession,
                 reuseSession,
                 invocationId,
@@ -275,6 +282,13 @@ export async function runCommandStage(context, hooks = {}) {
         privacyLog.end();
     }
 }
+function runtimeSessionIdOrNull(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 function recordHandle(manifest, descriptor, context) {
     const handles = Array.isArray(manifest.handles) ? [...manifest.handles] : [];
     const entry = {

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

@@ -35,6 +35,7 @@ export async function prepareRun(options) {
     const resolvedPipeline = options.pipeline
         ? {
             pipeline: options.pipeline,
+            userConfig: null,
             source: options.pipelineSource ?? null,
             configNotice: options.configNotice ?? null,
             envOverrides: options.envOverrides ?? {}
@@ -54,6 +55,7 @@ export async function prepareRun(options) {
         env,
         pipeline: resolvedPipeline.pipeline,
         pipelineSource: resolvedPipeline.source ?? null,
+        runtimeModeDefault: options.runtimeModeDefault ?? resolvedPipeline.userConfig?.runtimeMode ?? null,
         configNotice: resolvedPipeline.configNotice ?? null,
         envOverrides: resolvedPipeline.envOverrides ?? {},
         planner,

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

@@ -27,6 +27,18 @@ export function applyPrivacyToRunSummary(runSummary, manifest) {
         allowedFrames: manifest.privacy.totals.allowed_frames
     };
 }
+export function applyRuntimeToRunSummary(runSummary, manifest) {
+    const fallback = manifest.runtime_fallback ?? null;
+    runSummary.runtime = {
+        modeRequested: manifest.runtime_mode_requested,
+        modeUsed: manifest.runtime_mode,
+        provider: manifest.runtime_provider,
+        fallbackOccurred: fallback?.occurred ?? false,
+        fallbackCode: fallback?.code ?? null,
+        fallbackReason: fallback?.reason ?? null,
+        checkedAt: fallback?.checked_at ?? null
+    };
+}
 export function applyCloudExecutionToRunSummary(runSummary, manifest) {
     if (!manifest.cloud_execution) {
         return;

package/dist/scripts/run-review.js

@@ -16,7 +16,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { createInterface } from 'node:readline';
 import { promisify } from 'node:util';
-import { resolveCodexCommand } from '../orchestrator/src/cli/utils/devtools.js';
+import { createRuntimeCodexCommandContext, formatRuntimeSelectionSummary, parseRuntimeMode, resolveRuntimeCodexCommand } from '../orchestrator/src/cli/runtime/index.js';
 import { runDoctor } from '../orchestrator/src/cli/doctor.js';
 import { formatDoctorIssueLogSummary, writeDoctorIssueLog } from '../orchestrator/src/cli/doctorIssueLog.js';
 import { parseArgs as parseCliArgs, hasFlag } from './lib/cli-args.js';
@@ -180,6 +180,16 @@ function parseBooleanOptionValue(raw, label) {
     }
     throw new Error(`Invalid ${label} value "${raw}". Expected true|false.`);
 }
+function parseRuntimeModeOption(raw, label) {
+    if (typeof raw !== 'string') {
+        throw new Error(`${label} requires a value. Expected one of: cli, appserver.`);
+    }
+    const parsed = parseRuntimeMode(raw);
+    if (!parsed) {
+        throw new Error(`Invalid ${label} value "${raw}". Expected one of: cli, appserver.`);
+    }
+    return parsed;
+}
 function inferTaskFromManifestPath(manifestPath) {
     const segments = path.normalize(manifestPath).split(path.sep).filter((segment) => segment.length > 0);
     const fileName = segments.at(-1);
@@ -218,6 +228,9 @@ function parseArgs(argv) {
         else if (entry.key === 'task' && typeof entry.value === 'string') {
             options.task = entry.value;
         }
+        else if (entry.key === 'runtime-mode') {
+            options.runtimeMode = parseRuntimeModeOption(entry.value, '--runtime-mode');
+        }
         else if (entry.key === 'base' && typeof entry.value === 'string') {
             options.base = entry.value;
         }
@@ -413,7 +426,13 @@ async function main() {
         console.log('Set FORCE_CODEX_REVIEW=1 to invoke `codex review` in this environment.');
         return;
     }
-    await ensureReviewCommandAvailable();
+    const runtimeContext = await resolveReviewRuntimeContext({
+        options,
+        manifestPath,
+        env: reviewEnv
+    });
+    console.log(`[run-review] ${formatRuntimeSelectionSummary(runtimeContext.runtime)}.`);
+    await ensureReviewCommandAvailable(runtimeContext);
     const disableDelegationMcp = options.disableDelegationMcp ??
         (options.enableDelegationMcp === undefined ? false : !options.enableDelegationMcp);
     if (disableDelegationMcp) {
@@ -426,7 +445,7 @@ async function main() {
         includeScopeFlags: true,
         disableDelegationMcp
     });
-    const resolvedScoped = resolveReviewCommand(scopedReviewArgs);
+    const resolvedScoped = resolveReviewCommand(scopedReviewArgs, runtimeContext);
     console.log(`Review prompt saved to: ${path.relative(repoRoot, artifactPaths.promptPath)}`);
     console.log(`Review output log: ${path.relative(repoRoot, artifactPaths.outputLogPath)}`);
     console.log(`Launching Codex review (evidence: ${relativeManifest})`);
@@ -454,7 +473,7 @@ async function main() {
     const runReview = async (resolved) => runCodexReview({
         command: resolved.command,
         args: resolved.args,
-        env: reviewEnv,
+        env: runtimeContext.env,
         stdio: nonInteractive ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
         blockHeavyCommands: enforceBoundedMode,
         timeoutMs,
@@ -497,7 +516,7 @@ async function main() {
                 includeScopeFlags: false,
                 disableDelegationMcp
             });
-            const resolvedUnscoped = resolveReviewCommand(unscopedArgs);
+            const resolvedUnscoped = resolveReviewCommand(unscopedArgs, runtimeContext);
             try {
                 await runReview(resolvedUnscoped);
                 const telemetrySummary = await writeTelemetry('succeeded');
@@ -551,8 +570,8 @@ main().catch((error) => {
     console.error('[run-review] failed:', error.message ?? error);
     process.exitCode = typeof error?.exitCode === 'number' ? error.exitCode : 1;
 });
-async function ensureReviewCommandAvailable() {
-    const resolved = resolveCodexCommand(['--help'], process.env);
+async function ensureReviewCommandAvailable(context) {
+    const resolved = resolveRuntimeCodexCommand(['--help'], context);
     const hasReview = await new Promise((resolve, reject) => {
         const detached = process.platform !== 'win32';
         const child = spawn(resolved.command, resolved.args, { stdio: ['ignore', 'pipe', 'pipe'], detached });
@@ -607,6 +626,32 @@ async function ensureReviewCommandAvailable() {
         throw new Error('codex CLI is missing the `review` subcommand (or is not installed).');
     }
 }
+async function resolveReviewRuntimeContext(params) {
+    const runId = await resolveReviewRunId(params.manifestPath);
+    const requestedMode = params.options.runtimeMode ??
+        parseRuntimeMode(params.env.CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE ??
+            params.env.CODEX_ORCHESTRATOR_RUNTIME_MODE ??
+            null);
+    return await createRuntimeCodexCommandContext({
+        requestedMode,
+        executionMode: 'mcp',
+        repoRoot,
+        env: params.env,
+        runId: runId ?? `review-${Date.now()}`
+    });
+}
+async function resolveReviewRunId(manifestPath) {
+    try {
+        const raw = await readFile(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.run_id === 'string' && parsed.run_id.trim().length > 0
+            ? parsed.run_id.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 function resolveScopeFlag(options) {
     if (options.commit) {
         return { mode: 'commit', args: ['--commit', options.commit] };
@@ -644,8 +689,8 @@ function buildReviewArgs(options, prompt, opts) {
     args.push(prompt);
     return args;
 }
-function resolveReviewCommand(reviewArgs) {
-    return resolveCodexCommand(reviewArgs, process.env);
+function resolveReviewCommand(reviewArgs, context) {
+    return resolveRuntimeCodexCommand(reviewArgs, context);
 }
 async function buildScopeNotes(options) {
     const lines = [];
@@ -1954,6 +1999,7 @@ Standalone review wrapper for Codex review with manifest-backed context.
 Options:
   --manifest <path>              Explicit run manifest path.
   --task <task-id>               Task id used to resolve latest manifest.
+  --runtime-mode <cli|appserver> Runtime mode for the underlying Codex review call.
   --runs-dir <path>              Override .runs root for manifest discovery.
   --uncommitted                  Review uncommitted diff scope.
   --base <ref>                   Review diff from base ref.

package/docs/README.md

@@ -216,7 +216,7 @@ Note: the commands below assume a source checkout; `scripts/` helpers are not in
 | `node scripts/delegation-guard.mjs` | Enforces subagent delegation evidence before review (repo-only). |
 | `node scripts/spec-guard.mjs --dry-run` | Validates spec freshness; required before review (repo-only). |
 | `node scripts/diff-budget.mjs` | Guards against oversized diffs before review (repo-only; defaults: 25 files / 800 lines; supports explicit overrides). |
-| `npm run pack:smoke` | Downstream simulation gate for npm consumers (tarball install in temp mock repo, `review` wrapper artifacts, delegate-server JSONL, and `skills install --only long-poll-wait`). Core-lane runs it automatically when downstream-facing paths change. |
+| `npm run pack:smoke` | Downstream simulation gate for npm consumers (tarball install in temp mock repo, `review` wrapper artifacts, delegate-server JSONL, and `skills install --only long-poll-wait`). Core lane runs it automatically when downstream-facing paths change, and `.github/workflows/pack-smoke-backstop.yml` runs a weekly `main` backstop. |
 | `codex-orchestrator review` | Runs the standalone review wrapper with task-scoped manifest evidence; delegation MCP is enabled by default (explicit disable available via `CODEX_REVIEW_DISABLE_DELEGATION_MCP=1` / `--disable-delegation-mcp`), runtime guards are opt-in via `CODEX_REVIEW_*` env vars, and patience-first checkpoints log by default (`CODEX_REVIEW_MONITOR_INTERVAL_SECONDS` tunes/disables). Large uncommitted scopes get an automatic prompt advisory (`CODEX_REVIEW_LARGE_SCOPE_FILE_THRESHOLD` / `CODEX_REVIEW_LARGE_SCOPE_LINE_THRESHOLD`). Optional auto failure issue logging via `CODEX_REVIEW_AUTO_ISSUE_LOG=1` or `--auto-issue-log`. |
 | `npm run review` | Runs `codex review` with task-scoped manifest evidence; delegation MCP is enabled by default (explicit disable available via `CODEX_REVIEW_DISABLE_DELEGATION_MCP=1` / `--disable-delegation-mcp`), runtime guards are opt-in via `CODEX_REVIEW_*` env vars, and patience-first checkpoints log by default (`CODEX_REVIEW_MONITOR_INTERVAL_SECONDS` tunes/disables). Large uncommitted scopes get an automatic prompt advisory (`CODEX_REVIEW_LARGE_SCOPE_FILE_THRESHOLD` / `CODEX_REVIEW_LARGE_SCOPE_LINE_THRESHOLD`). Optional auto failure issue logging via `CODEX_REVIEW_AUTO_ISSUE_LOG=1` or `--auto-issue-log`. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -51,6 +51,7 @@
     "docs:freshness": "node scripts/docs-freshness.mjs --check",
     "docs:sync": "node --loader ts-node/esm scripts/docs-hygiene.ts --sync",
     "ci:cloud-canary": "node scripts/cloud-canary-ci.mjs",
+    "canary:runtime": "node scripts/runtime-mode-canary.mjs",
     "prelint": "node scripts/build-patterns-if-needed.mjs",
     "lint": "eslint orchestrator/src orchestrator/tests packages/orchestrator/src packages/orchestrator/tests packages/shared adapters evaluation/harness evaluation/tests --ext .ts,.tsx",
     "pack:audit": "node scripts/pack-audit.mjs",