@kbediako/codex-orchestrator 0.1.21 → 0.1.23

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
@@ -152,11 +152,16 @@ Bundled skills (may vary by release):
 
 ## DevTools readiness
 
-Check DevTools readiness (skill + MCP config):
+Check readiness (deps + capability wiring):
 ```bash
 codex-orchestrator doctor --format json
 ```
 
+Usage snapshot (scans local `.runs/`):
+```bash
+codex-orchestrator doctor --usage
+```
+
 Print DevTools MCP setup guidance:
 ```bash
 codex-orchestrator devtools setup
@@ -171,6 +176,7 @@ codex-orchestrator devtools setup
 - `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — optionally provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time).
 - `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.
 - `codex-orchestrator codex setup` — plan/apply a CO-managed Codex CLI install (optional managed/pinned path; use `--download-url` + `--download-sha256` for prebuilts).
+- `codex-orchestrator delegation setup --yes` — configure delegation MCP server wiring.
 - `codex-orchestrator self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
 

package/dist/bin/codex-orchestrator.js

@@ -14,8 +14,10 @@ import { evaluateInteractiveGate } from '../orchestrator/src/cli/utils/interacti
 import { buildSelfCheckResult } from '../orchestrator/src/cli/selfCheck.js';
 import { initCodexTemplates, formatInitSummary } from '../orchestrator/src/cli/init.js';
 import { runDoctor, formatDoctorSummary } from '../orchestrator/src/cli/doctor.js';
+import { formatDoctorUsageSummary, runDoctorUsage } from '../orchestrator/src/cli/doctorUsage.js';
 import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.js';
 import { formatCodexCliSetupSummary, runCodexCliSetup } from '../orchestrator/src/cli/codexCliSetup.js';
+import { formatDelegationSetupSummary, runDelegationSetup } from '../orchestrator/src/cli/delegationSetup.js';
 import { formatSkillsInstallSummary, installSkills } from '../orchestrator/src/cli/skills.js';
 import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { slugify } from '../orchestrator/src/cli/utils/strings.js';
