@kbediako/codex-orchestrator 0.1.36 → 0.1.38

package/README.md

@@ -39,6 +39,16 @@ Node.js >= 20 is required.
    > Tip: if you prefer `npx`, replace `codex-orch` with `npx @kbediako/codex-orchestrator`.
    > Tip: for multiple commands, you can also `export MCP_RUNNER_TASK_ID=<task-id>` once.
 
+## Runtime + Execution Modes
+
+- Mode semantics are orthogonal:
+  - `executionMode=mcp|cloud` controls where stages execute.
+  - `runtimeMode=cli|appserver` controls local runtime provider selection.
+- Local default runtime is `appserver`; preserve `--runtime-mode cli` as break-glass.
+- `--execution-mode cloud --runtime-mode appserver` is intentionally unsupported and fails fast with actionable errors.
+- `js_repl` is enabled by default globally. For deterministic cloud contracts, run explicit feature lanes (`CODEX_CLOUD_ENABLE_FEATURES=js_repl` and separate `CODEX_CLOUD_DISABLE_FEATURES=js_repl` runs). Use `CODEX_CLOUD_DISABLE_FEATURES=js_repl` for task-scoped cloud break-glass; reserve `codex features disable js_repl` for global emergency toggles and re-enable with `codex features enable js_repl`.
+- `memories` remains scoped to explicit eval lanes (legacy alias `memory_tool` is compatibility-only).
+
 ## Downstream init (recommended)
 
 Use this when you want Codex to drive work inside another repo with the CO defaults.
@@ -97,6 +107,7 @@ codex -c 'mcp_servers.delegation.enabled=true' ...
 Codex built-ins are `default`, `explorer`, `worker`, and `awaiter`. `researcher` is user-defined.
 - `spawn_agent` defaults to `default` when `agent_type` is omitted, so always set `agent_type` explicitly.
 - Multi-turn loops are supported (`spawn_agent` -> `send_input` -> `wait`/`resume_agent` -> `close_agent`), so subagents can iterate before parent synthesis.
+- Keep `fork_context` off by default for bounded subagent streams; set `fork_context=true` only when the subagent must inherit prior thread history.
 
 In Codex CLI `0.105.0`, built-in `explorer` no longer pins an older model profile; it inherits top-level defaults unless you attach a role `config_file`.
 CO now ships this downstream starter config via `init codex` (source template: `templates/codex/.codex/config.toml`; installed as .codex/config.toml in target repos):
@@ -155,7 +166,7 @@ Delegation guard profile:
 
 RLM (Recursive Language Model) is the long-horizon loop used by the `rlm` pipeline (`codex-orchestrator rlm "<goal>"` or `codex-orchestrator start rlm --goal "<goal>"`). Delegated runs only enter RLM when the child is launched with the `rlm` pipeline (or the rlm runner directly). In auto mode it resolves to symbolic only when context is large (`RLM_SYMBOLIC_MIN_BYTES`) and an explicit context signal is present (`RLM_CONTEXT_PATH` or delegated run); otherwise it stays iterative. The runner writes state to `.runs/<task-id>/cli/<run-id>/rlm/state.json` and stops when the validator passes or budgets are exhausted.
 For symbolic mode, the Option 2 alignment checker is enabled by default (`RLM_ALIGNMENT_CHECKER=1`) and writes append-only alignment artifacts under `.runs/<task-id>/cli/<run-id>/rlm/alignment/` (ledger + projection). Rollback toggle: set `RLM_ALIGNMENT_CHECKER=0`. Enforcement is opt-in via `RLM_ALIGNMENT_CHECKER_ENFORCE=1`.
