@kbediako/codex-orchestrator 0.1.35 → 0.1.37

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

@@ -0,0 +1,274 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import process from 'node:process';
+import { resolveCodexHome } from './utils/codexPaths.js';
+import { findPackageRoot } from './utils/packageInfo.js';
+import { writeAtomicFile } from '../utils/atomicWrite.js';
+const require = createRequire(import.meta.url);
+const toml = require('@iarna/toml');
+const canonicalize = require('canonicalize');
+export const BASELINE_MODEL = 'gpt-5.3-codex';
+export const BASELINE_REASONING = 'xhigh';
+export const BASELINE_REASONING_MINIMUM = 'high';
+export const BASELINE_AGENTS = {
+    max_threads: 12,
+    max_depth: 4,
+    max_spawn_depth: 4
+};
+const ROLE_DEFINITIONS = [
+    {
+        key: 'explorer_fast',
+        description: 'Fast explorer (spark text-only).',
+        fileName: 'explorer-fast.toml',
+        configFile: './agents/explorer-fast.toml',
+        templatePath: join('templates', 'codex', '.codex', 'agents', 'explorer-fast.toml')
+    },
+    {
+        key: 'worker_complex',
+        description: 'Complex implementation role.',
+        fileName: 'worker-complex.toml',
+        configFile: './agents/worker-complex.toml',
+        templatePath: join('templates', 'codex', '.codex', 'agents', 'worker-complex.toml')
+    },
+    {
+        key: 'awaiter',
+        description: 'Awaiter override (keeps awaiter behavior with latest codex/high reasoning).',
+        fileName: 'awaiter-high.toml',
+        configFile: './agents/awaiter-high.toml',
+        templatePath: join('templates', 'codex', '.codex', 'agents', 'awaiter-high.toml')
+    }
+];
+export async function runCodexDefaultsSetup(options = {}) {
+    const env = options.env ?? process.env;
+    const force = Boolean(options.force);
+    const apply = Boolean(options.apply);
+    const plan = buildPlan(env, force);
+    const roleDefinitions = await loadRoleDefinitions();
+    const configState = await loadConfigState(plan.configPath);
+    const nextConfig = mergeBaselineDefaults(configState.parsed, roleDefinitions);
+    const configChanged = canonicalize(configState.parsed) !== canonicalize(nextConfig);
+    const roleChanges = await planRoleChanges(plan.agentsDir, force, roleDefinitions);
+    if (!apply) {
+        const changes = buildPlannedChanges({
+            configPath: plan.configPath,
+            configExists: configState.exists,
+            configChanged,
+            roleChanges
+        });
+        return {
+            status: 'planned',
+            plan,
+            changes
+        };
+    }
+    const changes = [];
+    if (configChanged || !configState.exists) {
+        const rendered = `${toml.stringify(nextConfig)}\n`;
+        await writeAtomicFile(plan.configPath, rendered, { ensureDir: true, encoding: 'utf8' });
+        changes.push({
+            target: 'config',
+            name: 'config.toml',
+            path: plan.configPath,
+            status: configState.exists ? 'updated' : 'created',
+            detail: configState.exists
+                ? 'Updated CO baseline defaults additively and preserved unrelated keys.'
+                : 'Created config.toml with CO baseline defaults.'
+        });
+    }
+    else {
+        changes.push({
+            target: 'config',
+            name: 'config.toml',
+            path: plan.configPath,
+            status: 'unchanged',
+            detail: 'CO baseline defaults already present.'
+        });
+    }
+    await mkdir(plan.agentsDir, { recursive: true });
+    for (const roleChange of roleChanges) {
+        const shouldWrite = roleChange.existingContent === null
+            || (force && roleChange.existingContent !== roleChange.definition.content);
+        if (shouldWrite) {
+            await writeAtomicFile(roleChange.path, roleChange.definition.content, {
+                ensureDir: true,
+                encoding: 'utf8'
+            });
+            changes.push({
+                target: 'role_file',
+                name: roleChange.definition.key,
+                path: roleChange.path,
+                status: roleChange.existingContent === null ? 'created' : 'updated',
+                detail: roleChange.existingContent === null
+                    ? `Created ${roleChange.definition.fileName}.`
+                    : `Overwrote ${roleChange.definition.fileName} because --force was set.`
+            });
+            continue;
+        }
+        changes.push({
+            target: 'role_file',
+            name: roleChange.definition.key,
+            path: roleChange.path,
+            status: roleChange.currentStatus,
+            detail: roleChange.detail
+        });
+    }
+    return {
+        status: 'applied',
+        plan,
+        changes
+    };
+}
+export function formatCodexDefaultsSetupSummary(result) {
+    const lines = [];
+    lines.push(`Codex defaults setup: ${result.status}`);
+    lines.push(`- Codex home: ${result.plan.codexHome}`);
+    lines.push(`- Config: ${result.plan.configPath}`);
+    lines.push(`- Agents dir: ${result.plan.agentsDir}`);
+    lines.push(`- Force overwrite: ${result.plan.force ? 'yes' : 'no'}`);
+    lines.push('- Changes:');
+    for (const change of result.changes) {
+        lines.push(`  - ${change.target}:${change.name} -> ${change.status} (${change.path})`);
+        lines.push(`    ${change.detail}`);
+    }
+    if (result.status === 'planned') {
+        lines.push('Run with --yes to apply this setup.');
+    }
+    return lines;
+}
+function buildPlan(env, force) {
+    const codexHome = resolveCodexHome(env);
+    return {
+        codexHome,
+        configPath: join(codexHome, 'config.toml'),
+        agentsDir: join(codexHome, 'agents'),
+        force
+    };
+}
+async function loadConfigState(configPath) {
+    if (!existsSync(configPath)) {
+        return { exists: false, parsed: {} };
+    }
+    const raw = await readFile(configPath, 'utf8');
+    try {
+        const parsed = toml.parse(raw);
+        if (!isRecord(parsed)) {
+            throw new Error('top-level TOML document must be a table.');
+        }
+        return { exists: true, parsed: parsed };
+    }
+    catch (error) {
+        const reason = error?.message ?? String(error);
+        throw new Error(`Failed to parse Codex config TOML at ${configPath}: ${reason}`);
+    }
+}
+function mergeBaselineDefaults(existing, roleDefinitions) {
+    const next = structuredClone(existing);
+    next.model = BASELINE_MODEL;
+    next.model_reasoning_effort = BASELINE_REASONING;
+    const agents = isRecord(next.agents) ? structuredClone(next.agents) : {};
+    agents.max_threads = BASELINE_AGENTS.max_threads;
+    agents.max_depth = BASELINE_AGENTS.max_depth;
+    agents.max_spawn_depth = BASELINE_AGENTS.max_spawn_depth;
+    for (const role of roleDefinitions) {
+        const existingRole = isRecord(agents[role.key])
+            ? structuredClone(agents[role.key])
+            : {};
+        existingRole.description = role.description;
+        existingRole.config_file = role.configFile;
+        agents[role.key] = existingRole;
+    }
+    next.agents = agents;
+    return next;
+}
+async function planRoleChanges(agentsDir, force, roleDefinitions) {
+    const changes = [];
+    for (const definition of roleDefinitions) {
+        const path = join(agentsDir, definition.fileName);
+        if (!existsSync(path)) {
+            changes.push({
+                definition,
+                path,
+                existingContent: null,
+                currentStatus: 'pending',
+                detail: `Will create ${definition.fileName}.`
+            });
+            continue;
+        }
+        const current = await readFile(path, 'utf8');
+        if (current === definition.content) {
+            changes.push({
+                definition,
+                path,
+                existingContent: current,
+                currentStatus: 'unchanged',
+                detail: `${definition.fileName} already matches CO baseline defaults.`
+            });
+            continue;
+        }
+        if (force) {
+            changes.push({
+                definition,
+                path,
+                existingContent: current,
+                currentStatus: 'pending',
+                detail: `Will overwrite ${definition.fileName} because --force is set.`
+            });
+            continue;
+        }
+        changes.push({
+            definition,
+            path,
+            existingContent: current,
+            currentStatus: 'preserved',
+            detail: `${definition.fileName} already exists; preserving without --force.`
+        });
+    }
+    return changes;
+}
+async function loadRoleDefinitions() {
+    const packageRoot = findPackageRoot();
+    const loaded = [];
+    for (const definition of ROLE_DEFINITIONS) {
+        const templateFile = join(packageRoot, definition.templatePath);
+        let content;
+        try {
+            content = await readFile(templateFile, 'utf8');
+        }
+        catch (error) {
+            const reason = error?.message ?? String(error);
+            throw new Error(`Unable to read role template ${templateFile}: ${reason}`);
+        }
+        loaded.push({ ...definition, content });
+    }
+    return loaded;
+}
+function buildPlannedChanges(params) {
+    const changes = [];
+    const configStatus = params.configChanged || !params.configExists ? 'pending' : 'unchanged';
+    changes.push({
+        target: 'config',
+        name: 'config.toml',
+        path: params.configPath,
+        status: configStatus,
+        detail: configStatus === 'pending'
+            ? params.configExists
+                ? 'Will update CO baseline defaults additively while preserving unrelated keys.'
+                : 'Will create config.toml with CO baseline defaults.'
+            : 'CO baseline defaults already present.'
+    });
+    for (const roleChange of params.roleChanges) {
+        changes.push({
+            target: 'role_file',
+            name: roleChange.definition.key,
+            path: roleChange.path,
+            status: roleChange.currentStatus,
+            detail: roleChange.detail
+        });
+    }
+    return changes;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}

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/doctor.js