@@ -85,6 +87,9 @@ async function main() {
             case 'delegation-server':
                 await handleDelegationServer(args);
                 break;
+            case 'delegation':
+                await handleDelegation(args);
+                break;
             case 'version':
                 printVersion();
                 break;
@@ -167,6 +172,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;
@@ -313,6 +337,16 @@ async function handleRlm(orchestrator, rawArgs) {
     process.env.MCP_RUNNER_TASK_ID = taskId;
     applyRlmEnvOverrides(flags, goal);
     console.log(`Task: ${taskId}`);
+    const collabUserChoice = flags['collab'] !== undefined || process.env.RLM_SYMBOLIC_COLLAB !== undefined;
+    if (!collabUserChoice) {
+        const doctor = runDoctor();
+        if (doctor.collab.status === 'ok') {
+            console.log('Tip: collab is enabled. Try: codex-orchestrator rlm --collab auto \"<goal>\"');
+        }
+        else if (doctor.collab.status === 'disabled') {
+            console.log('Tip: collab is available but disabled. Enable with: codex features enable collab');
+        }
+    }
     let startResult = null;
     await withRunUi(flags, 'text', async (runEvents) => {
         startResult = await orchestrator.start({
@@ -525,15 +559,38 @@ async function handleInit(rawArgs) {
 async function handleDoctor(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    const result = runDoctor();
+    const includeUsage = Boolean(flags['usage']);
+    const windowDaysRaw = readStringFlag(flags, 'window-days');
+    let windowDays = undefined;
+    if (windowDaysRaw) {
+        if (!/^\d+$/u.test(windowDaysRaw)) {
+            throw new Error(`Invalid --window-days value '${windowDaysRaw}'. Expected a positive integer.`);
+        }
+        const parsed = Number(windowDaysRaw);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            throw new Error(`Invalid --window-days value '${windowDaysRaw}'. Expected a positive integer.`);
+        }
+        windowDays = parsed;
+    }
+    const taskFilter = readStringFlag(flags, 'task') ?? null;
+    const doctorResult = runDoctor();
+    const usageResult = includeUsage ? await runDoctorUsage({ windowDays, taskFilter }) : null;
     if (format === 'json') {
-        console.log(JSON.stringify(result, null, 2));
+        if (usageResult) {
+            console.log(JSON.stringify({ ...doctorResult, usage: usageResult }, null, 2));
+            return;
+        }
+        console.log(JSON.stringify(doctorResult, null, 2));
         return;
     }
-    const summary = formatDoctorSummary(result);
-    for (const line of summary) {
+    for (const line of formatDoctorSummary(doctorResult)) {
         console.log(line);
     }
+    if (usageResult) {
+        for (const line of formatDoctorUsageSummary(usageResult)) {
+            console.log(line);
+        }
+    }
 }
 async function handleDevtools(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -559,6 +616,30 @@ async function handleDevtools(rawArgs) {
         console.log(line);
     }
 }
+async function handleDelegation(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    const subcommand = positionals.shift();
+    if (!subcommand) {
+        throw new Error('delegation requires a subcommand (setup).');
+    }
+    if (subcommand !== 'setup') {
+        throw new Error(`Unknown delegation subcommand: ${subcommand}`);
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const apply = Boolean(flags['yes']);
+    if (format === 'json' && apply) {
+        throw new Error('delegation setup does not support --format json with --yes.');
+    }
+    const repoRoot = readStringFlag(flags, 'repo') ?? process.cwd();
+    const result = await runDelegationSetup({ apply, repoRoot });
+    if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    for (const line of formatDelegationSetupSummary(result)) {
+        console.log(line);
+    }
+}
 async function handleCodex(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const subcommand = positionals.shift();
@@ -879,6 +960,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.
@@ -888,6 +970,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.
@@ -940,7 +1023,11 @@ Commands:
     --codex-download-sha256 <sha>  Expected SHA256 for the prebuilt download.
     --codex-force          Overwrite existing CO-managed codex binary.
     --yes                  Apply codex CLI setup (otherwise plan only).
-  doctor [--format json]
+  doctor [--format json] [--usage] [--window-days <n>] [--task <id>]
+    --usage               Include a local usage snapshot (scans .runs/).
+    --window-days <n>     Window for --usage (default 30).
+    --task <id>           Limit --usage scan to a specific task directory.
+    --format json         Emit machine-readable output.
   codex setup
     --source <path>        Build from local Codex repo (or git URL).
     --ref <ref>            Git ref (branch/tag/sha) when building from repo.
@@ -952,6 +1039,10 @@ Commands:
   devtools setup          Print DevTools MCP setup instructions.
     --yes                 Apply setup by running "codex mcp add ...".
     --format json         Emit machine-readable output (dry-run only).
+  delegation setup        Configure delegation MCP server wiring.
+    --repo <path>         Repo root for delegation server (default cwd).
+    --yes                 Apply setup by running "codex mcp add ...".
+    --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).

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

@@ -0,0 +1,239 @@
+import { spawn, spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { resolveCodexCliBin } from './utils/codexCli.js';
+import { resolveCodexHome } from './utils/codexPaths.js';
+export async function runDelegationSetup(options = {}) {
+    const env = options.env ?? process.env;
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const codexBin = resolveCodexCliBin(env);
+    const codexHome = resolveCodexHome(env);
+    const configPath = join(codexHome, 'config.toml');
+    const plan = {
+        codexBin,
+        codexHome,
+        repoRoot,
+        commandLine: `"${codexBin}" mcp add delegation -- codex-orchestrator delegate-server`
+    };
+    const probe = inspectDelegationReadiness({ codexBin, configPath, repoRoot, env });
+    const readiness = { configured: probe.configured, configPath };
+    if (!options.apply) {
+        return { status: 'planned', plan, readiness };
+    }
+    if (probe.configured) {
+        return { status: 'skipped', reason: probe.reason ?? 'Delegation MCP is already configured.', plan, readiness };
+    }
+    await applyDelegationSetup({ codexBin, removeExisting: probe.removeExisting, envVars: probe.envVars }, env);
+    const configuredAfter = inspectDelegationReadiness({ codexBin, configPath, repoRoot, env }).configured;
+    return {
+        status: 'applied',
+        reason: probe.reason,
+        plan,
+        readiness: { ...readiness, configured: configuredAfter }
+    };
+}
+export function formatDelegationSetupSummary(result) {
+    const lines = [];
+    lines.push(`Delegation setup: ${result.status}`);
+    if (result.reason) {
+        lines.push(`Note: ${result.reason}`);
+    }
+    lines.push(`- Codex home: ${result.plan.codexHome}`);
+    lines.push(`- Config: ${result.readiness.configured ? 'ok' : 'missing'} (${result.readiness.configPath})`);
+    lines.push(`- Command: ${result.plan.commandLine}`);
+    if (result.status === 'planned') {
+        lines.push('Run with --yes to apply this setup.');
+    }
+    return lines;
+}
+function inspectDelegationReadiness(options) {
+    const requestedRepo = resolve(options.repoRoot);
+    const existing = readDelegationMcpServer(options.codexBin, options.env);
+    if (existing) {
+        const envVars = existing.envVars;
+        const isDelegationServer = existing.args.includes('delegate-server') || existing.args.includes('delegation-server');
+        if (!isDelegationServer) {
+            return {
+                configured: false,
+                removeExisting: true,
+                envVars,
+                reason: 'Existing delegation MCP entry does not point to codex-orchestrator delegate-server; reconfiguring.'
+            };
+        }
+        if (existing.pinnedRepo) {
+            const pinnedRepo = resolve(existing.pinnedRepo);
+            if (pinnedRepo !== requestedRepo) {
+                return {
+                    configured: false,
+                    removeExisting: true,
+                    envVars,
+                    reason: `Existing delegation MCP entry is pinned to ${existing.pinnedRepo}; reconfiguring.`
+                };
+            }
+            return {
+                configured: true,
+                removeExisting: false,
+                envVars,
+                reason: `Delegation MCP is already configured (pinned to ${existing.pinnedRepo}).`
+            };
+        }
+        return {
+            configured: true,
+            removeExisting: false,
+            envVars,
+            reason: 'Delegation MCP is already configured.'
+        };
+    }
+    // Fall back to directly scanning config.toml when the Codex CLI probe is unavailable.
+    const configured = isDelegationConfiguredFallback(options.configPath);
+    return { configured, removeExisting: false, envVars: {} };
+}
+function applyDelegationSetup(plan, env) {
+    const envFlags = [];
+    for (const [key, value] of Object.entries(plan.envVars ?? {})) {
+        envFlags.push('--env', `${key}=${value}`);
+    }
+    return new Promise((resolve, reject) => {
+        const runAdd = () => {
+            const child = spawn(plan.codexBin, ['mcp', 'add', 'delegation', ...envFlags, '--', 'codex-orchestrator', 'delegate-server'], { stdio: 'inherit', env });
+            child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+            child.once('exit', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`codex mcp add exited with code ${code ?? 'unknown'}`));
+                }
+            });
+        };
+        if (!plan.removeExisting) {
+            runAdd();
+            return;
+        }
+        const child = spawn(plan.codexBin, ['mcp', 'remove', 'delegation'], { stdio: 'inherit', env });
+        child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+        child.once('exit', (code) => {
+            if (code === 0) {
+                runAdd();
+            }
+            else {
+                reject(new Error(`codex mcp remove exited with code ${code ?? 'unknown'}`));
+            }
+        });
+    });
+}
+function readDelegationMcpServer(codexBin, env) {
+    const result = spawnSync(codexBin, ['mcp', 'get', 'delegation', '--json'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5000,
+        env
+    });
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    const stdout = String(result.stdout ?? '').trim();
+    if (!stdout) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        const transport = parsed.transport;
+        const args = Array.isArray(transport?.args)
+            ? transport.args.filter((value) => typeof value === 'string')
+            : [];
+        const envVars = {};
+        const envRecord = transport?.env;
+        if (envRecord && typeof envRecord === 'object' && !Array.isArray(envRecord)) {
+            for (const [key, value] of Object.entries(envRecord)) {
+                if (typeof value === 'string') {
+                    envVars[key] = value;
+                }
+            }
+        }
+        const pinnedRepo = readPinnedRepo(args);
+        return { args, pinnedRepo, envVars };
+    }
+    catch {
+        return null;
+    }
+}
+function readPinnedRepo(args) {
+    const index = args.indexOf('--repo');
+    if (index === -1) {
+        return null;
+    }
+    const candidate = args[index + 1];
+    return typeof candidate === 'string' && candidate.trim().length > 0 ? candidate.trim() : null;
+}
+function isDelegationConfiguredFallback(configPath) {
+    if (!existsSync(configPath)) {
+        return false;
+    }
+    try {
+        // Keep parsing loose; we only need to know whether a delegation entry exists.
+        const raw = readFileSync(configPath, 'utf8');
+        return hasMcpServerEntry(raw, 'delegation');
+    }
+    catch {
+        return false;
+    }
+}
+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/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,57 @@ 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-orchestrator delegation setup --yes',
+                'Or manually: codex mcp add delegation -- codex-orchestrator delegate-server',
+                "Enable for a run with: codex -c 'mcp_servers.delegation.enabled=true' ...",
+                'See: codex-orchestrator init codex'
+            ]
+        }
     };
 }
 export function formatDoctorSummary(result) {
@@ -118,5 +169,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/doctorUsage.js

@@ -0,0 +1,210 @@
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import process from 'node:process';
+import { collectManifests, findSubagentManifests, parseRunIdTimestamp, resolveEnvironmentPaths } from '../../../scripts/lib/run-manifests.js';
+import { normalizeTaskKey as normalizeTaskKeyAny } from '../../../scripts/lib/docs-helpers.js';
+const normalizeTaskKey = normalizeTaskKeyAny;
+export async function runDoctorUsage(options = {}) {
+    const windowDays = clampInt(options.windowDays ?? 30, 1, 3650);
+    const cutoffMs = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const env = resolveEnvironmentPaths();
+    const manifestPaths = await collectManifests(env.runsRoot, options.taskFilter ?? undefined);
+    const seenRunIds = new Set();
+    const pipelines = new Map();
+    const cloudByStatus = {};
+    const statusCounts = { total: 0, succeeded: 0, failed: 0, cancelled: 0, other: 0 };
+    let cloudRuns = 0;
+    let rlmRuns = 0;
+    let collabRunsWithToolCalls = 0;
+    let collabTotalToolCalls = 0;
+    const collabCaptureDisabled = String(process.env.CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS ?? '').trim() === '0';
+    const activeIndexTasks = new Set();
+    const taskKeys = readTaskIndexKeys(env.repoRoot);
+    for (const manifestPath of manifestPaths) {
+        const runIdFromPath = extractRunIdFromManifestPath(manifestPath);
+        if (!runIdFromPath) {
+            continue;
+        }
+        if (seenRunIds.has(runIdFromPath)) {
+            continue;
+        }
+        const timestamp = parseRunIdTimestamp(runIdFromPath);
+        if (timestamp && timestamp.getTime() < cutoffMs) {
+            continue;
+        }
+        let manifest;
+        try {
+            const raw = await readFile(manifestPath, 'utf8');
+            manifest = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const runId = typeof manifest.run_id === 'string' && manifest.run_id ? manifest.run_id : runIdFromPath;
+        if (seenRunIds.has(runId)) {
+            continue;
+        }
+        seenRunIds.add(runId);
+        const startedAtMs = Date.parse(manifest.started_at ?? '') || timestamp?.getTime() || 0;
+        if (!startedAtMs || startedAtMs < cutoffMs) {
+            continue;
+        }
+        statusCounts.total += 1;
+        if (manifest.status === 'succeeded') {
+            statusCounts.succeeded += 1;
+        }
+        else if (manifest.status === 'failed') {
+            statusCounts.failed += 1;
+        }
+        else if (manifest.status === 'cancelled') {
+            statusCounts.cancelled += 1;
+        }
+        else {
+            statusCounts.other += 1;
+        }
+        const pipelineId = typeof manifest.pipeline_id === 'string' && manifest.pipeline_id ? manifest.pipeline_id : 'unknown';
+        pipelines.set(pipelineId, (pipelines.get(pipelineId) ?? 0) + 1);
+        if (pipelineId === 'rlm') {
+            rlmRuns += 1;
+        }
+        if (manifest.cloud_execution) {
+            cloudRuns += 1;
+            const status = (manifest.cloud_execution.status ?? 'unknown').trim() || 'unknown';
+            cloudByStatus[status] = (cloudByStatus[status] ?? 0) + 1;
+        }
+        if (Array.isArray(manifest.collab_tool_calls) && manifest.collab_tool_calls.length > 0) {
+            collabRunsWithToolCalls += 1;
+            collabTotalToolCalls += manifest.collab_tool_calls.length;
+        }
+        if (taskKeys.has(manifest.task_id)) {
+            activeIndexTasks.add(manifest.task_id);
+        }
+    }
+    const pipelineTop = [...pipelines.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([id, runs]) => ({ id, runs }));
+    const delegationErrors = [];
+    let activeWithSubagents = 0;
+    let totalSubagentManifests = 0;
+    const activeTasks = [...activeIndexTasks];
+    const subagentResults = await Promise.all(activeTasks.map(async (taskId) => {
+        const result = await findSubagentManifests(env.runsRoot, taskId);
+        if (result.error) {
+            delegationErrors.push(result.error);
+        }
+        return { taskId, found: result.found };
+    }));
+    for (const item of subagentResults) {
+        totalSubagentManifests += item.found.length;
+        if (item.found.length > 0) {
+            activeWithSubagents += 1;
+        }
+    }
+    return {
+        window_days: windowDays,
+        cutoff_iso: cutoffIso,
+        runs: statusCounts,
+        cloud: {
+            runs: cloudRuns,
+            by_status: cloudByStatus
+        },
+        rlm: {
+            runs: rlmRuns
+        },
+        collab: {
+            runs_with_tool_calls: collabRunsWithToolCalls,
+            total_tool_calls: collabTotalToolCalls,
+            capture_disabled: collabCaptureDisabled
+        },
+        delegation: {
+            active_top_level_tasks: activeTasks.length,
+            active_with_subagents: activeWithSubagents,
+            total_subagent_manifests: totalSubagentManifests,
+            errors: delegationErrors
+        },
+        pipelines: {
+            total: pipelines.size,
+            top: pipelineTop
+        }
+    };
+}
+export function formatDoctorUsageSummary(result) {
+    const lines = [];
+    lines.push(`Usage (last ${result.window_days}d, cutoff ${result.cutoff_iso})`);
+    lines.push(`  - runs: ${result.runs.total} (ok=${result.runs.succeeded}, failed=${result.runs.failed}, cancelled=${result.runs.cancelled}, other=${result.runs.other})`);
+    lines.push(`  - cloud: ${result.cloud.runs} (${formatPercent(result.cloud.runs, result.runs.total)})${formatCloudStatuses(result.cloud.by_status)}`);
+    lines.push(`  - rlm: ${result.rlm.runs} (${formatPercent(result.rlm.runs, result.runs.total)})`);
+    const collabSuffix = result.collab.capture_disabled ? ' (capture disabled)' : '';
+    lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`);
+    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`);
+    }
+    else {
+        lines.push('  - delegation: no top-level tasks detected in tasks/index.json for this window');
+    }
+    if (result.pipelines.top.length > 0) {
+        lines.push('Top pipelines:');
+        for (const entry of result.pipelines.top) {
+            lines.push(`  - ${entry.id}: ${entry.runs}`);
+        }
+    }
+    if (result.delegation.errors.length > 0) {
+        lines.push('Delegation scan warnings:');
+        for (const warning of result.delegation.errors.slice(0, 3)) {
+            lines.push(`  - ${warning}`);
+        }
+    }
+    return lines;
+}
+function extractRunIdFromManifestPath(manifestPath) {
+    if (!manifestPath) {
+        return null;
+    }
+    // .../<run-id>/manifest.json
+    const dir = manifestPath.endsWith('manifest.json') ? basename(dirname(manifestPath)) : null;
+    return dir && dir !== '..' ? dir : null;
+}
+function clampInt(value, min, max) {
+    const rounded = Math.floor(value);
+    if (!Number.isFinite(rounded)) {
+        return min;
+    }
+    return Math.max(min, Math.min(max, rounded));
+}
+function formatPercent(numerator, denominator) {
+    if (!denominator) {
+        return '0%';
+    }
+    const pct = (numerator / denominator) * 100;
+    return `${Math.round(pct * 10) / 10}%`;
+}
+function formatCloudStatuses(byStatus) {
+    const entries = Object.entries(byStatus);
+    if (entries.length === 0) {
+        return '';
+    }
+    entries.sort((a, b) => b[1] - a[1]);
+    const top = entries
+        .slice(0, 3)
+        .map(([status, count]) => `${status}=${count}`)
+        .join(', ');
+    return ` [${top}]`;
+}
+function readTaskIndexKeys(repoRoot) {
+    const indexPath = join(repoRoot, 'tasks', 'index.json');
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const items = Array.isArray(parsed?.items) ? parsed.items : [];
+        const keys = items
+            .map((item) => normalizeTaskKey(item))
+            .filter((key) => typeof key === 'string' && key.length > 0);
+        return new Set(keys);
+    }
+    catch {
+        return new Set();
+    }
+}

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