-Symbolic subcalls can optionally use collab tools. Fast path: `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; sets `RLM_SYMBOLIC_MULTI_AGENT=1` plus legacy `RLM_SYMBOLIC_COLLAB=1` for compatibility, and implies symbolic mode). Collab requires `multi_agent=true` in `codex features list` (`collab` remains a legacy alias). Collab tool calls parsed from `codex exec --json --enable multi_agent` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable). For auditable role routing, prefix spawned prompts with `[agent_type:<role>]` and set `spawn_agent.agent_type` when supported; lifecycle validation enforces prompt-role evidence and validates `agent_type` when present (`RLM_SYMBOLIC_MULTI_AGENT_ROLE_POLICY=warn|off`, legacy alias `RLM_COLLAB_ROLE_POLICY`; `RLM_SYMBOLIC_MULTI_AGENT_ALLOW_DEFAULT_ROLE=1`, legacy alias `RLM_COLLAB_ALLOW_DEFAULT_ROLE`). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path (opt-in via `CODEX_CLI_USE_MANAGED=1`).
+Symbolic subcalls can optionally use collab tools. Fast path: `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; sets `RLM_SYMBOLIC_MULTI_AGENT=1` plus legacy `RLM_SYMBOLIC_COLLAB=1` for compatibility, and implies symbolic mode). Collab requires `multi_agent=true` in `codex features list` (`collab` remains a legacy alias). Collab tool calls parsed from `codex exec --json --enable multi_agent` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable); when present in events, `spawn_agent.fork_context` is captured for observability and surfaced in `codex-orchestrator doctor --usage` fork-context counters. For auditable role routing, prefix spawned prompts with `[agent_type:<role>]` and set `spawn_agent.agent_type` when supported; lifecycle validation enforces prompt-role evidence and validates `agent_type` when present (`RLM_SYMBOLIC_MULTI_AGENT_ROLE_POLICY=warn|off`, legacy alias `RLM_COLLAB_ROLE_POLICY`; `RLM_SYMBOLIC_MULTI_AGENT_ALLOW_DEFAULT_ROLE=1`, legacy alias `RLM_COLLAB_ALLOW_DEFAULT_ROLE`). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path (opt-in via `CODEX_CLI_USE_MANAGED=1`).
 For batch fan-out jobs, prefer native `spawn_agents_on_csv` before building custom orchestration wrappers.
 
 ### Delegation flow
@@ -215,10 +226,12 @@ Options:
 - `--codex-home <path>` targets a different Codex home directory.
 
 Bundled skills (may vary by release):
+- `codex-orchestrator`
 - `collab-subagents-first`
 - `chrome-devtools`
 - `delegation-usage`
 - `standalone-review`
+- `elegance-review`
 - `docs-first`
 - `collab-evals`
 - `collab-deliberation`
@@ -276,7 +289,7 @@ codex-orchestrator doctor --cloud-preflight
 - Active PR watch-resolve-merge loop: `codex-orchestrator pr resolve-merge --pr <number> --quiet-minutes <window>` (add `--auto-merge` when approved; exits early when author action is required).
 - Passive PR monitor loop: `codex-orchestrator pr watch-merge --pr <number> --quiet-minutes <window>` (monitor-only behavior; keeps waiting unless terminal/timeout).
 - Review checkpoints (npm-only safe): `NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>` for manifest-backed standalone review wrapper behavior (auto-skips repo-only diff-budget script when unavailable in downstream installs); use `codex review "<focus>"` for quick prompt-only checks; use `codex-orchestrator start implementation-gate --task <task-id> --format json` when you want a full gate run.
-- Downstream simulation before shipping wrapper/skill changes: `npm run pack:smoke` (packaged CLI in temp mock repo; validates `review` artifacts and `long-poll-wait` install path).
+- Downstream simulation before shipping wrapper/skill changes: `npm run pack:smoke` (packaged CLI in temp mock repo; validates `review` artifacts and `long-poll-wait` install path; spot-check gate). Use `npm run pack:audit` for full tarball inventory validation.
 - Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
 - Collab (symbolic RLM subagents): `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; requires Codex `features.multi_agent=true`)
 - Cloud: set `CODEX_CLOUD_ENV_ID` (and optional `CODEX_CLOUD_BRANCH`), then run: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`
