@kbediako/codex-orchestrator 0.1.20 → 0.1.22

package/README.md

@@ -89,7 +89,7 @@ Delegation guard profile:
 ## Delegation + RLM flow
 
 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 when delegated, when `RLM_CONTEXT_PATH` is set, or when the context exceeds `RLM_SYMBOLIC_MIN_BYTES`; 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.
-Symbolic subcalls can optionally use collab tools when `RLM_SYMBOLIC_COLLAB=1` (requires `collab=true` in `codex features list`). Collab tool calls parsed from `codex exec --json --enable collab` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path.
+Symbolic subcalls can optionally use collab tools. Fast path: `codex-orchestrator rlm --collab "<goal>"` (sets `RLM_SYMBOLIC_COLLAB=1` and implies symbolic mode). Collab requires `collab=true` in `codex features list`. Collab tool calls parsed from `codex exec --json --enable collab` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path.
 
 ### Delegation flow
 ```mermaid
@@ -137,14 +137,17 @@ codex-orchestrator skills install
 
 Options:
 - `--force` overwrites existing files.
+- `--only <skills>` installs only selected skills (comma-separated). Combine with `--force` to overwrite only those.
 - `--codex-home <path>` targets a different Codex home directory.
 
 Bundled skills (may vary by release):
+- `collab-subagents-first`
 - `delegation-usage`
 - `standalone-review`
 - `docs-first`
 - `collab-evals`
 - `collab-deliberation`
+- `release`
 - `delegate-early` (compatibility alias; use `delegation-usage`)
 
 ## DevTools readiness

package/dist/bin/codex-orchestrator.js

@@ -167,6 +167,25 @@ function applyRlmEnvOverrides(flags, goal) {
     if (goal) {
         process.env.RLM_GOAL = goal;
     }
+    const collabRaw = flags['collab'];
+    if (collabRaw !== undefined) {
+        const normalized = typeof collabRaw === 'string' ? collabRaw.trim().toLowerCase() : collabRaw === true ? 'true' : '';
+        const enabled = collabRaw === true || normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'auto';
+        const disabled = normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off';
+        if (enabled) {
+            process.env.RLM_SYMBOLIC_COLLAB = '1';
+            // Collab is only used in the symbolic loop; make the flag do what users expect.
+            if (!process.env.RLM_MODE) {
+                process.env.RLM_MODE = 'symbolic';
+            }
+        }
+        else if (disabled) {
+            process.env.RLM_SYMBOLIC_COLLAB = '0';
+        }
+        else if (typeof collabRaw === 'string') {
+            throw new Error('Invalid --collab value. Use --collab (or: --collab auto|true|false).');
+        }
+    }
     const validator = readStringFlag(flags, 'validator');
     if (validator) {
         process.env.RLM_VALIDATOR = validator;
@@ -605,7 +624,15 @@ async function handleSkills(rawArgs) {
             const format = flags['format'] === 'json' ? 'json' : 'text';
             const force = flags['force'] === true;
             const codexHome = readStringFlag(flags, 'codex-home');
-            const result = await installSkills({ force, codexHome });
+            const onlyRaw = flags['only'];
+            let only;
+            if (onlyRaw !== undefined) {
+                if (typeof onlyRaw !== 'string') {
+                    throw new Error('--only requires a comma-separated list of skill names.');
+                }
+                only = onlyRaw.split(',').map((entry) => entry.trim()).filter(Boolean);
+            }
+            const result = await installSkills({ force, codexHome, only });
             if (format === 'json') {
                 console.log(JSON.stringify(result, null, 2));
             }
@@ -871,6 +898,7 @@ Commands:
     --cloud                 Shortcut for --execution-mode cloud.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
     --goal "<goal>"         When pipeline is rlm, set the RLM goal.
+    --collab [auto|true|false]  When pipeline is rlm, enable collab subagents (implies symbolic mode).
     --validator <cmd|none>  When pipeline is rlm, set the validator command.
     --max-iterations <n>    When pipeline is rlm, override max iterations.
     --max-minutes <n>       When pipeline is rlm, override max minutes.
@@ -880,6 +908,7 @@ Commands:
 
   rlm "<goal>"              Run RLM loop until validator passes.
     --task <id>             Override task identifier.
+    --collab [auto|true|false]  Enable collab subagents (implies symbolic mode).
     --validator <cmd|none>  Set validator command or disable validation.
     --max-iterations <n>    Override max iterations (0 = unlimited with validator).
     --max-minutes <n>       Optional time-based guardrail in minutes.
@@ -946,6 +975,7 @@ Commands:
     --format json         Emit machine-readable output (dry-run only).
   skills install          Install bundled skills into $CODEX_HOME/skills.
     --force               Overwrite existing skill files.
+    --only <skills>       Install only selected skills (comma-separated).
     --codex-home <path>   Override the target Codex home directory.
     --format json         Emit machine-readable output.
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
@@ -972,6 +1002,7 @@ function printSkillsHelp() {
 Commands:
   install                   Install bundled skills into $CODEX_HOME/skills.
     --force                 Overwrite existing skill files.
+    --only <skills>         Install only selected skills (comma-separated).
     --codex-home <path>     Override the target Codex home directory.
     --format json           Emit machine-readable output.
 `);

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