@@ -1,15 +1,19 @@
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { buildDevtoolsSetupPlan, DEVTOOLS_SKILL_NAME, resolveDevtoolsReadiness } from './utils/devtools.js';
 import { isManagedCodexCliEnabled, resolveCodexCliBin, resolveCodexCliReadiness } from './utils/codexCli.js';
 import { resolveCodexHome } from './utils/codexPaths.js';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
 import { runCloudPreflight } from './utils/cloudPreflight.js';
+import { BASELINE_AGENTS, BASELINE_MODEL, BASELINE_REASONING_MINIMUM } from './codexDefaultsSetup.js';
 import { CommandPlanner } from './adapters/CommandPlanner.js';
 import { PipelineResolver } from './services/pipelineResolver.js';
 import { isRepoConfigRequired } from './config/repoConfigPolicy.js';
+const require = createRequire(import.meta.url);
+const toml = require('@iarna/toml');
 const OPTIONAL_DEPENDENCIES = [
     {
         name: 'playwright',
@@ -75,6 +79,7 @@ export function runDoctor(cwd = process.cwd()) {
     if (readiness.config.status !== 'ok') {
         missing.push(`${DEVTOOLS_SKILL_NAME}-config`);
     }
+    const codexDefaults = inspectCodexDefaultsAdvisory(process.env);
     const codexBin = resolveCodexCliBin(process.env);
     const managedOptIn = isManagedCodexCliEnabled(process.env);
     const managedCodex = resolveCodexCliReadiness(process.env);
@@ -102,7 +107,7 @@ export function runDoctor(cwd = process.cwd()) {
     const delegationConfig = inspectDelegationConfig();
     const delegationStatus = delegationConfig.status === 'ok' ? 'ok' : 'missing-config';
     return {
-        status: missing.length === 0 ? 'ok' : 'warning',
+        status: missing.length === 0 && codexDefaults.status === 'ok' ? 'ok' : 'warning',
         missing,
         dependencies,
         devtools,
@@ -110,6 +115,7 @@ export function runDoctor(cwd = process.cwd()) {
             active: { command: codexBin, managed_opt_in: managedOptIn },
             managed: managedCodex
         },
+        codex_defaults: codexDefaults,
         collab: {
             status: collabStatus,
             enabled: collabEnabled,
@@ -296,6 +302,19 @@ export function formatDoctorSummary(result) {
             lines.push(`  - version: ${result.codex_cli.managed.install.version}`);
         }
     }
+    lines.push(`Codex defaults advisory: ${result.codex_defaults.status}`);
+    lines.push(`  - config.toml: ${result.codex_defaults.config.status} (${result.codex_defaults.config.path})`);
+    if (result.codex_defaults.config.detail) {
+        lines.push(`    detail: ${result.codex_defaults.config.detail}`);
+    }
+    lines.push(`  - model: ${result.codex_defaults.checks.model.status} (actual: ${result.codex_defaults.checks.model.actual ?? '<unset>'}, expected: ${result.codex_defaults.checks.model.expected})`);
+    lines.push(`  - model_reasoning_effort: ${result.codex_defaults.checks.model_reasoning_effort.status} (actual: ${result.codex_defaults.checks.model_reasoning_effort.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.model_reasoning_effort.expected_minimum})`);
+    lines.push(`  - agents.max_threads: ${result.codex_defaults.checks.max_threads.status} (actual: ${result.codex_defaults.checks.max_threads.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.max_threads.expected_minimum})`);
+    lines.push(`  - agents.max_depth: ${result.codex_defaults.checks.max_depth.status} (actual: ${result.codex_defaults.checks.max_depth.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.max_depth.expected_minimum})`);
+    lines.push(`  - agents.max_spawn_depth: ${result.codex_defaults.checks.max_spawn_depth.status} (actual: ${result.codex_defaults.checks.max_spawn_depth.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.max_spawn_depth.expected_minimum})`);
+    for (const line of result.codex_defaults.guidance) {
+        lines.push(`  - ${line}`);
+    }
     lines.push(`Collab: ${result.collab.status}`);
     if (result.collab.enabled !== null) {
         lines.push(`  - enabled: ${result.collab.enabled}`);
@@ -326,6 +345,118 @@ export function formatDoctorSummary(result) {
     }
     return lines;
 }
+function inspectCodexDefaultsAdvisory(env = process.env) {
+    const configPath = join(resolveCodexHome(env), 'config.toml');
+    const checks = {
+        model: { status: 'advisory', expected: BASELINE_MODEL, actual: null },
+        model_reasoning_effort: { status: 'advisory', expected_minimum: BASELINE_REASONING_MINIMUM, actual: null },
+        max_threads: { status: 'advisory', expected_minimum: BASELINE_AGENTS.max_threads, actual: null },
+        max_depth: { status: 'advisory', expected_minimum: BASELINE_AGENTS.max_depth, actual: null },
+        max_spawn_depth: { status: 'advisory', expected_minimum: BASELINE_AGENTS.max_spawn_depth, actual: null }
+    };
+    const guidance = [
+        'Run `codex-orchestrator codex defaults --yes` to apply additive baseline defaults.',
+        'Additive policy: unrelated config keys are preserved; existing role files stay untouched unless `--force` is set.'
+    ];
+    if (!existsSync(configPath)) {
+        return {
+            status: 'advisory',
+            config: { path: configPath, status: 'missing', detail: 'config.toml not found' },
+            checks,
+            guidance
+        };
+    }
+    let parsed;
+    try {
+        const raw = readFileSync(configPath, 'utf8');
+        const value = toml.parse(raw);
+        if (!isRecord(value)) {
+            throw new Error('top-level TOML document must be a table.');
+        }
+        parsed = value;
+    }
+    catch (error) {
+        return {
+            status: 'advisory',
+            config: {
+                path: configPath,
+                status: 'invalid',
+                detail: error instanceof Error ? error.message : String(error)
+            },
+            checks,
+            guidance: [
+                `Fix TOML syntax in ${configPath} first, then rerun \`codex-orchestrator codex defaults --yes\`.`,
+                ...guidance
+            ]
+        };
+    }
+    const model = normalizeOptionalString(readStringValue(parsed.model));
+    checks.model.actual = model;
+    checks.model.status = model === BASELINE_MODEL ? 'ok' : 'advisory';
+    const reasoning = normalizeOptionalString(readStringValue(parsed.model_reasoning_effort));
+    checks.model_reasoning_effort.actual = reasoning;
+    checks.model_reasoning_effort.status = isReasoningAtLeastMinimum(reasoning, BASELINE_REASONING_MINIMUM)
+        ? 'ok'
+        : 'advisory';
+    const agents = isRecord(parsed.agents) ? parsed.agents : {};
+    const maxThreads = readNumberValue(agents.max_threads);
+    const maxDepth = readNumberValue(agents.max_depth);
+    const maxSpawnDepth = readNumberValue(agents.max_spawn_depth);
+    checks.max_threads.actual = maxThreads;
+    checks.max_threads.status =
+        typeof maxThreads === 'number' && maxThreads >= BASELINE_AGENTS.max_threads ? 'ok' : 'advisory';
+    checks.max_depth.actual = maxDepth;
+    checks.max_depth.status = typeof maxDepth === 'number' && maxDepth >= BASELINE_AGENTS.max_depth ? 'ok' : 'advisory';
+    checks.max_spawn_depth.actual = maxSpawnDepth;
+    checks.max_spawn_depth.status =
+        typeof maxSpawnDepth === 'number' && maxSpawnDepth >= BASELINE_AGENTS.max_spawn_depth ? 'ok' : 'advisory';
+    const allChecksOk = Object.values(checks).every((check) => check.status === 'ok');
+    return {
+        status: allChecksOk ? 'ok' : 'advisory',
+        config: { path: configPath, status: 'ok' },
+        checks,
+        guidance
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readStringValue(value) {
+    return typeof value === 'string' ? value : null;
+}
+function readNumberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function isReasoningAtLeastMinimum(value, minimum) {
+    const rank = resolveReasoningRank(value);
+    const minimumRank = resolveReasoningRank(minimum);
+    if (rank === null || minimumRank === null) {
+        return false;
+    }
+    return rank >= minimumRank;
+}
+function resolveReasoningRank(value) {
+    if (!value) {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    switch (normalized) {
+        case 'minimal':
+            return 0;
+        case 'low':
+            return 1;
+        case 'medium':
+            return 2;
+        case 'high':
+            return 3;
+        case 'xhigh':
+            return 4;
+        case 'maximum':
+            return 5;
+        default:
+            return null;
+    }
+}
 function normalizeOptionalString(value) {
     if (typeof value !== 'string') {
         return null;

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

@@ -10,9 +10,10 @@ Purpose:
 export async function writeDoctorIssueLog(options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const env = options.env ?? process.env;
-    const repoRoot = resolveIssueLogRepoRoot(cwd, env);
-    const runsRoot = resolveIssueLogRootPath(repoRoot, env.CODEX_ORCHESTRATOR_RUNS_DIR, '.runs');
-    const outRoot = resolveIssueLogRootPath(repoRoot, env.CODEX_ORCHESTRATOR_OUT_DIR, 'out');
+    const explicitCwd = options.cwd !== undefined;
+    const repoRoot = resolveIssueLogRepoRoot(cwd, env, explicitCwd);
+    const runsRoot = resolveIssueLogRootPath(repoRoot, env.CODEX_ORCHESTRATOR_RUNS_DIR, '.runs', explicitCwd);
+    const outRoot = resolveIssueLogRootPath(repoRoot, env.CODEX_ORCHESTRATOR_OUT_DIR, 'out', explicitCwd);
     const defaultTaskId = normalizeIssueLogTaskId(env);
     const capturedAt = new Date().toISOString();
     const issueId = formatIssueId(capturedAt);
@@ -95,14 +96,31 @@ function resolveIssueLogPath(repoRoot, rawPath) {
     }
     return resolve(repoRoot, normalized);
 }
-function resolveIssueLogRepoRoot(cwd, env) {
+function resolveIssueLogRepoRoot(cwd, env, explicitCwd) {
+    const cwdResolution = resolveRepoRootFromHint(cwd);
     const configuredRoot = normalizeText(env.CODEX_ORCHESTRATOR_ROOT);
-    const rootHint = configuredRoot === null
-        ? cwd
-        : isAbsolute(configuredRoot)
-            ? configuredRoot
-            : resolve(cwd, configuredRoot);
-    return resolveRepoRootFromHint(rootHint);
+    if (configuredRoot === null) {
+        return cwdResolution.root;
+    }
+    const configuredHint = isAbsolute(configuredRoot) ? configuredRoot : resolve(cwd, configuredRoot);
+    const configuredResolution = resolveRepoRootFromHint(configuredHint);
+    if (!explicitCwd) {
+        return configuredResolution.root;
+    }
+    // Keep explicit override behavior when cwd is inside the configured workspace.
+    if (isPathWithin(cwd, configuredResolution.root)) {
+        // If cwd sits under a nested workspace boundary, prefer that more local workspace.
+        if (cwdResolution.source !== 'hint' && cwdResolution.root !== configuredResolution.root) {
+            return cwdResolution.root;
+        }
+        return configuredResolution.root;
+    }
+    // If cwd clearly belongs to another workspace (tasks index or git boundary), prefer cwd.
+    if (cwdResolution.source !== 'hint') {
+        return cwdResolution.root;
+    }
+    // Fallback to configured root when cwd has no strong workspace signals.
+    return configuredResolution.root;
 }
 function resolveRepoRootFromHint(rootHint) {
     const normalizedHint = resolve(rootHint);
@@ -110,7 +128,7 @@ function resolveRepoRootFromHint(rootHint) {
     let current = normalizedHint;
     while (current) {
         if (existsSync(join(current, 'tasks', 'index.json'))) {
-            return current;
+            return { root: current, source: 'tasks-index' };
         }
         if (gitBoundary && current === gitBoundary) {
             break;
@@ -121,7 +139,10 @@ function resolveRepoRootFromHint(rootHint) {
         }
         current = parent;
     }
-    return gitBoundary ?? normalizedHint;
+    if (gitBoundary) {
+        return { root: gitBoundary, source: 'git-boundary' };
+    }
+    return { root: normalizedHint, source: 'hint' };
 }
 function findNearestGitBoundary(start) {
     let current = resolve(start);
@@ -137,15 +158,20 @@ function findNearestGitBoundary(start) {
     }
     return null;
 }
-function resolveIssueLogRootPath(repoRoot, configuredPath, fallback) {
+function resolveIssueLogRootPath(repoRoot, configuredPath, fallback, enforceRepoBoundary) {
     const normalized = normalizeText(configuredPath);
     if (!normalized) {
         return resolve(repoRoot, fallback);
     }
-    if (isAbsolute(normalized)) {
-        return normalized;
+    const resolvedPath = isAbsolute(normalized) ? normalized : resolve(repoRoot, normalized);
+    if (enforceRepoBoundary && !isPathWithin(resolvedPath, repoRoot)) {
+        return resolve(repoRoot, fallback);
     }
-    return resolve(repoRoot, normalized);
+    return resolvedPath;
+}
+function isPathWithin(candidatePath, rootPath) {
+    const rel = relative(rootPath, candidatePath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
 function normalizeIssueLogTaskId(env) {
     return normalizeArtifactTaskId(normalizeText(env.MCP_RUNNER_TASK_ID)

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