@@ -61,7 +61,7 @@ export function formatInitSummary(result, cwd) {
         lines.push('No files written.');
     }
     lines.push('Next steps (recommended):');
-    lines.push(`  - codex mcp add delegation -- codex-orchestrator delegate-server --repo ${cwd}`);
+    lines.push('  - codex-orchestrator delegation setup --yes');
     lines.push('  - codex-orchestrator codex setup  # optional: managed/pinned Codex CLI (stock CLI works by default)');
     return lines;
 }

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/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,8 +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] [--usage]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`).
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
+- `codex-orchestrator delegation setup [--yes]`: configure delegation MCP wiring (`--yes` applies `codex mcp add ...`).
 - `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.21",
+  "version": "0.1.23",
   "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.

package/skills/delegation-usage/DELEGATION_GUIDE.md

@@ -63,7 +63,7 @@ Fix by re-registering the server with a TOML-quoted override:
 codex mcp remove delegation
 codex mcp add delegation \
   --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' \
-  -- codex-orchestrator delegate-server --repo /path/to/repo
+  -- codex-orchestrator delegate-server
 ```
 
 ## Server mode vs child mode (don’t mix them up)
@@ -98,7 +98,7 @@ If you want deeper recursion or longer wall-clock time for delegated runs, set R
 ```bash
 codex mcp add delegation \
   --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' \
-  -- codex-orchestrator delegate-server --repo /path/to/repo
+  -- codex-orchestrator delegate-server
 ```
 
 For the `rlm` pipeline specifically, use:

package/skills/delegation-usage/SKILL.md

@@ -35,16 +35,16 @@ codex exec \
 ```
 
 Optional (only if you need it):