@@ -8,6 +8,22 @@ export class CommandReviewer {
         const result = this.requireResult();
         if (input.mode === 'cloud') {
             const cloudExecution = result.manifest.cloud_execution;
+            if (!cloudExecution) {
+                const summaryLines = [
+                    result.success
+                        ? 'Cloud mode requested but preflight failed; fell back to MCP mode successfully.'
+                        : 'Cloud mode requested but preflight failed; fell back to MCP mode and the run failed.',
+                    `Manifest: ${result.manifestPath}`,
+                    `Runner log: ${result.logPath}`
+                ];
+                return {
+                    summary: summaryLines.join('\n'),
+                    decision: {
+                        approved: result.success,
+                        feedback: result.notes.join('\n') || result.manifest.summary || undefined
+                    }
+                };
+            }
             const status = cloudExecution?.status ?? 'unknown';
             const cloudTask = cloudExecution?.task_id ?? '<unknown>';
             const approved = status === 'ready' && result.success;

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

@@ -9,6 +9,31 @@ export class CommandTester {
         const result = this.requireResult();
         if (input.mode === 'cloud') {
             const cloudExecution = result.manifest.cloud_execution;
+            if (!cloudExecution) {
+                // Cloud mode can fall back to MCP when preflight fails; treat that as a normal guardrail run.
+                const guardrailStatus = ensureGuardrailStatus(result.manifest);
+                const reports = [
+                    {
+                        name: 'cloud-preflight',
+                        status: 'passed',
+                        details: result.manifest.summary?.trim() ||
+                            'Cloud execution was skipped due to preflight failure; fell back to MCP mode.'
+                    },
+                    {
+                        name: 'guardrails',
+                        status: guardrailStatus.present ? 'passed' : 'failed',
+                        details: guardrailStatus.present
+                            ? guardrailStatus.summary
+                            : guardrailStatus.recommendation ?? guardrailStatus.summary
+                    }
+                ];
+                return {
+                    subtaskId: input.build.subtaskId,
+                    success: guardrailStatus.present && result.success,
+                    reports,
+                    runId: input.runId
+                };
+            }
             const status = cloudExecution?.status ?? 'unknown';
             const passed = status === 'ready' && result.success;
             const diagnosis = diagnoseCloudFailure({

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

@@ -1,5 +1,10 @@
 import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { buildDevtoolsSetupPlan, DEVTOOLS_SKILL_NAME, resolveDevtoolsReadiness } from './utils/devtools.js';
+import { resolveCodexCliBin, resolveCodexCliReadiness } from './utils/codexCli.js';
+import { resolveCodexHome } from './utils/codexPaths.js';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
 const OPTIONAL_DEPENDENCIES = [
     {
@@ -65,11 +70,56 @@ export function runDoctor(cwd = process.cwd()) {
     if (readiness.config.status !== 'ok') {
         missing.push(`${DEVTOOLS_SKILL_NAME}-config`);
     }
+    const codexBin = resolveCodexCliBin(process.env);
+    const managedCodex = resolveCodexCliReadiness(process.env);
+    const features = readCodexFeatureFlags(codexBin);
+    const collabEnabled = features?.collab ?? null;
+    const collabStatus = features === null ? 'unavailable' : collabEnabled ? 'ok' : 'disabled';
+    const cloudCmdAvailable = canRunCommand(codexBin, ['cloud', '--help']);
+    const cloudEnvIdConfigured = typeof process.env.CODEX_CLOUD_ENV_ID === 'string' && process.env.CODEX_CLOUD_ENV_ID.trim().length > 0;
+    const cloudBranch = typeof process.env.CODEX_CLOUD_BRANCH === 'string' && process.env.CODEX_CLOUD_BRANCH.trim().length > 0
+        ? process.env.CODEX_CLOUD_BRANCH.trim().replace(/^refs\/heads\//u, '')
+        : null;
+    const cloudStatus = !cloudCmdAvailable ? 'unavailable' : cloudEnvIdConfigured ? 'ok' : 'not_configured';
+    const delegationConfig = inspectDelegationConfig();
+    const delegationStatus = delegationConfig.status === 'ok' ? 'ok' : 'missing-config';
     return {
         status: missing.length === 0 ? 'ok' : 'warning',
         missing,
         dependencies,
-        devtools
+        devtools,
+        codex_cli: {
+            active: { command: codexBin },
+            managed: managedCodex
+        },
+        collab: {
+            status: collabStatus,
+            enabled: collabEnabled,
+            enablement: [
+                'Enable collab for symbolic RLM runs with: codex-orchestrator rlm --collab "<goal>"',
+                'Or set: RLM_SYMBOLIC_COLLAB=1 (implies symbolic mode when using --collab).',
+                'If collab is disabled in codex features: codex features enable collab'
+            ]
+        },
+        cloud: {
+            status: cloudStatus,
+            env_id_configured: cloudEnvIdConfigured,
+            branch: cloudBranch,
+            enablement: [
+                'Set CODEX_CLOUD_ENV_ID to a valid Codex Cloud environment id.',
+                'Optional: set CODEX_CLOUD_BRANCH (must exist on origin).',
+                'Then run a pipeline stage in cloud mode with: codex-orchestrator start <pipeline> --cloud --target <stage-id>'
+            ]
+        },
+        delegation: {
+            status: delegationStatus,
+            config: delegationConfig,
+            enablement: [
+                `Run: codex mcp add delegation -- codex-orchestrator delegate-server --repo ${cwd}`,
+                "Enable for a run with: codex -c 'mcp_servers.delegation.enabled=true' ...",
+                'See: codex-orchestrator init codex'
+            ]
+        }
     };
 }
 export function formatDoctorSummary(result) {
@@ -118,5 +168,164 @@ export function formatDoctorSummary(result) {
     for (const line of result.devtools.enablement) {
         lines.push(`  - ${line}`);
     }
+    lines.push(`Codex CLI: ${result.codex_cli.active.command}`);
+    lines.push(`  - managed: ${result.codex_cli.managed.status} (${result.codex_cli.managed.config.path})`);
+    if (result.codex_cli.managed.status === 'invalid' && result.codex_cli.managed.config.error) {
+        lines.push(`    error: ${result.codex_cli.managed.config.error}`);
+    }
+    if (result.codex_cli.managed.status === 'ok') {
+        lines.push(`  - binary: ${result.codex_cli.managed.binary.status} (${result.codex_cli.managed.binary.path})`);
+        if (result.codex_cli.managed.install?.version) {
+            lines.push(`  - version: ${result.codex_cli.managed.install.version}`);
+        }
+    }
+    lines.push(`Collab: ${result.collab.status}`);
+    if (result.collab.enabled !== null) {
+        lines.push(`  - enabled: ${result.collab.enabled}`);
+    }
+    for (const line of result.collab.enablement) {
+        lines.push(`  - ${line}`);
+    }
+    lines.push(`Cloud: ${result.cloud.status}`);
+    lines.push(`  - CODEX_CLOUD_ENV_ID: ${result.cloud.env_id_configured ? 'set' : 'missing'}`);
+    lines.push(`  - CODEX_CLOUD_BRANCH: ${result.cloud.branch ?? '<unset>'}`);
+    for (const line of result.cloud.enablement) {
+        lines.push(`  - ${line}`);
+    }
+    lines.push(`Delegation: ${result.delegation.status}`);
+    const delegationConfigLabel = result.delegation.config.status === 'ok'
+        ? `ok (${result.delegation.config.path})`
+        : `missing (${result.delegation.config.path})`;
+    lines.push(`  - config.toml: ${delegationConfigLabel}`);
+    if (result.delegation.config.detail) {
+        lines.push(`    detail: ${result.delegation.config.detail}`);
+    }
+    for (const line of result.delegation.enablement) {
+        lines.push(`  - ${line}`);
+    }
     return lines;
 }
+function readCodexFeatureFlags(codexBin) {
+    const result = spawnSync(codexBin, ['features', 'list'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5000
+    });
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    const stdout = String(result.stdout ?? '');
+    const flags = {};
+    for (const line of stdout.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const tokens = trimmed.split(/\s+/u);
+        if (tokens.length < 2) {
+            continue;
+        }
+        const name = tokens[0] ?? '';
+        const enabledToken = tokens[tokens.length - 1] ?? '';
+        if (!name) {
+            continue;
+        }
+        if (enabledToken === 'true') {
+            flags[name] = true;
+        }
+        else if (enabledToken === 'false') {
+            flags[name] = false;
+        }
+    }
+    return flags;
+}
+function canRunCommand(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 5000
+    });
+    if (result.error) {
+        return false;
+    }
+    return result.status === 0;
+}
+function inspectDelegationConfig(env = process.env) {
+    const codexHome = resolveCodexHome(env);
+    const configPath = join(codexHome, 'config.toml');
+    if (!existsSync(configPath)) {
+        return { status: 'missing', path: configPath, detail: 'config.toml not found' };
+    }
+    try {
+        const raw = readFileSync(configPath, 'utf8');
+        const hasEntry = hasMcpServerEntry(raw, 'delegation');
+        if (hasEntry) {
+            return { status: 'ok', path: configPath };
+        }
+        return { status: 'missing', path: configPath, detail: 'mcp_servers.delegation entry not found' };
+    }
+    catch (error) {
+        return {
+            status: 'missing',
+            path: configPath,
+            detail: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function hasMcpServerEntry(raw, serverName) {
+    const lines = raw.split('\n');
+    let currentTable = null;
+    for (const line of lines) {
+        const trimmed = stripTomlComment(line).trim();
+        if (!trimmed) {
+            continue;
+        }
+        const tableMatch = trimmed.match(/^\[(.+)\]$/u);
+        if (tableMatch) {
+            currentTable = tableMatch[1]?.trim() ?? null;
+            if (currentTable === `mcp_servers.${serverName}` ||
+                currentTable === `mcp_servers."${serverName}"` ||
+                currentTable === `mcp_servers.'${serverName}'`) {
+                return true;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('mcp_servers.')) {
+            if (trimmed.startsWith(`mcp_servers."${serverName}".`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.'${serverName}'.`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.${serverName}.`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers."${serverName}"=`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.'${serverName}'=`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.${serverName}=`)) {
+                return true;
+            }
+        }
+        if (currentTable === 'mcp_servers') {
+            const entryPattern = new RegExp(`^"?${escapeRegExp(serverName)}"?\\s*=`, 'u');
+            if (entryPattern.test(trimmed)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function stripTomlComment(line) {
+    const index = line.indexOf('#');
+    if (index === -1) {
+        return line;
+    }
+    return line.slice(0, index);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -31,6 +31,7 @@ import { CLI_EXECUTION_MODE_PARSER, resolveRequiresCloudPolicy } from '../utils/
 import { resolveCodexCliBin } from './utils/codexCli.js';
 import { CodexCloudTaskExecutor } from '../cloud/CodexCloudTaskExecutor.js';
 import { persistPipelineExperience } from './services/pipelineExperience.js';
+import { runCloudPreflight } from './utils/cloudPreflight.js';
 const resolveBaseEnvironment = () => normalizeEnvironmentPaths(resolveEnvironmentPaths());
 const CONFIG_OVERRIDE_ENV_KEYS = ['CODEX_CONFIG_OVERRIDES', 'CODEX_MCP_CONFIG_OVERRIDES'];
 const DEFAULT_CLOUD_POLL_INTERVAL_SECONDS = 10;
@@ -552,6 +553,27 @@ export class CodexOrchestrator {
     }
     async executePipeline(options) {
         if (options.mode === 'cloud') {
+            const environmentId = resolveCloudEnvironmentId(options.task, options.target, options.envOverrides);
+            const branch = readCloudString(options.envOverrides?.CODEX_CLOUD_BRANCH) ??
+                readCloudString(process.env.CODEX_CLOUD_BRANCH);
+            const mergedEnv = { ...process.env, ...(options.envOverrides ?? {}) };
+            const codexBin = resolveCodexCliBin(mergedEnv);
+            const preflight = await runCloudPreflight({
+                repoRoot: options.env.repoRoot,
+                codexBin,
+                environmentId,
+                branch,
+                env: mergedEnv
+            });
+            if (!preflight.ok) {
+                const detail = `Cloud preflight failed; falling back to mcp. ` +
+                    preflight.issues.map((issue) => issue.message).join(' ');
+                appendSummary(options.manifest, detail);
+                logger.warn(detail);
+                const fallback = await this.executePipeline({ ...options, mode: 'mcp', executionModeOverride: 'mcp' });
+                fallback.notes.unshift(detail);
+                return fallback;
+            }
             return await this.executeCloudPipeline(options);
         }
         const { env, pipeline, manifest, paths, runEvents, envOverrides } = options;
@@ -883,6 +905,12 @@ export class CodexOrchestrator {
                     const disableFeatures = readCloudFeatureList(readCloudString(envOverrides?.CODEX_CLOUD_DISABLE_FEATURES) ??
                         readCloudString(process.env.CODEX_CLOUD_DISABLE_FEATURES));
                     const codexBin = resolveCodexCliBin({ ...process.env, ...(envOverrides ?? {}) });
+                    const cloudEnvOverrides = {
+                        ...(envOverrides ?? {}),
+                        CODEX_NON_INTERACTIVE: envOverrides?.CODEX_NON_INTERACTIVE ?? process.env.CODEX_NON_INTERACTIVE ?? '1',
+                        CODEX_NO_INTERACTIVE: envOverrides?.CODEX_NO_INTERACTIVE ?? process.env.CODEX_NO_INTERACTIVE ?? '1',
+                        CODEX_INTERACTIVE: envOverrides?.CODEX_INTERACTIVE ?? process.env.CODEX_INTERACTIVE ?? '0'
+                    };
                     const cloudResult = await executor.execute({
                         codexBin,
                         prompt,
@@ -895,7 +923,7 @@ export class CodexOrchestrator {
                         branch,
                         enableFeatures,
                         disableFeatures,
-                        env: envOverrides
+                        env: cloudEnvOverrides
                     });
                     success = cloudResult.success;
                     notes.push(...cloudResult.notes);

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

@@ -53,6 +53,7 @@ export async function persistPipelineExperience(params) {
             maxSummaryWords: instructions.experienceMaxWords
         });
         await store.recordBatch([record], relativeToRepo(env, paths.manifestPath));
+        logger.info(`[experience] Recorded pipeline experience (domain=${domain}, words=${tokenCount}) for ${pipeline.id} run ${manifest.run_id}.`);
     }
     catch (error) {
         logger.warn(`Failed to persist pipeline experience for run ${manifest.run_id}: ${error?.message ?? String(error)}`);

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

@@ -12,18 +12,28 @@ export async function installSkills(options = {}) {
     const targetRoot = join(codexHome, 'skills');
     const written = [];
     const skipped = [];
-    const skillNames = await listSkillNames(sourceRoot);
-    await copyDir(sourceRoot, targetRoot, {
+    const availableSkills = await listSkillNames(sourceRoot);
+    const selectedSkills = resolveSelectedSkills(availableSkills, options.only);
+    const copyOptions = {
         force: options.force ?? false,
         written,
         skipped
-    });
+    };
+    if (selectedSkills.length === availableSkills.length) {
+        await copyDir(sourceRoot, targetRoot, copyOptions);
+    }
+    else {
+        await mkdir(targetRoot, { recursive: true });
+        for (const skill of selectedSkills) {
+            await copyDir(join(sourceRoot, skill), join(targetRoot, skill), copyOptions);
+        }
+    }
     return {
         written,
         skipped,
         sourceRoot,
         targetRoot,
-        skills: skillNames
+        skills: selectedSkills
     };
 }
 export function formatSkillsInstallSummary(result, cwd = process.cwd()) {
@@ -61,6 +71,22 @@ async function listSkillNames(sourceRoot) {
     const entries = await readdir(sourceRoot, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
+function resolveSelectedSkills(availableSkills, only) {
+    if (!only) {
+        return availableSkills;
+    }
+    const trimmed = only.map((entry) => entry.trim()).filter(Boolean);
+    if (trimmed.length === 0) {
+        throw new Error('No skills specified for --only.');
+    }
+    const requested = Array.from(new Set(trimmed));
+    const available = new Set(availableSkills);
+    const unknown = requested.filter((skill) => !available.has(skill));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown skill(s): ${unknown.join(', ')}. Available skills: ${availableSkills.join(', ')}`);
+    }
+    return requested;
+}
 async function assertDirectory(path) {
     const info = await stat(path).catch(() => null);
     if (!info || !info.isDirectory()) {

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

@@ -0,0 +1,101 @@
+import { spawn } from 'node:child_process';
+function runCommand(command, args, options) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 4000).unref();
+            resolve({
+                exitCode: 124,
+                stdout,
+                stderr: `${stderr}\nTimed out after ${Math.round(timeoutMs / 1000)}s.`.trim()
+            });
+        }, timeoutMs);
+        timer.unref();
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.once('error', (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode: 1, stdout, stderr: `${stderr}\n${error.message}`.trim() });
+        });
+        child.once('close', (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode: typeof code === 'number' ? code : 1, stdout, stderr });
+        });
+    });
+}
+function normalizeBranch(raw) {
+    const trimmed = String(raw ?? '').trim();
+    if (!trimmed) {
+        return null;
+    }
+    return trimmed.replace(/^refs\/heads\//u, '');
+}
+export async function runCloudPreflight(params) {
+    const issues = [];
+    const branch = normalizeBranch(params.branch);
+    if (!params.environmentId) {
+        issues.push({
+            code: 'missing_environment',
+            message: 'Missing CODEX_CLOUD_ENV_ID (or target metadata.cloudEnvId).'
+        });
+    }
+    const codexCheck = await runCommand(params.codexBin, ['--version'], {
+        cwd: params.repoRoot,
+        env: params.env
+    });
+    if (codexCheck.exitCode !== 0) {
+        issues.push({
+            code: 'codex_unavailable',
+            message: `Codex CLI is unavailable (${params.codexBin} --version failed).`
+        });
+    }
+    if (branch) {
+        const gitCheck = await runCommand('git', ['--version'], { cwd: params.repoRoot, env: params.env });
+        if (gitCheck.exitCode !== 0) {
+            issues.push({ code: 'git_unavailable', message: 'git is unavailable (required for cloud preflight).' });
+        }
+        else {
+            const branchCheck = await runCommand('git', ['ls-remote', '--exit-code', '--heads', 'origin', branch], { cwd: params.repoRoot, env: params.env });
+            if (branchCheck.exitCode !== 0) {
+                issues.push({
+                    code: 'branch_missing',
+                    message: `Cloud branch '${branch}' was not found on origin. Push it first or set CODEX_CLOUD_BRANCH to an existing remote branch.`
+                });
+            }
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        issues,
+        details: {
+            codexBin: params.codexBin,
+            environmentId: params.environmentId,
+            branch
+        }
+    };
+}

package/docs/README.md

@@ -25,7 +25,7 @@ Codex Orchestrator is the coordination layer that glues together Codex-driven ag
 
 ## How It Works
 - **Planner → Builder → Tester → Reviewer:** The core `TaskManager` (see `orchestrator/src/manager.ts`) wires together agent interfaces that decide *what* to run (planner), execute the selected pipeline stage (builder), verify results (tester), and give a final decision (reviewer).
-- **Execution modes:** Each plan item can flag `requires_cloud` and task metadata can set `execution.parallel`; the mode policy picks `mcp` (local MCP runtime) or `cloud` execution accordingly.
+- **Execution modes:** Each plan item can flag `requires_cloud` and task metadata can set `execution.parallel`; the mode policy picks `mcp` (local MCP runtime) or `cloud` execution accordingly. Cloud runs perform a quick preflight (env id, codex availability, optional remote branch) and fall back to `mcp` with a recorded summary when preflight fails.
 - **Event-driven persistence:** Milestones emit typed events on `EventBus`. `PersistenceCoordinator` captures run summaries in the task state store and writes manifests so nothing is lost if the process crashes.
 - **CLI lifecycle:** `CodexOrchestrator` (in `orchestrator/src/cli/orchestrator.ts`) resolves instruction sources (`AGENTS.md`, `docs/AGENTS.md`, `.agent/AGENTS.md`), loads the chosen pipeline, executes each command stage via `runCommandStage`, and keeps heartbeats plus command status current inside the manifest (approval evidence will surface once prompt wiring lands).
 - **Control-plane & scheduler integrations:** Optional validation (`control-plane/`) and scheduling (`scheduler/`) modules enrich manifests with drift checks, plan assignments, and remote run metadata.
@@ -101,9 +101,9 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 ## Companion Package Commands
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (includes `mcp-client.json` and `AGENTS.md`; no overwrite unless `--force`).
-- `codex-orchestrator doctor [--format json]`: check optional tooling dependencies and print install commands.
+- `codex-orchestrator doctor [--format json]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands.
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
-- `codex-orchestrator skills install [--force] [--codex-home <path>]`: install bundled skills into `$CODEX_HOME/skills` (global skills remain the primary reference when installed).
+- `codex-orchestrator skills install [--force] [--only <skills>] [--codex-home <path>]`: install bundled skills into `$CODEX_HOME/skills` (global skills remain the primary reference when installed).
 - `codex-orchestrator self-check --format json`: emit a safe JSON health payload for smoke tests.
 - `codex-orchestrator --version`: print the package version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/collab-subagents-first/SKILL.md

@@ -137,6 +137,7 @@ Do not treat wrapper handoff-only output as a completed review.
 
 - Symptoms: missing collab/delegate tool-call evidence, framing/parsing errors, or unstable collab behavior after CLI upgrades.
 - Check versions first: `codex --version` and `codex-orchestrator --version`.
+- Confirm feature readiness: `codex-orchestrator doctor` (checks collab/cloud/delegation readiness and prints enablement commands).
 - CO repo refresh path (safe default): `scripts/codex-cli-refresh.sh --repo <codex-repo> --no-push`.
 - Rebuild managed CLI only: `codex-orchestrator codex setup --source <codex-repo> --yes --force`.
 - If local codex is materially behind upstream, sync before diagnosing collab behavior differences.