@@ -307,7 +320,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/doctorUsage.js

@@ -31,6 +31,9 @@ export async function runDoctorUsage(options = {}) {
     const collabByEventType = {};
     const collabTools = new Map();
     const collabCaptureDisabled = String(process.env.CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS ?? '').trim() === '0';
+    let collabSpawnForkContextTrue = 0;
+    let collabSpawnForkContextFalse = 0;
+    let collabSpawnForkContextUnknown = 0;
     let collabRunsWithUnclosedSpawnAgents = 0;
     let collabUnclosedSpawnAgents = 0;
     let collabRunsWithSpawnThreadLimitFailures = 0;
@@ -160,6 +163,15 @@ export async function runDoctorUsage(options = {}) {
                     continue;
                 }
                 if (tool === 'spawn_agent') {
+                    if (entry?.fork_context === true) {
+                        collabSpawnForkContextTrue += 1;
+                    }
+                    else if (entry?.fork_context === false) {
+                        collabSpawnForkContextFalse += 1;
+                    }
+                    else {
+                        collabSpawnForkContextUnknown += 1;
+                    }
                     if (isFailed) {
                         const rawFailedSpawnId = typeof entry?.item_id === 'string' ? entry.item_id.trim() : '';
                         const failedSpawnId = rawFailedSpawnId.length > 0 && rawFailedSpawnId !== 'unknown'
@@ -290,6 +302,9 @@ export async function runDoctorUsage(options = {}) {
             by_event_type: collabByEventType,
             top_tools: collabTopTools,
             capture_disabled: collabCaptureDisabled,
+            spawn_agent_fork_context_true: collabSpawnForkContextTrue,
+            spawn_agent_fork_context_false: collabSpawnForkContextFalse,
+            spawn_agent_fork_context_unknown: collabSpawnForkContextUnknown,
             runs_with_unclosed_spawn_agents: collabRunsWithUnclosedSpawnAgents,
             unclosed_spawn_agents: collabUnclosedSpawnAgents,
             runs_with_spawn_thread_limit_failures: collabRunsWithSpawnThreadLimitFailures,
@@ -357,9 +372,10 @@ export function formatDoctorUsageSummary(result) {
     const collabLifecycleUnknownSignal = collabLifecycleUnknownRuns > 0
         ? `, lifecycle_unknown_runs=${collabLifecycleUnknownRuns}`
         : '';
+    const collabForkContextSignal = `, fork_context=${result.collab.spawn_agent_fork_context_true}/${result.collab.spawn_agent_fork_context_false}/${result.collab.spawn_agent_fork_context_unknown}`;
     const collabToolList = formatTopList(result.collab.top_tools.map((entry) => ({ key: entry.tool, value: entry.calls })), 3, 'tools');
     lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`
-        + `${collabTaskSuffix}, events=${result.collab.total_tool_calls}${collabAvg} (ok=${collabOk}, failed=${collabFailed}${collabLeakSignal}${collabThreadLimitSignal}${collabLifecycleUnknownSignal})${collabToolList}`);
+        + `${collabTaskSuffix}, events=${result.collab.total_tool_calls}${collabAvg} (ok=${collabOk}, failed=${collabFailed}${collabLeakSignal}${collabThreadLimitSignal}${collabLifecycleUnknownSignal}${collabForkContextSignal})${collabToolList}`);
     if (result.delegation.active_top_level_tasks > 0) {
         lines.push(`  - delegation: ${result.delegation.active_with_subagents}/${result.delegation.active_top_level_tasks} top-level tasks have subagent manifests (${result.delegation.total_subagent_manifests} total); child_runs=${result.delegation.total_child_runs} over ${result.delegation.tasks_with_child_runs} tasks`);
     }

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();
 }