-- Add `--repo /path/to/repo` to the MCP args when registering the server or when you need repo-scoped config.
+- Add `--repo /path/to/repo` only when you want to pin the server to a repo even if Codex is launched outside that repo (default uses cwd).
 - Add `-c 'features.skills=false'` for a minimal, deterministic background run.
 - Add `-c 'delegate.mode=question_only'` when the child only needs `delegate.question.*` (and optional `delegate.status`).
 - Add `-c 'delegate.mode=full'` when the child needs `delegate.spawn/pause/cancel` (nested delegation / run control).
 - If the task needs external docs or APIs, enable only the relevant MCP server for that environment.
 - If `delegate.spawn` is missing, re-register the MCP server with full mode (server config controls tool surface):
   - `codex mcp remove delegation`
-  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' -- codex-orchestrator delegate-server --repo /path/to/repo`
+  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' -- codex-orchestrator delegate-server`
 - To raise RLM budgets for delegated runs, re-register with an override (TOML-quoted):
-  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' -- codex-orchestrator delegate-server --repo /path/to/repo`
+  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' -- codex-orchestrator delegate-server`
 
 For deeper background patterns and troubleshooting, see `DELEGATION_GUIDE.md`.
 For runner + delegation coordination (short `--task` flow), see `docs/delegation-runner-workflow.md`.
@@ -64,8 +64,10 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
 ### 0) One-time setup (register the MCP server)
 
 - Register the delegation server once:
+  - Preferred: `codex-orchestrator delegation setup --yes`
+    - This wraps `codex mcp add delegation ...` and keeps wiring discoverable via `codex-orchestrator doctor`.
   - `codex mcp add delegation -- codex-orchestrator delegate-server`
-  - Optional (recommended for repo-scoped config): append `--repo /path/to/repo` to the args.
+  - Optional: append `--repo /path/to/repo` to pin the server to one repo (not recommended if you work across repos).
   - `delegate-server` is the canonical name; `delegation-server` is supported as an alias.
 - Per-run `-c 'mcp_servers.delegation.enabled=true'` only works **after** registration.
 - If `delegate.*` tools are missing mid-task, start a new run with: