@kbediako/codex-orchestrator 0.1.38 → 0.2.0

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

@@ -2,18 +2,23 @@ import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { release as osRelease } from 'node:os';
 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 { buildCloudPreflightAuthProvenance, buildCloudPreflightRequest, runCloudPreflight } from './utils/cloudPreflight.js';
+import { classifyDelegationTransport, formatDelegateServerProcessSummary, inspectDelegateServerProcesses, inspectDelegationMcpConfig, probeDelegationInitialize, resolveDelegationServerInvocation } from './utils/delegationMcpHealth.js';
+import { sanitizeProviderOverrideEnv } from './utils/providerOverrideEnv.js';
+import { hasLinearApiCredentials, hasLinearSourceBinding, resolveLinearSourceSetup } from './control/linearDispatchSource.js';
+import { normalizeDispatchSourceProvider } from './control/trackerDispatchPilot.js';
+import { BASELINE_AGENTS, BASELINE_MODEL, BASELINE_REVIEW_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');
+let tomlParser;
 const OPTIONAL_DEPENDENCIES = [
     {
         name: 'playwright',
@@ -23,6 +28,7 @@ const OPTIONAL_DEPENDENCIES = [
     { name: 'pixelmatch', install: 'npm install --save-dev pixelmatch' },
     { name: 'cheerio', install: 'npm install --save-dev cheerio' }
 ];
+const PROVIDER_ROOT_RELATIVE_PATH = '.codex/providers';
 export function runDoctor(cwd = process.cwd()) {
     const dependencies = OPTIONAL_DEPENDENCIES.map((entry) => {
         const resolved = resolveOptionalDependency(entry.name, cwd);
@@ -104,10 +110,30 @@ export function runDoctor(cwd = process.cwd()) {
         : null;
     const cloudStatus = !cloudCmdAvailable ? 'unavailable' : cloudEnvIdConfigured ? 'ok' : 'not_configured';
     const cloudFallbackPolicy = resolveCloudFallbackPolicy();
-    const delegationConfig = inspectDelegationConfig();
-    const delegationStatus = delegationConfig.status === 'ok' ? 'ok' : 'missing-config';
+    const repoRoot = resolveDoctorRepoRoot(cwd);
+    const delegationSnapshot = inspectDelegationMcpConfig(process.env);
+    const delegationTransport = classifyDelegationTransport(delegationSnapshot.entry);
+    const delegationStartup = probeDelegationInitialize(delegationSnapshot.entry, { env: process.env });
+    const delegationProcesses = inspectDelegateServerProcesses({ repoRoot });
+    const delegationStatus = delegationSnapshot.status !== 'ok'
+        ? 'missing-config'
+        : delegationTransport.status !== 'safe'
+            || delegationStartup.status === 'slow'
+            || delegationStartup.status === 'failed'
+            || delegationProcesses.status === 'stale'
+            ? 'warning'
+            : delegationProcesses.status === 'unavailable'
+                ? 'unavailable'
+                : 'ok';
+    const delegationBlocksOverallStatus = delegationStatus === 'missing-config';
+    const providers = inspectProviderReadiness(repoRoot, process.env);
     return {
-        status: missing.length === 0 && codexDefaults.status === 'ok' ? 'ok' : 'warning',
+        status: missing.length === 0 &&
+            codexDefaults.status === 'ok' &&
+            providers.status === 'ok' &&
+            !delegationBlocksOverallStatus
+            ? 'ok'
+            : 'warning',
         missing,
         dependencies,
         devtools,
@@ -141,24 +167,71 @@ export function runDoctor(cwd = process.cwd()) {
         },
         delegation: {
             status: delegationStatus,
-            config: delegationConfig,
-            enablement: [
-                'Quick fix: codex-orchestrator doctor --apply --yes',
-                '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'
-            ]
-        }
+            config: {
+                status: delegationSnapshot.status,
+                path: delegationSnapshot.path,
+                detail: delegationSnapshot.detail,
+                source: delegationSnapshot.entry?.source,
+                pinned_repo: delegationSnapshot.entry?.pinnedRepo ?? null
+            },
+            transport: {
+                status: delegationTransport.status,
+                kind: delegationTransport.kind,
+                command_line: delegationTransport.commandLine,
+                detail: delegationTransport.detail
+            },
+            startup: {
+                status: delegationStartup.status,
+                latency_ms: delegationStartup.latencyMs,
+                threshold_ms: delegationStartup.thresholdMs,
+                detail: delegationStartup.detail
+            },
+            processes: {
+                status: delegationProcesses.status,
+                active_count: delegationProcesses.activeCount,
+                active_pids: delegationProcesses.activePids,
+                stale_count: delegationProcesses.staleCount,
+                stale_pids: delegationProcesses.stalePids,
+                stale_rss_mb: Number((delegationProcesses.staleRssKb / 1024).toFixed(1)),
+                threshold_minutes: delegationProcesses.thresholdSeconds / 60,
+                detail: delegationProcesses.detail,
+                details: delegationProcesses.details.map((detail) => ({
+                    pid: detail.pid,
+                    ppid: detail.ppid,
+                    elapsed_seconds: detail.elapsedSeconds,
+                    rss_mb: Number((detail.rssKb / 1024).toFixed(1)),
+                    cwd: detail.cwd,
+                    parent_pid: detail.parentPid,
+                    parent_cwd: detail.parentCwd,
+                    root_codex_parent_pid: detail.rootCodexParentPid,
+                    root_codex_parent_cwd: detail.rootCodexParentCwd,
+                    classification: detail.classification,
+                    classification_detail: detail.classificationDetail,
+                    manifest_path: detail.manifestAssociation?.manifestPath ?? null,
+                    issue_identifier: detail.manifestAssociation?.issueIdentifier ?? null,
+                    pipeline_id: detail.manifestAssociation?.pipelineId ?? null,
+                    task_id: detail.manifestAssociation?.taskId ?? null,
+                    run_id: detail.manifestAssociation?.runId ?? null,
+                    status: detail.manifestAssociation?.status ?? null
+                }))
+            },
+            enablement: buildDelegationEnablementGuidance({
+                configStatus: delegationSnapshot.status,
+                transportStatus: delegationTransport.status,
+                directTransportGuidance: buildDelegationDirectTransportGuidance()
+            })
+        },
+        providers
     };
 }
 export async function runDoctorCloudPreflight(options = {}) {
-    const env = options.env ?? process.env;
-    const cwd = options.cwd ?? process.cwd();
-    const configuredRoot = normalizeOptionalString(env.CODEX_ORCHESTRATOR_ROOT);
+    const env = sanitizeProviderOverrideEnv(options.env ?? process.env);
+    const explicitCwd = normalizeOptionalString(options.cwd);
+    const cwd = explicitCwd ? resolve(explicitCwd) : process.cwd();
+    // An explicit cwd is the caller's repo hint; only fall back to the ambient root override when cwd is implicit.
+    const configuredRoot = explicitCwd ? null : normalizeOptionalString(env.CODEX_ORCHESTRATOR_ROOT);
     const rootHint = configuredRoot ? resolve(cwd, configuredRoot) : cwd;
     const repoRoot = resolveDoctorRepoRoot(rootHint);
-    const codexBin = resolveCodexCliBin(env);
     const taskId = normalizeOptionalString(options.taskId)
         ?? normalizeOptionalString(env.MCP_RUNNER_TASK_ID)
         ?? normalizeOptionalString(env.TASK)
@@ -185,41 +258,113 @@ export async function runDoctorCloudPreflight(options = {}) {
         ?? planMetadataEnvironmentId
         ?? normalizeOptionalString(env.CODEX_CLOUD_ENV_ID)
         ?? resolveTaskMetadataCloudEnvironmentId(repoRoot, taskId);
-    const branch = normalizeOptionalBranch(options.branch) ?? normalizeOptionalBranch(env.CODEX_CLOUD_BRANCH);
-    const preflight = await runCloudPreflight({
+    const preflight = await runCloudPreflight(buildCloudPreflightRequest({
         repoRoot,
-        codexBin,
         environmentId,
-        branch,
+        branch: options.branch,
         env
-    });
+    }));
+    const authProvenance = preflight.details.authProvenance ??
+        buildCloudPreflightAuthProvenance({
+            env,
+            environmentId: preflight.details.environmentId,
+            branch: preflight.details.branch
+        });
     const issues = planMetadataIssue ? [planMetadataIssue, ...preflight.issues] : preflight.issues;
+    const securityAdvisories = inspectCodexSandboxSecurityAdvisories({ env });
     const guidance = buildCloudPreflightGuidance(issues);
     return {
         ok: preflight.ok && planMetadataIssue === null,
         details: {
             codex_bin: preflight.details.codexBin,
             environment_id: preflight.details.environmentId,
-            branch: preflight.details.branch
+            branch: preflight.details.branch,
+            auth_provenance: {
+                provider_kind: authProvenance.providerKind,
+                active_profile_fingerprint: authProvenance.activeProfileFingerprint,
+                active_account_fingerprint: authProvenance.activeAccountFingerprint,
+                cloud_env_id: authProvenance.cloudEnvId,
+                cloud_branch: authProvenance.cloudBranch,
+                credential_source: authProvenance.credentialSource,
+                auth_freshness: authProvenance.authFreshness
+            }
         },
         issues,
+        security_advisories: securityAdvisories,
         guidance
     };
 }
+export function inspectCodexSandboxSecurityAdvisories(options = {}) {
+    const env = options.env ?? process.env;
+    const advisories = [];
+    const configPath = join(resolveCodexHome(env), 'config.toml');
+    if (existsSync(configPath)) {
+        try {
+            const raw = readFileSync(configPath, 'utf8');
+            const parsed = getTomlParser().parse(raw);
+            if (isRecord(parsed)) {
+                const sandboxMode = normalizeOptionalString(readStringValue(parsed.sandbox_mode));
+                if (sandboxMode === 'danger-full-access') {
+                    advisories.push({
+                        code: 'codex_config_danger_full_access',
+                        scope: 'local-only',
+                        severity: 'warning',
+                        message: 'Codex config sets top-level sandbox_mode to danger-full-access.',
+                        guidance: 'Treat this as a local-only advisory; do not use it to satisfy cloud readiness or weaken CO sandbox defaults.',
+                        details: {
+                            path: configPath,
+                            sandbox_mode: sandboxMode
+                        }
+                    });
+                }
+            }
+        }
+        catch {
+            // Existing Codex defaults checks already report invalid TOML; keep this advisory focused on security posture.
+        }
+    }
+    const platform = options.platform ?? process.platform;
+    const releaseText = normalizeOptionalString(options.osRelease ?? osRelease());
+    if (isWsl1Release(platform, releaseText)) {
+        advisories.push({
+            code: 'wsl1_bubblewrap_unsupported',
+            scope: 'local-only',
+            severity: 'warning',
+            message: 'WSL1 detected; Codex bubblewrap sandbox behavior is unsupported for this local platform.',
+            guidance: 'Run local Codex sandbox checks on WSL2/Linux/macOS, or keep this as a local-only limitation; it is not cloud canary evidence.',
+            details: {
+                platform,
+                os_release: releaseText ?? undefined
+            }
+        });
+    }
+    return advisories;
+}
+function isWsl1Release(platform, releaseText) {
+    if (platform !== 'linux' || !releaseText) {
+        return false;
+    }
+    const normalized = releaseText.toLowerCase();
+    return normalized.includes('microsoft') && !normalized.includes('microsoft-standard') && !normalized.includes('wsl2');
+}
 function resolveDoctorRepoRoot(cwd) {
     const fallback = resolve(cwd);
     let current = fallback;
+    let providerRootCandidate = null;
     while (current) {
         if (existsSync(join(current, 'tasks', 'index.json'))) {
             return current;
         }
+        if (!providerRootCandidate && existsSync(join(current, PROVIDER_ROOT_RELATIVE_PATH))) {
+            providerRootCandidate = current;
+        }
         const parent = dirname(current);
         if (parent === current) {
             break;
         }
         current = parent;
     }
-    return fallback;
+    return providerRootCandidate ?? fallback;
 }
 export function formatDoctorCloudPreflightSummary(result) {
     const lines = [];
@@ -227,6 +372,11 @@ export function formatDoctorCloudPreflightSummary(result) {
     lines.push(`  - codex bin: ${result.details.codex_bin}`);
     lines.push(`  - environment id: ${result.details.environment_id ?? '<unset>'}`);
     lines.push(`  - branch: ${result.details.branch ?? '<unset>'}`);
+    lines.push(`  - auth provider: ${result.details.auth_provenance.provider_kind}`);
+    lines.push(`  - credential source: ${result.details.auth_provenance.credential_source ?? '<none detected>'}`);
+    lines.push(`  - profile fingerprint: ${result.details.auth_provenance.active_profile_fingerprint ?? '<unset>'}`);
+    lines.push(`  - account fingerprint: ${result.details.auth_provenance.active_account_fingerprint ?? '<unset>'}`);
+    lines.push(`  - auth freshness: ${result.details.auth_provenance.auth_freshness}`);
     if (result.issues.length > 0) {
         lines.push('  - issues:');
         for (const issue of result.issues) {
@@ -239,6 +389,19 @@ export function formatDoctorCloudPreflightSummary(result) {
             lines.push(`    - ${item}`);
         }
     }
+    if (result.security_advisories.length > 0) {
+        lines.push('  - sandbox/security advisories:');
+        for (const advisory of result.security_advisories) {
+            lines.push(`    - [${advisory.code}/${advisory.scope}] ${advisory.message}`);
+            lines.push(`      guidance: ${advisory.guidance}`);
+            if (advisory.details?.path) {
+                lines.push(`      path: ${advisory.details.path}`);
+            }
+            if (advisory.details?.platform || advisory.details?.os_release) {
+                lines.push(`      platform: ${advisory.details.platform ?? '<unknown>'}, os_release: ${advisory.details.os_release ?? '<unknown>'}`);
+            }
+        }
+    }
     return lines;
 }
 export function formatDoctorSummary(result) {
@@ -308,10 +471,13 @@ export function formatDoctorSummary(result) {
         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(`  - review_model: ${result.codex_defaults.checks.review_model.status} (actual: ${result.codex_defaults.checks.review_model.actual ?? '<unset>'}, expected: ${result.codex_defaults.checks.review_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})`);
+    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} when set; <unset> accepted)`);
+    if (result.codex_defaults.legacy_max_spawn_depth?.present) {
+        lines.push(`  - legacy agents.max_spawn_depth: ${result.codex_defaults.legacy_max_spawn_depth.status} (actual: ${result.codex_defaults.legacy_max_spawn_depth.actual ?? '<unset>'}; ${result.codex_defaults.legacy_max_spawn_depth.detail})`);
+    }
     for (const line of result.codex_defaults.guidance) {
         lines.push(`  - ${line}`);
     }
@@ -340,23 +506,176 @@ export function formatDoctorSummary(result) {
     if (result.delegation.config.detail) {
         lines.push(`    detail: ${result.delegation.config.detail}`);
     }
+    if (result.delegation.config.source) {
+        lines.push(`  - source: ${result.delegation.config.source}`);
+    }
+    lines.push(`  - transport: ${result.delegation.transport.status} (${result.delegation.transport.kind})`);
+    if (result.delegation.transport.command_line) {
+        lines.push(`    command: ${result.delegation.transport.command_line}`);
+    }
+    lines.push(`    detail: ${result.delegation.transport.detail}`);
+    lines.push(`  - initialize: ${result.delegation.startup.status} (latency: ${result.delegation.startup.latency_ms ?? '<skipped>'} ms, threshold: ${result.delegation.startup.threshold_ms} ms)`);
+    lines.push(`    detail: ${result.delegation.startup.detail}`);
+    lines.push(`  - processes: ${result.delegation.processes.status} (active: ${result.delegation.processes.active_count}, stale: ${result.delegation.processes.stale_count}, stale rss: ${result.delegation.processes.stale_rss_mb.toFixed(1)} MB)`);
+    lines.push(`    detail: ${result.delegation.processes.detail}`);
+    if (result.delegation.processes.stale_pids.length > 0) {
+        lines.push(`    stale pids: ${result.delegation.processes.stale_pids.join(', ')}`);
+        for (const detail of result.delegation.processes.details
+            .filter((entry) => entry.classification === 'stale-parent-session' || entry.classification === 'stale-orphan')
+            .slice(0, 3)) {
+            lines.push(`    stale detail: ${formatDelegateServerProcessSummary({
+                pid: detail.pid,
+                classification: detail.classification,
+                cwd: detail.cwd,
+                parentPid: detail.parent_pid,
+                parentCwd: detail.parent_cwd,
+                rootCodexParentPid: detail.root_codex_parent_pid,
+                rootCodexParentCwd: detail.root_codex_parent_cwd,
+                manifestPath: detail.manifest_path
+            })}`);
+        }
+    }
     for (const line of result.delegation.enablement) {
         lines.push(`  - ${line}`);
     }
+    lines.push(`Providers: ${result.providers.status}`);
+    lines.push(`  - repo examples: ${result.providers.repo_examples.status} (${result.providers.repo_examples.root})`);
+    if (result.providers.repo_examples.missing.length > 0) {
+        lines.push(`    missing: ${result.providers.repo_examples.missing.join(', ')}`);
+    }
+    lines.push(`  - control policy: ${result.providers.control_policy.status} (${result.providers.control_policy.path})`);
+    if (result.providers.control_policy.detail) {
+        lines.push(`    detail: ${result.providers.control_policy.detail}`);
+    }
+    lines.push(`  - Linear: ${result.providers.linear.status}`);
+    lines.push(`    credentials: ${result.providers.linear.credentials_present ? 'present' : 'missing'}`);
+    lines.push(`    binding: ${result.providers.linear.binding_present ? 'present' : 'missing'}`);
+    lines.push(`    webhook secret: ${result.providers.linear.webhook_secret_present ? 'present' : 'missing'}`);
+    lines.push(`    dispatch_pilot: ${renderProviderToggleSummary(result.providers.linear.dispatch_pilot_enabled, result.providers.linear.dispatch_pilot_provider)}`);
+    lines.push(`  - Telegram: ${result.providers.telegram.status}`);
+    lines.push(`    polling: ${result.providers.telegram.polling_enabled ? 'enabled' : 'disabled'}`);
+    lines.push(`    bot token: ${result.providers.telegram.bot_token_present ? 'present' : 'missing'}`);
+    lines.push(`    allowlisted chats: ${result.providers.telegram.allowed_chat_ids}`);
+    lines.push(`    mutations: ${result.providers.telegram.mutations_enabled ? 'enabled' : 'disabled'}`);
+    lines.push(`    push: ${result.providers.telegram.push_enabled ? 'enabled' : 'disabled'}`);
+    lines.push(`    transport policy: ${renderTransportPolicySummary(result.providers.telegram.telegram_transport_allowed)}`);
+    for (const line of result.providers.guidance) {
+        lines.push(`  - ${line}`);
+    }
     return lines;
 }
+export function buildDelegationDirectTransportGuidance(resolver = () => resolveDelegationServerInvocation({ env: process.env, execPath: process.execPath })) {
+    try {
+        return `Direct dist transport: ${resolver().commandLine} --repo <path>`;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return `Direct dist transport unavailable until dist is built: ${detail}`;
+    }
+}
+export function buildDelegationEnablementGuidance(options) {
+    const lines = [];
+    const setupApplyWouldHelp = options.configStatus !== 'ok' || options.transportStatus !== 'safe';
+    if (setupApplyWouldHelp) {
+        lines.push('Quick fix: codex-orchestrator doctor --apply --yes');
+    }
+    lines.push('Run: codex-orchestrator delegation setup --yes');
+    lines.push('Run: codex-orchestrator delegation cleanup-stale --yes');
+    lines.push(options.directTransportGuidance ?? buildDelegationDirectTransportGuidance());
+    lines.push("Enable for a run with: codex -c 'mcp_servers.delegation.enabled=true' ...");
+    lines.push('See: codex-orchestrator init codex');
+    return lines;
+}
+function inspectProviderReadiness(repoRoot, env = process.env) {
+    const providerRoot = join(repoRoot, PROVIDER_ROOT_RELATIVE_PATH);
+    const repoExamples = {
+        readme: join(providerRoot, 'README.md'),
+        env_example: join(providerRoot, 'provider.env.example'),
+        control_example: join(providerRoot, 'control.example.json')
+    };
+    const missingRepoExamples = Object.entries(repoExamples)
+        .filter(([, filePath]) => !existsSync(filePath))
+        .map(([key]) => key);
+    const controlPolicy = readProviderControlPolicy(providerRoot);
+    const linearSourceSetup = resolveLinearSourceSetup({
+        provider: 'linear',
+        workspace_id: controlPolicy.dispatch_pilot_source_setup?.workspace_id ?? null,
+        team_id: controlPolicy.dispatch_pilot_source_setup?.team_id ?? null,
+        project_id: controlPolicy.dispatch_pilot_source_setup?.project_id ?? null
+    }, env);
+    const linearCredentialsPresent = hasLinearApiCredentials(env);
+    const linearBindingPresent = hasLinearSourceBinding(linearSourceSetup);
+    const linearWebhookSecretPresent = Boolean(normalizeOptionalString(env.CO_LINEAR_WEBHOOK_SECRET));
+    const linearRequired = controlPolicy.dispatch_pilot_enabled === true && controlPolicy.dispatch_pilot_provider === 'linear';
+    const linearReady = linearCredentialsPresent &&
+        linearBindingPresent &&
+        linearWebhookSecretPresent &&
+        linearRequired;
+    const telegramPollingEnabled = parseEnvBoolean(env.CO_TELEGRAM_POLLING_ENABLED);
+    const telegramBotTokenPresent = Boolean(normalizeOptionalString(env.CO_TELEGRAM_BOT_TOKEN));
+    const telegramAllowedChatIds = parseCsvList(env.CO_TELEGRAM_ALLOWED_CHAT_IDS).length;
+    const telegramMutationsEnabled = parseEnvBoolean(env.CO_TELEGRAM_ENABLE_MUTATIONS);
+    const telegramPushEnabled = parseEnvBoolean(env.CO_TELEGRAM_PUSH_ENABLED);
+    const telegramRequired = controlPolicy.telegram_transport_allowed === true;
+    const telegramReady = telegramPollingEnabled &&
+        telegramBotTokenPresent &&
+        telegramAllowedChatIds > 0 &&
+        telegramMutationsEnabled &&
+        telegramRequired;
+    const repoExamplesStatus = missingRepoExamples.length === 0 ? 'ok' : 'missing';
+    return {
+        status: repoExamplesStatus === 'ok' &&
+            controlPolicy.status === 'ok' &&
+            (!linearRequired || linearReady) &&
+            (!telegramRequired || telegramReady)
+            ? 'ok'
+            : 'advisory',
+        repo_examples: {
+            status: repoExamplesStatus,
+            root: providerRoot,
+            paths: repoExamples,
+            missing: missingRepoExamples
+        },
+        control_policy: controlPolicy,
+        linear: {
+            status: linearReady ? 'ready' : 'incomplete',
+            credentials_present: linearCredentialsPresent,
+            binding_present: linearBindingPresent,
+            webhook_secret_present: linearWebhookSecretPresent,
+            dispatch_pilot_enabled: controlPolicy.dispatch_pilot_enabled,
+            dispatch_pilot_provider: controlPolicy.dispatch_pilot_provider
+        },
+        telegram: {
+            status: telegramReady ? 'ready' : 'incomplete',
+            polling_enabled: telegramPollingEnabled,
+            bot_token_present: telegramBotTokenPresent,
+            allowed_chat_ids: telegramAllowedChatIds,
+            mutations_enabled: telegramMutationsEnabled,
+            push_enabled: telegramPushEnabled,
+            telegram_transport_allowed: controlPolicy.telegram_transport_allowed
+        },
+        guidance: [
+            'Seed the current repo with: codex-orchestrator init codex --cwd <repo>',
+            'Review .codex/providers/provider.env.example and .codex/providers/control.example.json before enabling providers.',
+            'Re-run codex-orchestrator doctor --format json after exporting provider env vars to confirm readiness.'
+        ]
+    };
+}
 function inspectCodexDefaultsAdvisory(env = process.env) {
     const configPath = join(resolveCodexHome(env), 'config.toml');
     const checks = {
         model: { status: 'advisory', expected: BASELINE_MODEL, actual: null },
+        review_model: { status: 'advisory', expected: BASELINE_REVIEW_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 }
+        max_depth: { status: 'advisory', expected_minimum: BASELINE_AGENTS.max_depth, actual: null }
     };
+    let legacyMaxSpawnDepth = 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.'
+        'Additive policy: unrelated config keys are preserved; existing role files stay untouched unless `--force` is set.',
+        'Current CO baseline no longer seeds or expects `agents.max_spawn_depth`; keep it only as a legacy local override when an older parser/runtime still honors it.',
+        'Leaving `agents.max_depth` unset remains accepted when local parser/runtime constraints require it.'
     ];
     if (!existsSync(configPath)) {
         return {
@@ -369,7 +688,7 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
     let parsed;
     try {
         const raw = readFileSync(configPath, 'utf8');
-        const value = toml.parse(raw);
+        const value = getTomlParser().parse(raw);
         if (!isRecord(value)) {
             throw new Error('top-level TOML document must be a table.');
         }
@@ -393,6 +712,9 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
     const model = normalizeOptionalString(readStringValue(parsed.model));
     checks.model.actual = model;
     checks.model.status = model === BASELINE_MODEL ? 'ok' : 'advisory';
+    const reviewModel = normalizeOptionalString(readStringValue(parsed.review_model));
+    checks.review_model.actual = reviewModel;
+    checks.review_model.status = reviewModel === BASELINE_REVIEW_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)
@@ -406,27 +728,208 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
     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');
+    checks.max_depth.status =
+        maxDepth === null || (typeof maxDepth === 'number' && maxDepth >= BASELINE_AGENTS.max_depth) ? 'ok' : 'advisory';
+    if (maxSpawnDepth !== null) {
+        const legacySpawnDepthOk = maxSpawnDepth >= BASELINE_AGENTS.max_depth;
+        legacyMaxSpawnDepth = {
+            present: true,
+            status: legacySpawnDepthOk ? 'ok' : 'advisory',
+            actual: maxSpawnDepth,
+            detail: legacySpawnDepthOk
+                ? 'legacy override detected; safe for the CO baseline, but remove it when your local parser/runtime no longer consumes spawn-depth caps'
+                : `older parser/runtime may still treat this as a hard cap below the CO baseline depth; raise it to >= ${BASELINE_AGENTS.max_depth} or remove it`
+        };
+    }
+    const allChecksOk = Object.values(checks).every((check) => check.status === 'ok')
+        && legacyMaxSpawnDepth?.status !== 'advisory';
     return {
         status: allChecksOk ? 'ok' : 'advisory',
         config: { path: configPath, status: 'ok' },
         checks,
+        legacy_max_spawn_depth: legacyMaxSpawnDepth,
         guidance
     };
 }
+function getTomlParser() {
+    if (tomlParser) {
+        return tomlParser;
+    }
+    if (tomlParser === null) {
+        throw new Error('Failed to load @iarna/toml.');
+    }
+    try {
+        tomlParser = require('@iarna/toml');
+        return tomlParser;
+    }
+    catch (error) {
+        tomlParser = null;
+        throw error;
+    }
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function readStringValue(value) {
-    return typeof value === 'string' ? value : null;
+function readStringValue(value, ...keys) {
+    if (keys.length === 0) {
+        return typeof value === 'string' ? value : null;
+    }
+    if (!isRecord(value)) {
+        return null;
+    }
+    for (const key of keys) {
+        if (typeof value[key] === 'string') {
+            return value[key];
+        }
+    }
+    return null;
 }
 function readNumberValue(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
+function readBooleanValue(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+function readRecordValue(value, ...keys) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    for (const key of keys) {
+        if (isRecord(value[key])) {
+            return value[key];
+        }
+    }
+    return null;
+}
+function readStringArrayValue(value, ...keys) {
+    const raw = isRecord(value)
+        ? keys.map((key) => value[key]).find((entry) => Array.isArray(entry))
+        : Array.isArray(value)
+            ? value
+            : undefined;
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    return raw
+        .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+        .filter((entry) => entry.length > 0);
+}
+function parseEnvBoolean(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return false;
+    }
+    return ['1', 'true', 'yes', 'on'].includes(normalized.toLowerCase());
+}
+function parseCsvList(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return [];
+    }
+    return normalized
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function readProviderControlPolicy(providerRoot) {
+    const preferredPath = join(providerRoot, 'control.json');
+    const fallbackPath = join(providerRoot, 'control.example.json');
+    const candidate = existsSync(preferredPath) ? preferredPath : existsSync(fallbackPath) ? fallbackPath : preferredPath;
+    if (!existsSync(candidate)) {
+        return {
+            status: 'missing',
+            path: preferredPath,
+            dispatch_pilot_enabled: null,
+            dispatch_pilot_provider: null,
+            dispatch_pilot_source_setup: null,
+            transport_mutating_enabled: null,
+            telegram_transport_allowed: null
+        };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+        if (!isRecord(parsed)) {
+            throw new Error('provider control policy must be a JSON object');
+        }
+        const featureToggles = isRecord(parsed.feature_toggles) ? parsed.feature_toggles : null;
+        const dispatchPilot = resolveDispatchPilotControls(featureToggles);
+        const dispatchSource = readRecordValue(dispatchPilot, 'source');
+        const dispatchBindingSource = readRecordValue(dispatchSource, 'linear') ?? dispatchSource;
+        const dispatchPilotEnabled = readBooleanValue(dispatchPilot?.enabled);
+        const rawDispatchPilotProvider = normalizeOptionalString(readStringValue(dispatchSource, 'provider', 'source_provider', 'sourceProvider'));
+        const normalizedDispatchPilotProvider = normalizeDispatchSourceProvider(rawDispatchPilotProvider ?? undefined);
+        if (dispatchPilotEnabled === true) {
+            if (!dispatchSource) {
+                throw new Error('dispatch_pilot.source is required when dispatch_pilot.enabled=true');
+            }
+            if (!normalizedDispatchPilotProvider) {
+                throw new Error(rawDispatchPilotProvider
+                    ? `unsupported dispatch_pilot.source.provider: ${rawDispatchPilotProvider}`
+                    : 'dispatch_pilot.source.provider is required when dispatch_pilot.enabled=true');
+            }
+        }
+        const transportMutating = resolveTransportMutatingControls(featureToggles);
+        const transportMutatingEnabled = readBooleanValue(transportMutating?.enabled);
+        const allowedTransports = readStringArrayValue(transportMutating, 'allowed_transports', 'allowedTransports');
+        const telegramTransportAllowed = transportMutating === null
+            ? null
+            : transportMutatingEnabled === true
+                ? allowedTransports ? allowedTransports.includes('telegram') : true
+                : false;
+        return {
+            status: 'ok',
+            path: candidate,
+            dispatch_pilot_enabled: dispatchPilotEnabled,
+            dispatch_pilot_provider: normalizedDispatchPilotProvider ?? rawDispatchPilotProvider,
+            dispatch_pilot_source_setup: dispatchBindingSource
+                ? {
+                    workspace_id: normalizeOptionalString(readStringValue(dispatchBindingSource, 'workspace_id', 'workspaceId')),
+                    team_id: normalizeOptionalString(readStringValue(dispatchBindingSource, 'team_id', 'teamId')),
+                    project_id: normalizeOptionalString(readStringValue(dispatchBindingSource, 'project_id', 'projectId'))
+                }
+                : null,
+            transport_mutating_enabled: transportMutatingEnabled,
+            telegram_transport_allowed: telegramTransportAllowed
+        };
+    }
+    catch (error) {
+        return {
+            status: 'invalid',
+            path: candidate,
+            detail: error instanceof Error ? error.message : String(error),
+            dispatch_pilot_enabled: null,
+            dispatch_pilot_provider: null,
+            dispatch_pilot_source_setup: null,
+            transport_mutating_enabled: null,
+            telegram_transport_allowed: null
+        };
+    }
+}
+function resolveTransportMutatingControls(featureToggles) {
+    const direct = readRecordValue(featureToggles, 'transport_mutating_controls');
+    const coordinator = readRecordValue(featureToggles, 'coordinator');
+    const nested = readRecordValue(coordinator, 'transport_mutating_controls');
+    return nested ?? direct ?? null;
+}
+function resolveDispatchPilotControls(featureToggles) {
+    const direct = readRecordValue(featureToggles, 'dispatch_pilot');
+    const coordinator = readRecordValue(featureToggles, 'coordinator');
+    const nested = readRecordValue(coordinator, 'dispatch_pilot');
+    return nested ?? direct ?? null;
+}
+function renderProviderToggleSummary(enabled, provider) {
+    if (enabled === null) {
+        return 'unconfigured';
+    }
+    const label = enabled ? 'enabled' : 'disabled';
+    return provider ? `${label} (${provider})` : label;
+}
+function renderTransportPolicySummary(allowed) {
+    if (allowed === null) {
+        return 'unconfigured';
+    }
+    return allowed ? 'telegram allowed' : 'telegram blocked';
+}
 function isReasoningAtLeastMinimum(value, minimum) {
     const rank = resolveReasoningRank(value);
     const minimumRank = resolveReasoningRank(minimum);
@@ -464,10 +967,6 @@ function normalizeOptionalString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
-function normalizeOptionalBranch(value) {
-    const normalized = normalizeOptionalString(value);
-    return normalized ? normalized.replace(/^refs\/heads\//u, '') : null;
-}
 function resolveCloudFallbackPolicy(env = process.env) {
     const raw = normalizeOptionalString(env.CODEX_ORCHESTRATOR_CLOUD_FALLBACK);
     if (!raw) {
@@ -641,82 +1140,3 @@ function canRunCommand(command, args) {
     }
     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, '\\$&');
-}