@kbediako/codex-orchestrator 0.1.38 → 0.2.0

package/dist/bin/codex-orchestrator.js

@@ -1,50 +1,86 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { opendir, readFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { opendir } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
 import process from 'node:process';
-import { fileURLToPath } from 'node:url';
+import { pathToFileURL } from 'node:url';
 import { CodexOrchestrator } from '../orchestrator/src/cli/orchestrator.js';
-import { formatPlanPreview } from '../orchestrator/src/cli/utils/planFormatter.js';
-import { executeExecCommand } from '../orchestrator/src/cli/exec/command.js';
+import { runExecCliShell } from '../orchestrator/src/cli/execCliShell.js';
 import { resolveEnvironmentPaths } from '../scripts/lib/run-manifests.js';
-import { runPrWatchMerge } from '../scripts/lib/pr-watch-merge.js';
-import { normalizeEnvironmentPaths, sanitizeTaskId } from '../orchestrator/src/cli/run/environment.js';
+import { sanitizeTaskId } from '../orchestrator/src/cli/run/environment.js';
 import { RunEventEmitter } from '../orchestrator/src/cli/events/runEvents.js';
 import { evaluateInteractiveGate } from '../orchestrator/src/cli/utils/interactive.js';
 import { buildSelfCheckResult } from '../orchestrator/src/cli/selfCheck.js';
-import { initCodexTemplates, formatInitSummary } from '../orchestrator/src/cli/init.js';
-import { runDoctor, runDoctorCloudPreflight, formatDoctorSummary, formatDoctorCloudPreflightSummary } from '../orchestrator/src/cli/doctor.js';
-import { formatDoctorUsageSummary, runDoctorUsage } from '../orchestrator/src/cli/doctorUsage.js';
+import { runDoctor } from '../orchestrator/src/cli/doctor.js';
+import { runDoctorUsage } from '../orchestrator/src/cli/doctorUsage.js';
 import { formatDoctorIssueLogSummary, writeDoctorIssueLog } from '../orchestrator/src/cli/doctorIssueLog.js';
-import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.js';
-import { formatCodexCliSetupSummary, runCodexCliSetup } from '../orchestrator/src/cli/codexCliSetup.js';
-import { formatCodexDefaultsSetupSummary, runCodexDefaultsSetup } from '../orchestrator/src/cli/codexDefaultsSetup.js';
-import { formatDelegationSetupSummary, runDelegationSetup } from '../orchestrator/src/cli/delegationSetup.js';
-import { formatSkillsInstallSummary, installSkills, listBundledSkills } from '../orchestrator/src/cli/skills.js';
-import { findPackageRoot, loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
+import { runInitCliShell } from '../orchestrator/src/cli/initCliShell.js';
+import { runCodexCliShell } from '../orchestrator/src/cli/codexCliShell.js';
+import { runDevtoolsCliShell } from '../orchestrator/src/cli/devtoolsCliShell.js';
+import { runDelegationCliShell } from '../orchestrator/src/cli/delegationCliShell.js';
+import { runLinearCliShell } from '../orchestrator/src/cli/linearCliShell.js';
+import { runSkillsCliShell } from '../orchestrator/src/cli/skillsCliShell.js';
+import { runFlowCliRequestShell } from '../orchestrator/src/cli/flowCliRequestShell.js';
+import { runStartCliRequestShell } from '../orchestrator/src/cli/startCliRequestShell.js';
+import { runFrontendTestCliRequestShell } from '../orchestrator/src/cli/frontendTestCliRequestShell.js';
+import { runPlanCliShell } from '../orchestrator/src/cli/planCliShell.js';
+import { runDoctorCliRequestShell } from '../orchestrator/src/cli/doctorCliRequestShell.js';
+import { runRlmCliRequestShell } from '../orchestrator/src/cli/rlmCliRequestShell.js';
+import { runRlmCompletionCliShell } from '../orchestrator/src/cli/rlmCompletionCliShell.js';
+import { runResumeCliShell } from '../orchestrator/src/cli/resumeCliShell.js';
+import { runStatusCliShell } from '../orchestrator/src/cli/statusCliShell.js';
+import { runSelfCheckCliShell } from '../orchestrator/src/cli/selfCheckCliShell.js';
+import { printSetupCliHelp, runSetupCliShell } from '../orchestrator/src/cli/setupCliShell.js';
+import { runReviewCliLaunchShell } from '../orchestrator/src/cli/reviewCliLaunchShell.js';
+import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { slugify } from '../orchestrator/src/cli/utils/strings.js';
 import { serveMcp } from '../orchestrator/src/cli/mcp.js';
-import { formatMcpEnableSummary, runMcpEnable } from '../orchestrator/src/cli/mcpEnable.js';
-import { startDelegationServer } from '../orchestrator/src/cli/delegationServer.js';
-import { splitDelegationConfigOverrides } from '../orchestrator/src/cli/config/delegationConfig.js';
-import { buildCommandPreview } from '../orchestrator/src/cli/utils/commandPreview.js';
+import { runMcpEnableCliShell } from '../orchestrator/src/cli/mcpEnableCliShell.js';
+import { runDelegationServerCliShell } from '../orchestrator/src/cli/delegationServerCliShell.js';
+import { DEFAULT_PROVIDER_START_PIPELINE_ID, runControlHostCliShell } from '../orchestrator/src/cli/controlHostCliShell.js';
+import { runControlHostFreshnessGaugeCliShell } from '../orchestrator/src/cli/controlHostFreshnessGaugeCliShell.js';
+import { runControlHostSupervisionCliShell } from '../orchestrator/src/cli/controlHostSupervisionCliShell.js';
+import { runCoStatusAttachCliShell } from '../orchestrator/src/cli/coStatusAttachCliShell.js';
+import { runCoStatusCliShell } from '../orchestrator/src/cli/coStatusCliShell.js';
+import { runCoStatusOperatorAutopilotCliShell } from '../orchestrator/src/cli/coStatusOperatorAutopilotCliShell.js';
 import { REPO_CONFIG_REQUIRED_ENV_KEY } from '../orchestrator/src/cli/config/repoConfigPolicy.js';
 const AUTO_ISSUE_LOG_ENV_KEY = 'CODEX_ORCHESTRATOR_AUTO_ISSUE_LOG';
-async function main() {
-    const args = process.argv.slice(2);
+function writeStderrLine(message) {
+    process.stderr.write(`${message}\n`);
+}
+export function isDirectExecution(entryArg = process.argv[1], metaUrl = import.meta.url) {
+    if (typeof entryArg !== 'string' || entryArg.length === 0) {
+        return false;
+    }
+    const candidateUrls = new Set();
+    try {
+        candidateUrls.add(pathToFileURL(resolve(entryArg)).href);
+    }
+    catch {
+        // Fall through to the realpath check so missing/cwd issues still fail closed.
+    }
+    try {
+        candidateUrls.add(pathToFileURL(realpathSync(entryArg)).href);
+    }
+    catch {
+        // Missing or unreadable entry points should not be treated as direct execution.
+    }
+    return candidateUrls.has(metaUrl);
+}
+export async function runCodexOrchestratorCli(rawArgs = process.argv.slice(2)) {
+    process.exitCode = 0;
+    const args = [...rawArgs];
     const command = args.shift();
     if (!command || command === 'help' || command === '--help' || command === '-h') {
         printHelp();
-        return;
+        return 0;
     }
     if (command === '--version' || command === '-v') {
         printVersion();
-        return;
+        return 0;
     }
-    const orchestrator = new CodexOrchestrator();
     try {
+        const orchestrator = new CodexOrchestrator();
         switch (command) {
             case 'start':
                 await handleStart(orchestrator, args);
@@ -70,6 +106,12 @@ async function main() {
             case 'status':
                 await handleStatus(orchestrator, args);
                 break;
+            case 'control-host':
+                await handleControlHost(args);
+                break;
+            case 'co-status':
+                await handleCoStatus(args);
+                break;
             case 'exec':
                 await handleExec(args);
                 break;
@@ -88,6 +130,9 @@ async function main() {
             case 'codex':
                 await handleCodex(args);
                 break;
+            case 'linear':
+                await handleLinear(args);
+                break;
             case 'devtools':
                 await handleDevtools(args);
                 break;
@@ -111,15 +156,16 @@ async function main() {
                 printVersion();
                 break;
             default:
-                console.error(`Unknown command: ${command}`);
+                writeStderrLine(`Unknown command: ${command}`);
                 printHelp();
                 process.exitCode = 1;
         }
     }
     catch (error) {
-        console.error(error?.message ?? String(error));
+        writeStderrLine(error?.message ?? String(error));
         process.exitCode = 1;
     }
+    return typeof process.exitCode === 'number' ? process.exitCode : 0;
 }
 function parseArgs(raw) {
     const positionals = [];
@@ -128,6 +174,7 @@ function parseArgs(raw) {
     const booleanFlagKeys = new Set([
         'apply',
         'auto-issue-log',
+        'blocked-by-source',
         'cloud',
         'cloud-preflight',
         'codex-cli',
@@ -206,132 +253,6 @@ function resolveTargetStageId(flags) {
     }
     return undefined;
 }
-const FLOW_TARGET_PIPELINE_SCOPES = new Set(['docs-review', 'implementation-gate']);
-function isFlowTargetPipelineScope(scope) {
-    return FLOW_TARGET_PIPELINE_SCOPES.has(scope);
-}
-function normalizeFlowTargetToken(candidate) {
-    const trimmed = candidate.trim();
-    if (!trimmed) {
-        return null;
-    }
-    const tokens = trimmed.split(':');
-    if (tokens.length > 1 && !(tokens[0] ?? '').trim()) {
-        return null;
-    }
-    let scoped = false;
-    let scopeToken = null;
-    let suffixToken = trimmed;
-    if (tokens.length > 1) {
-        const candidateScope = (tokens[0] ?? '').trim().toLowerCase();
-        if (isFlowTargetPipelineScope(candidateScope)) {
-            scoped = true;
-            scopeToken = candidateScope;
-            suffixToken = (tokens[tokens.length - 1] ?? '').trim();
-        }
-    }
-    if (!suffixToken) {
-        return null;
-    }
-    return {
-        literal: trimmed,
-        literalLower: trimmed.toLowerCase(),
-        stageTokenLower: suffixToken.toLowerCase(),
-        scopeLower: scopeToken,
-        scoped
-    };
-}
-function flowPlanItemPipelineId(item) {
-    const metadataPipelineId = item.metadata && typeof item.metadata['pipelineId'] === 'string'
-        ? item.metadata['pipelineId'].trim().toLowerCase()
-        : '';
-    if (metadataPipelineId) {
-        return metadataPipelineId;
-    }
-    const delimiterIndex = item.id.indexOf(':');
-    if (delimiterIndex <= 0) {
-        return null;
-    }
-    return item.id.slice(0, delimiterIndex).trim().toLowerCase() || null;
-}
-function flowPlanItemMatchesTarget(item, candidate) {
-    const normalized = normalizeFlowTargetToken(candidate);
-    if (!normalized) {
-        return false;
-    }
-    if (item.id.toLowerCase() === normalized.literalLower) {
-        return true;
-    }
-    if (normalized.scoped && normalized.scopeLower) {
-        const itemPipelineId = flowPlanItemPipelineId(item);
-        if (itemPipelineId && itemPipelineId !== normalized.scopeLower) {
-            return false;
-        }
-    }
-    const metadataStageId = item.metadata && typeof item.metadata['stageId'] === 'string'
-        ? item.metadata['stageId'].toLowerCase()
-        : null;
-    const aliases = Array.isArray(item.metadata?.['aliases'])
-        ? item.metadata?.['aliases']
-        : [];
-    const aliasTokens = aliases.filter((alias) => typeof alias === 'string')
-        .map((alias) => alias.toLowerCase());
-    if (normalized.scoped) {
-        if (metadataStageId
-            && (metadataStageId === normalized.literalLower || metadataStageId === normalized.stageTokenLower)) {
-            return true;
-        }
-        return aliasTokens.some((alias) => alias === normalized.literalLower || alias === normalized.stageTokenLower);
-    }
-    if (item.id.toLowerCase().endsWith(`:${normalized.stageTokenLower}`)) {
-        return true;
-    }
-    if (metadataStageId
-        && (metadataStageId === normalized.stageTokenLower
-            || metadataStageId.endsWith(`:${normalized.stageTokenLower}`))) {
-        return true;
-    }
-    return aliasTokens.some((alias) => alias === normalized.stageTokenLower || alias.endsWith(`:${normalized.stageTokenLower}`));
-}
-function planIncludesStageId(plan, stageId) {
-    if (!stageId.trim()) {
-        return false;
-    }
-    return plan.plan.items.some((item) => flowPlanItemMatchesTarget(item, stageId));
-}
-function resolveFlowTargetScope(stageId) {
-    const delimiterIndex = stageId.indexOf(':');
-    if (delimiterIndex <= 0) {
-        return null;
-    }
-    const scope = stageId.slice(0, delimiterIndex).trim().toLowerCase();
-    if (!isFlowTargetPipelineScope(scope)) {
-        return null;
-    }
-    return scope;
-}
-async function resolveFlowTargetStageSelection(orchestrator, taskId, requestedTargetStageId) {
-    if (!requestedTargetStageId) {
-        return {};
-    }
-    const [docsPlan, implementationPlan] = (await Promise.all([
-        orchestrator.plan({ pipelineId: 'docs-review', taskId }),
-        orchestrator.plan({ pipelineId: 'implementation-gate', taskId })
-    ]));
-    const requestedScope = resolveFlowTargetScope(requestedTargetStageId);
-    const docsScopeMatch = !requestedScope || requestedScope === 'docs-review';
-    const implementationScopeMatch = !requestedScope || requestedScope === 'implementation-gate';
-    const docsReviewTargetStageId = docsScopeMatch && planIncludesStageId(docsPlan, requestedTargetStageId)
-        ? requestedTargetStageId
-        : undefined;
-    const implementationGateTargetStageId = implementationScopeMatch && planIncludesStageId(implementationPlan, requestedTargetStageId)
-        ? requestedTargetStageId
-        : undefined;
-    if (!docsReviewTargetStageId && !implementationGateTargetStageId) {
-        throw new Error(`Target stage "${requestedTargetStageId}" is not defined in docs-review or implementation-gate.`);
-    }
-    return { docsReviewTargetStageId, implementationGateTargetStageId };
-}
 function readStringFlag(flags, key) {
     const value = flags[key];
     if (typeof value !== 'string') {
@@ -515,30 +436,6 @@ function resolveRlmTaskId(taskFlag) {
     const slug = slugify(repoName, 'adhoc');
     return sanitizeTaskId(`rlm-${slug}`);
 }
-async function waitForManifestCompletion(manifestPath, intervalMs = 2000) {
-    const terminal = new Set(['succeeded', 'failed', 'cancelled']);
-    while (true) {
-        const raw = await readFile(manifestPath, 'utf8');
-        const manifest = JSON.parse(raw);
-        if (terminal.has(manifest.status)) {
-            return manifest;
-        }
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    }
-}
-async function readRlmState(statePath) {
-    try {
-        const raw = await readFile(statePath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (!parsed?.final) {
-            return null;
-        }
-        return { exitCode: parsed.final.exitCode, status: parsed.final.status };
-    }
-    catch {
-        return null;
-    }
-}
 async function maybeCaptureAutoIssueLog(params) {
     if (!params.enabled) {
         return { issueLog: null, issueLogError: null };
@@ -594,110 +491,52 @@ async function handleStart(orchestrator, rawArgs) {
         printStartHelp();
         return;
     }
-    const pipelineId = positionals[0];
-    const format = flags['format'] === 'json' ? 'json' : 'text';
-    const executionMode = resolveExecutionModeFlag(flags);
-    const runtimeMode = resolveRuntimeModeFlag(flags);
-    applyRepoConfigRequiredPolicy(flags);
-    const autoIssueLogEnabled = resolveAutoIssueLogEnabled(flags);
-    if (pipelineId === 'rlm') {
-        const goal = readStringFlag(flags, 'goal');
-        const warnLegacyEnvAlias = shouldWarnLegacyMultiAgentEnv(flags, process.env);
-        applyRlmEnvOverrides(flags, goal);
-        if (warnLegacyEnvAlias) {
-            console.warn('Warning: RLM_SYMBOLIC_COLLAB is a legacy alias; prefer RLM_SYMBOLIC_MULTI_AGENT.');
+    await runStartCliRequestShell({
+        orchestrator,
+        positionals,
+        flags,
+        runWithUi: async (format, action) => await withRunUi(flags, format, action),
+        emitRunOutput,
+        maybeCaptureAutoIssueLog,
+        resolveTaskFilter,
+        withAutoIssueLogContext,
+        maybeEmitRunAdoptionHint,
+        resolveExecutionModeFlag,
+        resolveRuntimeModeFlag,
+        applyRepoConfigRequiredPolicy,
+        resolveAutoIssueLogEnabled,
+        resolveTargetStageId,
+        readStringFlag,
+        shouldWarnLegacyMultiAgentEnv: (requestFlags) => shouldWarnLegacyMultiAgentEnv(requestFlags, process.env),
+        applyRlmEnvOverrides,
+        resolveRlmTaskId,
+        setTaskEnvironment: (taskId) => {
+            process.env.MCP_RUNNER_TASK_ID = taskId;
+        },
+        log: (line) => console.log(line),
+        warn: (line) => console.warn(line),
+        setExitCode: (code) => {
+            process.exitCode = code;
         }
-    }
-    let taskIdOverride = typeof flags['task'] === 'string' ? flags['task'] : undefined;
-    try {
-        await withRunUi(flags, format, async (runEvents) => {
-            if (pipelineId === 'rlm') {
-                taskIdOverride = resolveRlmTaskId(taskIdOverride);
-                process.env.MCP_RUNNER_TASK_ID = taskIdOverride;
-                if (format !== 'json') {
-                    console.log(`Task: ${taskIdOverride}`);
-                }
-            }
-            const result = await orchestrator.start({
-                pipelineId,
-                taskId: taskIdOverride,
-                parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
-                approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
-                targetStageId: resolveTargetStageId(flags),
-                executionMode,
-                runtimeMode,
-                runEvents
-            });
-            const issueLogCapture = result.manifest.status !== 'succeeded'
-                ? await maybeCaptureAutoIssueLog({
-                    enabled: autoIssueLogEnabled,
-                    issueTitle: `Auto issue log: start ${pipelineId ?? 'diagnostics'} failed`,
-                    issueNotes: `Automatic failure capture for run ${result.manifest.run_id} (${result.manifest.status}).`,
-                    taskFilter: resolveTaskFilter(result.manifest.task_id, taskIdOverride)
-                })
-                : { issueLog: null, issueLogError: null };
-            emitRunOutput(result, format, 'Run started', issueLogCapture);
-            if (result.manifest.status === 'failed' || result.manifest.status === 'cancelled') {
-                process.exitCode = 1;
-            }
-            if (result.manifest.status === 'succeeded' && result.manifest.pipeline_id !== 'rlm') {
-                await maybeEmitRunAdoptionHint({
-                    format,
-                    taskFilter: resolveTaskFilter(result.manifest.task_id, taskIdOverride)
-                });
-            }
-        });
-    }
-    catch (error) {
-        const issueLogCapture = await maybeCaptureAutoIssueLog({
-            enabled: autoIssueLogEnabled,
-            issueTitle: `Auto issue log: start ${pipelineId ?? 'diagnostics'} failed before run manifest`,
-            issueNotes: 'Automatic failure capture for start setup failure before run manifest creation.',
-            taskFilter: resolveTaskFilter(undefined, taskIdOverride)
-        });
-        throw withAutoIssueLogContext(error, issueLogCapture);
-    }
+    });
 }
 async function handleFrontendTest(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
-    const format = flags['format'] === 'json' ? 'json' : 'text';
-    const devtools = Boolean(flags['devtools']);
-    const runtimeMode = resolveRuntimeModeFlag(flags);
-    applyRepoConfigRequiredPolicy(flags);
-    if (positionals.length > 0) {
-        console.error(`[frontend-test] ignoring extra arguments: ${positionals.join(' ')}`);
-    }
-    const originalDevtools = process.env.CODEX_REVIEW_DEVTOOLS;
-    if (devtools) {
-        process.env.CODEX_REVIEW_DEVTOOLS = '1';
-    }
-    try {
-        await withRunUi(flags, format, async (runEvents) => {
-            const result = await orchestrator.start({
-                pipelineId: 'frontend-testing',
-                taskId: typeof flags['task'] === 'string' ? flags['task'] : undefined,
-                parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
-                approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
-                targetStageId: resolveTargetStageId(flags),
-                runtimeMode,
-                runEvents
-            });
-            emitRunOutput(result, format, 'Run started');
-            if (result.manifest.status === 'failed' || result.manifest.status === 'cancelled') {
-                process.exitCode = 1;
-            }
-        });
-    }
-    finally {
-        if (devtools) {
-            if (originalDevtools === undefined) {
-                delete process.env.CODEX_REVIEW_DEVTOOLS;
-            }
-            else {
-                process.env.CODEX_REVIEW_DEVTOOLS = originalDevtools;
-            }
-        }
+    if (isHelpRequest(positionals, flags)) {
+        printFrontendTestHelp();
+        return;
     }
+    await runFrontendTestCliRequestShell({
+        orchestrator,
+        positionals,
+        flags,
+        resolveRuntimeModeFlag,
+        applyRepoConfigRequiredPolicy,
+        resolveTargetStageId,
+        runWithUi: async (format, action) => await withRunUi(flags, format, action),
+        emitRunOutput,
+        warn: (line) => console.error(line)
+    });
 }
 async function handleFlow(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -705,174 +544,23 @@ async function handleFlow(orchestrator, rawArgs) {
         printFlowHelp();
         return;
     }
-    if (positionals.length > 0) {
-        throw new Error(`flow does not accept positional arguments: ${positionals.join(' ')}`);
-    }
-    const format = flags['format'] === 'json' ? 'json' : 'text';
-    const executionMode = resolveExecutionModeFlag(flags);
-    const runtimeMode = resolveRuntimeModeFlag(flags);
-    applyRepoConfigRequiredPolicy(flags);
-    const autoIssueLogEnabled = resolveAutoIssueLogEnabled(flags);
-    const taskId = typeof flags['task'] === 'string' ? flags['task'] : undefined;
-    const parentRunId = typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined;
-    const approvalPolicy = typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined;
-    const targetStageId = resolveTargetStageId(flags);
-    try {
-        const { docsReviewTargetStageId, implementationGateTargetStageId } = await resolveFlowTargetStageSelection(orchestrator, taskId, targetStageId);
-        await withRunUi(flags, format, async (runEvents) => {
-            const docsReviewResult = await orchestrator.start({
-                pipelineId: 'docs-review',
-                taskId,
-                parentRunId,
-                approvalPolicy,
-                targetStageId: docsReviewTargetStageId,
-                executionMode,
-                runtimeMode,
-                runEvents
-            });
-            const docsPayload = toRunOutputPayload(docsReviewResult);
-            if (format === 'text') {
-                emitRunOutput(docsReviewResult, format, 'Docs-review run');
-            }
-            if (docsReviewResult.manifest.status !== 'succeeded') {
-                const issueLogCapture = await maybeCaptureAutoIssueLog({
-                    enabled: autoIssueLogEnabled,
-                    issueTitle: 'Auto issue log: flow docs-review failed',
-                    issueNotes: `Automatic failure capture for docs-review run ${docsReviewResult.manifest.run_id} (${docsReviewResult.manifest.status}).`,
-                    taskFilter: resolveTaskFilter(docsReviewResult.manifest.task_id, taskId)
-                });
-                process.exitCode = 1;
-                if (format === 'json') {
-                    const payload = {
-                        status: docsReviewResult.manifest.status,
-                        failed_stage: 'docs-review',
-                        docs_review: docsPayload,
-                        implementation_gate: null,
-                        issue_log: issueLogCapture.issueLog,
-                        issue_log_error: issueLogCapture.issueLogError
-                    };
-                    console.log(JSON.stringify(payload, null, 2));
-                }
-                else {
-                    console.log('Flow halted: docs-review failed.');
-                    if (issueLogCapture.issueLog) {
-                        for (const line of formatDoctorIssueLogSummary(issueLogCapture.issueLog)) {
-                            console.log(line);
-                        }
-                    }
-                    if (issueLogCapture.issueLogError) {
-                        console.log(`Auto issue log: failed (${issueLogCapture.issueLogError})`);
-                    }
-                }
-                return;
-            }
-            const implementationGateResult = await orchestrator.start({
-                pipelineId: 'implementation-gate',
-                taskId,
-                parentRunId: docsReviewResult.manifest.run_id,
-                approvalPolicy,
-                targetStageId: implementationGateTargetStageId,
-                executionMode,
-                runtimeMode,
-                runEvents
-            });
-            const implementationPayload = toRunOutputPayload(implementationGateResult);
-            const issueLogCapture = implementationGateResult.manifest.status !== 'succeeded'
-                ? await maybeCaptureAutoIssueLog({
-                    enabled: autoIssueLogEnabled,
-                    issueTitle: 'Auto issue log: flow implementation-gate failed',
-                    issueNotes: `Automatic failure capture for implementation-gate run ${implementationGateResult.manifest.run_id} (${implementationGateResult.manifest.status}).`,
-                    taskFilter: resolveTaskFilter(implementationGateResult.manifest.task_id, taskId)
-                })
-                : { issueLog: null, issueLogError: null };
-            if (format === 'json') {
-                const payload = {
-                    status: implementationGateResult.manifest.status,
-                    failed_stage: implementationGateResult.manifest.status === 'succeeded' ? null : 'implementation-gate',
-                    docs_review: docsPayload,
-                    implementation_gate: implementationPayload,
-                    issue_log: issueLogCapture.issueLog,
-                    issue_log_error: issueLogCapture.issueLogError
-                };
-                console.log(JSON.stringify(payload, null, 2));
-                if (implementationGateResult.manifest.status !== 'succeeded') {
-                    process.exitCode = 1;
-                }
-                return;
-            }
-            emitRunOutput(implementationGateResult, format, 'Implementation-gate run');
-            if (implementationGateResult.manifest.status !== 'succeeded') {
-                process.exitCode = 1;
-                console.log('Flow halted: implementation-gate failed.');
-                if (issueLogCapture.issueLog) {
-                    for (const line of formatDoctorIssueLogSummary(issueLogCapture.issueLog)) {
-                        console.log(line);
-                    }
-                }
-                if (issueLogCapture.issueLogError) {
-                    console.log(`Auto issue log: failed (${issueLogCapture.issueLogError})`);
-                }
-                return;
-            }
-            console.log('Flow complete: docs-review -> implementation-gate.');
-            await maybeEmitRunAdoptionHint({
-                format,
-                taskFilter: resolveTaskFilter(implementationGateResult.manifest.task_id, taskId)
-            });
-        });
-    }
-    catch (error) {
-        const issueLogCapture = await maybeCaptureAutoIssueLog({
-            enabled: autoIssueLogEnabled,
-            issueTitle: 'Auto issue log: flow failed before run manifest',
-            issueNotes: 'Automatic failure capture for flow setup failure before run manifest creation.',
-            taskFilter: resolveTaskFilter(undefined, taskId)
-        });
-        throw withAutoIssueLogContext(error, issueLogCapture);
-    }
-}
-function runningFromSourceRuntime() {
-    return fileURLToPath(import.meta.url).endsWith('.ts');
-}
-function resolveReviewRunner() {
-    const packageRoot = findPackageRoot(import.meta.url);
-    const sourceRunner = join(packageRoot, 'scripts', 'run-review.ts');
-    const distRunner = join(packageRoot, 'dist', 'scripts', 'run-review.js');
-    if (runningFromSourceRuntime() && existsSync(sourceRunner)) {
-        return {
-            command: process.execPath,
-            args: ['--loader', 'ts-node/esm', sourceRunner]
-        };
-    }
-    if (existsSync(distRunner)) {
-        return {
-            command: process.execPath,
-            args: [distRunner]
-        };
-    }
-    if (existsSync(sourceRunner)) {
-        return {
-            command: process.execPath,
-            args: ['--loader', 'ts-node/esm', sourceRunner]
-        };
-    }
-    throw new Error('Unable to locate review runner. Expected dist/scripts/run-review.js (npm) or scripts/run-review.ts (source checkout).');
-}
-async function runPassthroughCommand(command, args, options = {}) {
-    return await new Promise((resolve, reject) => {
-        const child = spawn(command, args, {
-            env: options.env ?? process.env,
-            cwd: options.cwd ?? process.cwd(),
-            stdio: 'inherit'
-        });
-        child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
-        child.once('close', (code, signal) => {
-            if (signal) {
-                resolve(1);
-                return;
-            }
-            resolve(typeof code === 'number' ? code : 1);
-        });
+    await runFlowCliRequestShell({
+        orchestrator,
+        positionals,
+        flags,
+        runWithUi: async (format, action) => await withRunUi(flags, format, action),
+        emitRunOutput,
+        formatIssueLogSummary: formatDoctorIssueLogSummary,
+        toRunOutputPayload,
+        maybeCaptureAutoIssueLog,
+        resolveTaskFilter,
+        withAutoIssueLogContext,
+        maybeEmitRunAdoptionHint,
+        resolveExecutionModeFlag,
+        resolveRuntimeModeFlag,
+        applyRepoConfigRequiredPolicy,
+        resolveAutoIssueLogEnabled,
+        resolveTargetStageId
     });
 }
 async function handleReview(rawArgs) {
@@ -881,11 +569,7 @@ async function handleReview(rawArgs) {
         printReviewHelp();
         return;
     }
-    const runner = resolveReviewRunner();
-    const exitCode = await runPassthroughCommand(runner.command, [...runner.args, ...rawArgs], {
-        cwd: process.cwd(),
-        env: process.env
-    });
+    const exitCode = await runReviewCliLaunchShell({ rawArgs });
     if (exitCode !== 0) {
         process.exitCode = exitCode;
     }
@@ -899,16 +583,13 @@ async function handlePlan(orchestrator, rawArgs) {
     applyRepoConfigRequiredPolicy(flags);
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    const result = await orchestrator.plan({
+    await runPlanCliShell({
+        orchestrator,
         pipelineId,
         taskId: typeof flags['task'] === 'string' ? flags['task'] : undefined,
-        targetStageId: resolveTargetStageId(flags)
+        targetStageId: resolveTargetStageId(flags),
+        format
     });
-    if (format === 'json') {
-        console.log(JSON.stringify(result, null, 2));
-        return;
-    }
-    process.stdout.write(`${formatPlanPreview(result)}\n`);
 }
 async function handleRlm(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -916,64 +597,36 @@ async function handleRlm(orchestrator, rawArgs) {
         printRlmHelp();
         return;
     }
-    const runtimeMode = resolveRuntimeModeFlag(flags);
-    applyRepoConfigRequiredPolicy(flags);
-    const goalFromArgs = positionals.length > 0 ? positionals.join(' ') : undefined;
-    const goal = goalFromArgs ?? readStringFlag(flags, 'goal') ?? process.env.RLM_GOAL?.trim();
-    if (!goal) {
-        throw new Error('rlm requires a goal. Use: codex-orchestrator rlm \"<goal>\".');
-    }
-    const taskFlag = typeof flags['task'] === 'string' ? flags['task'] : undefined;
-    const taskId = resolveRlmTaskId(taskFlag);
-    process.env.MCP_RUNNER_TASK_ID = taskId;
-    const warnLegacyEnvAlias = shouldWarnLegacyMultiAgentEnv(flags, process.env);
-    applyRlmEnvOverrides(flags, goal);
-    if (warnLegacyEnvAlias) {
-        console.warn('Warning: RLM_SYMBOLIC_COLLAB is a legacy alias; prefer RLM_SYMBOLIC_MULTI_AGENT.');
-    }
-    console.log(`Task: ${taskId}`);
-    const collabUserChoice = flags['collab'] !== undefined ||
-        flags['multi-agent'] !== undefined ||
-        process.env.RLM_SYMBOLIC_COLLAB !== undefined ||
-        process.env.RLM_SYMBOLIC_MULTI_AGENT !== undefined;
-    if (!collabUserChoice) {
-        const doctor = runDoctor();
-        if (doctor.collab.status === 'ok') {
-            console.log('Tip: multi-agent collab is enabled. Try: codex-orchestrator rlm --multi-agent auto \"<goal>\" (legacy: --collab auto).');
-        }
-        else if (doctor.collab.status === 'disabled') {
-            console.log('Tip: multi-agent collab is available but disabled. Enable with: codex features enable multi_agent (legacy alias: collab).');
-        }
-    }
-    let startResult = null;
-    await withRunUi(flags, 'text', async (runEvents) => {
-        startResult = await orchestrator.start({
-            pipelineId: 'rlm',
-            taskId,
-            parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
-            approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
-            runtimeMode,
-            runEvents
-        });
-        emitRunOutput(startResult, 'text', 'Run started');
+    await runRlmCliRequestShell({
+        orchestrator,
+        positionals,
+        flags,
+        env: process.env,
+        runWithUi: async (action) => await withRunUi(flags, 'text', action),
+        emitRunOutput,
+        resolveRuntimeModeFlag,
+        applyRepoConfigRequiredPolicy,
+        readStringFlag,
+        applyRlmEnvOverrides,
+        shouldWarnLegacyEnvAlias: shouldWarnLegacyMultiAgentEnv,
+        resolveRlmTaskId,
+        setTaskEnvironment: (taskId) => {
+            process.env.MCP_RUNNER_TASK_ID = taskId;
+        },
+        runDoctor,
+        resolveRepoRoot: () => resolveEnvironmentPaths().repoRoot,
+        runCompletionShell: async ({ repoRoot, artifactRoot }) => await runRlmCompletionCliShell({
+            repoRoot,
+            artifactRoot,
+            log: (line) => console.log(line),
+            error: (line) => console.error(line),
+            setExitCode: (code) => {
+                process.exitCode = code;
+            }
+        }),
+        log: (line) => console.log(line),
+        warn: (line) => console.warn(line)
     });
-    if (!startResult) {
-        throw new Error('rlm run failed to start.');
-    }
-    const resolvedStart = startResult;
-    const { repoRoot } = resolveEnvironmentPaths();
-    const manifestPath = join(repoRoot, resolvedStart.manifest.artifact_root, 'manifest.json');
-    const manifest = await waitForManifestCompletion(manifestPath);
-    const statePath = join(repoRoot, resolvedStart.manifest.artifact_root, 'rlm', 'state.json');
-    const rlmState = await readRlmState(statePath);
-    if (rlmState) {
-        console.log(`RLM status: ${rlmState.status}`);
-        process.exitCode = rlmState.exitCode;
-        return;
-    }
-    console.log(`RLM status: ${manifest.status}`);
-    console.error('RLM state file missing; treating as internal error.');
-    process.exitCode = 10;
 }
 async function handleResume(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -988,17 +641,17 @@ async function handleResume(orchestrator, rawArgs) {
         throw new Error('resume requires --run <run-id>.');
     }
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    await withRunUi(flags, format, async (runEvents) => {
-        const result = await orchestrator.resume({
-            runId,
-            resumeToken: typeof flags['token'] === 'string' ? flags['token'] : undefined,
-            actor: typeof flags['actor'] === 'string' ? flags['actor'] : undefined,
-            reason: typeof flags['reason'] === 'string' ? flags['reason'] : undefined,
-            targetStageId: resolveTargetStageId(flags),
-            runtimeMode,
-            runEvents
-        });
-        emitRunOutput(result, format, 'Run resumed');
+    await runResumeCliShell({
+        orchestrator,
+        runId,
+        format,
+        runtimeMode,
+        resumeToken: typeof flags['token'] === 'string' ? flags['token'] : undefined,
+        actor: typeof flags['actor'] === 'string' ? flags['actor'] : undefined,
+        reason: typeof flags['reason'] === 'string' ? flags['reason'] : undefined,
+        targetStageId: resolveTargetStageId(flags),
+        runWithUi: async (action) => await withRunUi(flags, format, action),
+        emitRunOutput
     });
 }
 async function handleStatus(orchestrator, rawArgs) {
@@ -1014,18 +667,84 @@ async function handleStatus(orchestrator, rawArgs) {
     const watch = Boolean(flags['watch']);
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const interval = parseInt(flags['interval'] ?? '10', 10);
-    if (!watch) {
-        await orchestrator.status({ runId, format });
+    await runStatusCliShell({ orchestrator, runId, watch, format, interval });
+}
+async function handleControlHost(rawArgs) {
+    if (rawArgs[0] === 'freshness-gauge') {
+        const { positionals, flags } = parseArgs(rawArgs.slice(1));
+        if (isHelpRequest(positionals, flags)) {
+            printControlHostFreshnessGaugeHelp();
+            return;
+        }
+        if (positionals.length > 0) {
+            throw new Error(`Unknown control-host freshness-gauge argument(s): ${positionals.join(' ')}`);
+        }
+        await runControlHostFreshnessGaugeCliShell({
+            flags,
+            printHelp: printControlHostFreshnessGaugeHelp
+        });
         return;
     }
-    const terminal = new Set(['succeeded', 'failed', 'cancelled']);
-    while (true) {
-        const manifest = await orchestrator.status({ runId, format });
-        if (terminal.has(manifest.status)) {
-            break;
+    if (rawArgs[0] === 'supervise') {
+        const { positionals, flags } = parseArgs(rawArgs.slice(1));
+        await runControlHostSupervisionCliShell({
+            positionals,
+            flags,
+            printHelp: printControlHostSupervisionHelp
+        });
+        return;
+    }
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printControlHostHelp();
+        return;
+    }
+    if (positionals.length > 0) {
+        throw new Error(`Unknown control-host argument(s): ${positionals.join(' ')}`);
+    }
+    await runControlHostCliShell({
+        flags,
+        printHelp: printControlHostHelp
+    });
+}
+async function handleCoStatus(rawArgs) {
+    if (rawArgs[0] === 'operator-autopilot') {
+        const { positionals, flags } = parseArgs(rawArgs.slice(1));
+        if (isHelpRequest(positionals, flags)) {
+            printCoStatusOperatorAutopilotHelp();
+            return;
+        }
+        await runCoStatusOperatorAutopilotCliShell({
+            positionals,
+            flags,
+            printHelp: printCoStatusOperatorAutopilotHelp
+        });
+        return;
+    }
+    if (rawArgs[0] === 'attach') {
+        const { positionals, flags } = parseArgs(rawArgs.slice(1));
+        if (isHelpRequest(positionals, flags)) {
+            printCoStatusAttachHelp();
+            return;
         }
-        await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+        if (positionals.length > 0) {
+            throw new Error(`Unknown co-status attach argument(s): ${positionals.join(' ')}`);
+        }
+        await runCoStatusAttachCliShell({
+            flags,
+            printHelp: printCoStatusAttachHelp
+        });
+        return;
     }
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printCoStatusHelp();
+        return;
+    }
+    await runCoStatusCliShell({
+        flags,
+        printHelp: printCoStatusHelp
+    });
 }
 async function maybeStartHud(gate, emitter) {
     if (!gate.enabled) {
@@ -1111,40 +830,9 @@ function toRunOutputPayload(result, issueLogCapture = { issueLog: null, issueLog
     };
 }
 async function handleExec(rawArgs) {
-    const parsed = parseExecArgs(rawArgs);
-    if (parsed.commandTokens.length === 0) {
-        throw new Error('exec requires a command to run.');
-    }
-    const isInteractive = process.stdout.isTTY === true && process.stderr.isTTY === true;
-    const outputMode = parsed.requestedMode ?? (isInteractive ? 'interactive' : 'jsonl');
-    const env = normalizeEnvironmentPaths(resolveEnvironmentPaths());
-    if (parsed.taskId) {
-        env.taskId = sanitizeTaskId(parsed.taskId);
-    }
-    const context = {
-        env,
-        stdout: process.stdout,
-        stderr: process.stderr
-    };
-    const invocation = {
-        command: parsed.commandTokens[0],
-        args: parsed.commandTokens.slice(1),
-        cwd: parsed.cwd,
-        outputMode,
-        notifyTargets: parsed.notifyTargets,
-        otelEndpoint: parsed.otelEndpoint,
-        jsonPretty: parsed.jsonPretty
-    };
-    const result = await executeExecCommand(context, invocation);
-    if (result.exitCode !== null) {
-        process.exitCode = result.exitCode;
-    }
-    else if (result.status !== 'succeeded') {
-        process.exitCode = 1;
-    }
-    if (outputMode === 'interactive') {
-        await maybeEmitExecAdoptionHint(env.taskId);
-    }
+    await runExecCliShell(parseExecArgs(rawArgs), {
+        maybeEmitAdoptionHint: maybeEmitExecAdoptionHint
+    });
 }
 async function shouldScanAdoptionHint(taskFilter) {
     if (!taskFilter) {
@@ -1204,16 +892,11 @@ async function maybeEmitExecAdoptionHint(taskFilter) {
 async function handleSelfCheck(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    const result = buildSelfCheckResult();
-    if (format === 'json') {
-        console.log(JSON.stringify(result, null, 2));
-        return;
-    }
-    console.log(`Status: ${result.status}`);
-    console.log(`Name: ${result.name}`);
-    console.log(`Version: ${result.version}`);
-    console.log(`Node: ${result.node}`);
-    console.log(`Timestamp: ${result.timestamp}`);
+    await runSelfCheckCliShell({
+        format,
+        buildResult: buildSelfCheckResult,
+        log: (line) => console.log(line)
+    });
 }
 async function handleInit(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -1221,439 +904,46 @@ async function handleInit(rawArgs) {
         printInitHelp();
         return;
     }
-    const template = positionals[0];
-    if (!template) {
-        throw new Error('init requires a template name (e.g. init codex).');
-    }
-    if (template !== 'codex') {
-        throw new Error(`Unknown init template: ${template}`);
-    }
-    const cwd = typeof flags['cwd'] === 'string' ? flags['cwd'] : process.cwd();
-    const force = Boolean(flags['force']);
-    const result = await initCodexTemplates({ template, cwd, force });
-    const summary = formatInitSummary(result, cwd);
-    for (const line of summary) {
-        console.log(line);
-    }
-    if (flags['codex-cli'] === true) {
-        const apply = Boolean(flags['yes']);
-        const source = readStringFlag(flags, 'codex-source');
-        const ref = readStringFlag(flags, 'codex-ref');
-        const downloadUrl = readStringFlag(flags, 'codex-download-url');
-        const downloadSha256 = readStringFlag(flags, 'codex-download-sha256');
-        const cliForce = Boolean(flags['codex-force']);
-        const setupResult = await runCodexCliSetup({
-            apply,
-            force: cliForce,
-            source,
-            ref,
-            downloadUrl,
-            downloadSha256
-        });
-        for (const line of formatCodexCliSetupSummary(setupResult)) {
-            console.log(line);
-        }
-    }
+    await runInitCliShell({ positionals, flags });
 }
 async function handleSetup(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     if (isHelpRequest(positionals, flags)) {
-        console.log(`Usage: codex-orchestrator setup [--yes] [--refresh-skills] [--format json]
-
-One-shot bootstrap for downstream users. Installs bundled skills and configures
-delegation + DevTools MCP wiring.
-
-Options:
-  --yes                 Apply setup (otherwise plan only).
-  --refresh-skills      Overwrite bundled skills in $CODEX_HOME/skills during setup.
-  --repo <path>         Repo root for delegation wiring (default cwd).
-  --format json         Emit machine-readable output (dry-run only).
-`);
+        printSetupCliHelp();
         return;
     }
-    const format = flags['format'] === 'json' ? 'json' : 'text';
-    const apply = Boolean(flags['yes']);
-    const refreshSkills = Boolean(flags['refresh-skills']);
-    if (format === 'json' && apply) {
-        throw new Error('setup does not support --format json with --yes.');
-    }
-    const repoFlag = readStringFlag(flags, 'repo');
-    const repoRoot = repoFlag ?? process.cwd();
-    const delegationCommandPreview = repoFlag
-        ? buildCommandPreview('codex-orchestrator', ['delegation', 'setup', '--yes', '--repo', repoFlag])
-        : 'codex-orchestrator delegation setup --yes';
-    const bundledSkills = await listBundledSkills();
-    if (bundledSkills.length === 0) {
-        throw new Error('No bundled skills detected; cannot run setup.');
-    }
-    const guidance = buildSetupGuidance();
-    if (!apply) {
-        const installCommand = `codex-orchestrator skills install ${refreshSkills ? '--force ' : ''}--only ${bundledSkills.join(',')}`;
-        const skillsNote = refreshSkills
-            ? 'Installs bundled skills into $CODEX_HOME/skills with overwrite enabled via --refresh-skills.'
-            : 'Installs bundled skills into $CODEX_HOME/skills without overwriting existing files by default. Add --refresh-skills to force overwrite.';
-        const delegation = await runDelegationSetup({ repoRoot });
-        const devtools = await runDevtoolsSetup();
-        const payload = {
-            status: 'planned',
-            steps: {
-                skills: {
-                    commandLines: [installCommand],
-                    note: skillsNote
-                },
-                delegation,
-                devtools,
-                guidance
-            }
-        };
-        if (format === 'json') {
-            console.log(JSON.stringify(payload, null, 2));
-            return;
-        }
-        console.log('Setup plan:');
-        console.log('- Skills:');
-        for (const commandLine of payload.steps.skills.commandLines) {
-            console.log(`  - ${commandLine}`);
-        }
-        console.log(`- Delegation: ${delegationCommandPreview}`);
-        console.log('- DevTools: codex-orchestrator devtools setup --yes');
-        for (const line of formatSetupGuidanceSummary(guidance)) {
-            console.log(line);
-        }
-        console.log('Run with --yes to apply this setup.');
-        return;
-    }
-    const skills = await installSkills({ force: refreshSkills, only: bundledSkills });
-    const delegation = await runDelegationSetup({ apply: true, repoRoot });
-    const devtools = await runDevtoolsSetup({ apply: true });
-    for (const line of formatSkillsInstallSummary(skills)) {
-        console.log(line);
-    }
-    for (const line of formatDelegationSetupSummary(delegation)) {
-        console.log(line);
-    }
-    for (const line of formatDevtoolsSetupSummary(devtools)) {
-        console.log(line);
-    }
-    for (const line of formatSetupGuidanceSummary(guidance)) {
-        console.log(line);
-    }
-    console.log('Next: codex-orchestrator doctor --usage');
-}
-function buildSetupGuidance() {
-    return {
-        note: 'Agent-first default: run docs-review before implementation and implementation-gate before handoff.',
-        references: [
-            'https://github.com/Kbediako/CO#downstream-usage-cheatsheet-agent-first',
-            'https://github.com/Kbediako/CO/blob/main/docs/AGENTS.md',
-            'https://github.com/Kbediako/CO/blob/main/docs/guides/collab-vs-mcp.md',
-            'https://github.com/Kbediako/CO/blob/main/docs/guides/rlm-recursion-v2.md'
-        ],
-        recommended_commands: [
-            'codex-orchestrator flow --task <task-id>',
-            'codex-orchestrator doctor --usage',
-            'codex-orchestrator rlm --multi-agent auto "<goal>"',
-            'codex-orchestrator codex defaults --yes',
-            'codex-orchestrator mcp enable --servers delegation --yes'
-        ]
-    };
-}
-function formatSetupGuidanceSummary(guidance) {
-    const lines = ['Setup guidance:', `- ${guidance.note}`];
-    if (guidance.recommended_commands.length > 0) {
-        lines.push('- Recommended commands:');
-        for (const command of guidance.recommended_commands) {
-            lines.push(`  - ${command}`);
-        }
-    }
-    if (guidance.references.length > 0) {
-        lines.push('- References:');
-        for (const reference of guidance.references) {
-            lines.push(`  - ${reference}`);
-        }
-    }
-    return lines;
+    await runSetupCliShell({ flags });
 }
 async function handleDoctor(rawArgs) {
-    const { flags } = parseArgs(rawArgs);
-    const format = flags['format'] === 'json' ? 'json' : 'text';
-    const includeUsage = Boolean(flags['usage']);
-    const includeCloudPreflight = Boolean(flags['cloud-preflight']);
-    const includeIssueLog = Boolean(flags['issue-log']);
-    const cloudEnvIdOverride = readStringFlag(flags, 'cloud-env-id');
-    const cloudBranchOverride = readStringFlag(flags, 'cloud-branch');
-    const issueTitle = readStringFlag(flags, 'issue-title');
-    const issueNotes = readStringFlag(flags, 'issue-notes');
-    const issueLogPath = readStringFlag(flags, 'issue-log-path');
-    if (!includeCloudPreflight && (cloudEnvIdOverride || cloudBranchOverride)) {
-        throw new Error('--cloud-env-id/--cloud-branch require --cloud-preflight.');
-    }
-    if (!includeIssueLog && (issueTitle || issueNotes || issueLogPath)) {
-        throw new Error('--issue-title/--issue-notes/--issue-log-path require --issue-log.');
-    }
-    const wantsApply = Boolean(flags['apply']);
-    const apply = Boolean(flags['yes']);
-    if (wantsApply && format === 'json') {
-        throw new Error('doctor --apply does not support --format json.');
-    }
-    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;
-    const cloudPreflightResult = includeCloudPreflight
-        ? await runDoctorCloudPreflight({
-            cwd: process.cwd(),
-            environmentId: cloudEnvIdOverride,
-            branch: cloudBranchOverride,
-            taskId: taskFilter
-        })
-        : null;
-    const issueLogResult = includeIssueLog
-        ? await writeDoctorIssueLog({
-            doctor: doctorResult,
-            usage: usageResult,
-            cloudPreflight: cloudPreflightResult,
-            issueTitle,
-            issueNotes,
-            issueLogPath,
-            taskFilter
-        })
-        : null;
-    if (format === 'json') {
-        const payload = { ...doctorResult };
-        if (usageResult) {
-            payload.usage = usageResult;
-        }
-        if (cloudPreflightResult) {
-            payload.cloud_preflight = cloudPreflightResult;
-        }
-        if (issueLogResult) {
-            payload.issue_log = issueLogResult;
-        }
-        console.log(JSON.stringify(payload, null, 2));
-        return;
-    }
-    for (const line of formatDoctorSummary(doctorResult)) {
-        console.log(line);
-    }
-    if (usageResult) {
-        for (const line of formatDoctorUsageSummary(usageResult)) {
-            console.log(line);
-        }
-    }
-    if (cloudPreflightResult) {
-        for (const line of formatDoctorCloudPreflightSummary(cloudPreflightResult)) {
-            console.log(line);
-        }
-    }
-    if (issueLogResult) {
-        for (const line of formatDoctorIssueLogSummary(issueLogResult)) {
-            console.log(line);
-        }
-    }
-    if (!wantsApply) {
-        return;
-    }
-    const repoRoot = process.cwd();
-    const delegationPlan = await runDelegationSetup({ repoRoot });
-    const devtoolsPlan = await runDevtoolsSetup();
-    const needsDelegation = !delegationPlan.readiness.configured;
-    const needsDevtoolsSkill = devtoolsPlan.readiness.skill.status !== 'ok';
-    const devtoolsConfigStatus = devtoolsPlan.readiness.config.status;
-    const needsDevtoolsConfig = devtoolsConfigStatus === 'missing';
-    const hasInvalidDevtoolsConfig = devtoolsConfigStatus === 'invalid';
-    if (!needsDelegation && !needsDevtoolsSkill && !needsDevtoolsConfig && !hasInvalidDevtoolsConfig) {
-        console.log('Doctor apply: nothing to do.');
-        return;
-    }
-    console.log('Doctor apply plan:');
-    if (needsDevtoolsSkill) {
-        console.log('- Install skill: chrome-devtools (codex-orchestrator skills install --only chrome-devtools)');
-    }
-    if (hasInvalidDevtoolsConfig) {
-        console.log(`- DevTools MCP config is invalid: ${devtoolsPlan.readiness.config.path} (fix config.toml then rerun doctor --apply)`);
-    }
-    if (needsDevtoolsConfig) {
-        console.log('- Configure DevTools MCP: codex-orchestrator devtools setup --yes');
-    }
-    if (needsDelegation) {
-        console.log('- Configure delegation MCP: codex-orchestrator delegation setup --yes');
-    }
-    if (!apply) {
-        console.log('Run with --apply --yes to apply these fixes.');
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printDoctorHelp();
         return;
     }
-    if (needsDevtoolsSkill) {
-        const skills = await installSkills({ only: ['chrome-devtools'] });
-        for (const line of formatSkillsInstallSummary(skills)) {
-            console.log(line);
-        }
-    }
-    if (needsDelegation) {
-        const delegation = await runDelegationSetup({ apply: true, repoRoot });
-        for (const line of formatDelegationSetupSummary(delegation)) {
-            console.log(line);
-        }
-    }
-    if (hasInvalidDevtoolsConfig) {
-        console.log(`DevTools setup: skipped (config.toml is invalid: ${devtoolsPlan.readiness.config.path}). Fix it and rerun doctor --apply --yes.`);
-    }
-    else if (needsDevtoolsConfig) {
-        const devtools = await runDevtoolsSetup({ apply: true });
-        for (const line of formatDevtoolsSetupSummary(devtools)) {
-            console.log(line);
-        }
-    }
-    const doctorAfter = runDoctor();
-    for (const line of formatDoctorSummary(doctorAfter)) {
-        console.log(line);
+    if (positionals.length > 0) {
+        throw new Error(`Unknown doctor argument(s): ${positionals.join(' ')}`);
     }
+    await runDoctorCliRequestShell({ flags });
 }
 async function handleDevtools(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
-    const subcommand = positionals.shift();
-    if (!subcommand) {
-        throw new Error('devtools requires a subcommand (setup).');
-    }
-    if (subcommand !== 'setup') {
-        throw new Error(`Unknown devtools subcommand: ${subcommand}`);
-    }
-    const format = flags['format'] === 'json' ? 'json' : 'text';
-    const apply = Boolean(flags['yes']);
-    if (format === 'json' && apply) {
-        throw new Error('devtools setup does not support --format json with --yes.');
-    }
-    const result = await runDevtoolsSetup({ apply });
-    if (format === 'json') {
-        console.log(JSON.stringify(result, null, 2));
-        return;
-    }
-    const summary = formatDevtoolsSetupSummary(result);
-    for (const line of summary) {
-        console.log(line);
-    }
+    await runDevtoolsCliShell({ positionals, flags });
 }
 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);
-    }
+    await runDelegationCliShell({ positionals, flags });
 }
 async function handleCodex(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
-    const subcommand = positionals.shift();
-    if (flags['help'] === true || flags['--help'] === true || flags['h'] === true || !subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
-        printCodexHelp();
-        return;
-    }
-    if (subcommand === 'setup') {
-        const format = flags['format'] === 'json' ? 'json' : 'text';
-        const apply = Boolean(flags['yes']);
-        const source = readStringFlag(flags, 'source');
-        const ref = readStringFlag(flags, 'ref');
-        const downloadUrl = readStringFlag(flags, 'download-url');
-        const downloadSha256 = readStringFlag(flags, 'download-sha256');
-        const force = Boolean(flags['force']);
-        const result = await runCodexCliSetup({
-            apply,
-            force,
-            source,
-            ref,
-            downloadUrl,
-            downloadSha256
-        });
-        if (format === 'json') {
-            console.log(JSON.stringify(result, null, 2));
-            return;
-        }
-        const summary = formatCodexCliSetupSummary(result);
-        for (const line of summary) {
-            console.log(line);
-        }
-        return;
-    }
-    if (subcommand === 'defaults') {
-        const format = flags['format'] === 'json' ? 'json' : 'text';
-        const apply = Boolean(flags['yes']);
-        const force = Boolean(flags['force']);
-        const result = await runCodexDefaultsSetup({
-            apply,
-            force
-        });
-        if (format === 'json') {
-            console.log(JSON.stringify(result, null, 2));
-            return;
-        }
-        const summary = formatCodexDefaultsSetupSummary(result);
-        for (const line of summary) {
-            console.log(line);
-        }
-        return;
-    }
-    throw new Error(`Unknown codex subcommand: ${subcommand}`);
+    await runCodexCliShell({ positionals, flags, printHelp: printCodexHelp });
 }
 async function handleSkills(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
-    const subcommand = positionals[0];
-    const wantsHelp = flags['help'] === true || subcommand === 'help' || subcommand === '--help';
-    if (!subcommand || wantsHelp) {
-        printSkillsHelp();
-        return;
-    }
-    switch (subcommand) {
-        case 'install': {
-            const format = flags['format'] === 'json' ? 'json' : 'text';
-            const force = flags['force'] === true;
-            const codexHome = readStringFlag(flags, 'codex-home');
-            const onlyRaw = flags['only'];
-            let only;
-            if (onlyRaw !== undefined) {
-                if (typeof onlyRaw !== 'string') {
-                    throw new Error('--only requires a comma-separated list of skill names.');
-                }
-                only = onlyRaw.split(',').map((entry) => entry.trim()).filter(Boolean);
-            }
-            const result = await installSkills({ force, codexHome, only });
-            if (format === 'json') {
-                console.log(JSON.stringify(result, null, 2));
-            }
-            else {
-                console.log(formatSkillsInstallSummary(result).join('\n'));
-            }
-            return;
-        }
-        default:
-            throw new Error(`Unknown skills command: ${subcommand}`);
-    }
+    await runSkillsCliShell({ positionals, flags, printHelp: printSkillsHelp });
+}
+async function handleLinear(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    await runLinearCliShell({ positionals, flags, printHelp: printLinearHelp });
 }
 async function handleMcp(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -1672,182 +962,31 @@ async function handleMcp(rawArgs) {
         return;
     }
     if (subcommand === 'enable') {
-        const allowedEnableFlags = new Set(['yes', 'format', 'servers']);
-        let yesFlag;
-        let formatFlag;
-        let serversFlag;
-        const unexpectedPositionals = [];
-        const enableTokens = rawArgs.slice(1);
-        for (let index = 0; index < enableTokens.length; index += 1) {
-            const token = enableTokens[index];
-            if (!token) {
-                continue;
-            }
-            if (token === '--') {
-                unexpectedPositionals.push(...enableTokens.slice(index + 1));
-                break;
-            }
-            if (!token.startsWith('--')) {
-                unexpectedPositionals.push(token);
-                continue;
-            }
-            const [key, inlineValue] = token.slice(2).split('=', 2);
-            if (!allowedEnableFlags.has(key)) {
-                throw new Error(`Unknown mcp enable flag: --${key}`);
-            }
-            let resolvedValue = true;
-            if (inlineValue !== undefined) {
-                resolvedValue = inlineValue;
-            }
-            else {
-                const nextToken = enableTokens[index + 1];
-                if (nextToken && !nextToken.startsWith('--')) {
-                    resolvedValue = nextToken;
-                    index += 1;
-                }
-            }
-            if (key === 'yes') {
-                if (yesFlag !== undefined) {
-                    throw new Error('--yes specified multiple times.');
-                }
-                yesFlag = resolvedValue;
-                continue;
-            }
-            if (key === 'format') {
-                if (formatFlag !== undefined) {
-                    throw new Error('--format specified multiple times.');
-                }
-                formatFlag = resolvedValue;
-                continue;
-            }
-            if (serversFlag !== undefined) {
-                throw new Error('--servers specified multiple times.');
-            }
-            serversFlag = resolvedValue;
-        }
-        if (positionals.length > 0 || unexpectedPositionals.length > 0) {
-            throw new Error(`mcp enable does not accept positional arguments: ${[...positionals, ...unexpectedPositionals].join(' ')}`);
-        }
-        let apply = false;
-        if (yesFlag === true) {
-            apply = true;
-        }
-        else if (typeof yesFlag === 'string') {
-            const normalizedYes = yesFlag.trim().toLowerCase();
-            if (normalizedYes === 'true' || normalizedYes === '1' || normalizedYes === 'yes' || normalizedYes === 'on') {
-                apply = true;
-            }
-            else if (normalizedYes === 'false'
-                || normalizedYes === '0'
-                || normalizedYes === 'no'
-                || normalizedYes === 'off') {
-                apply = false;
-            }
-            else {
-                throw new Error('--yes expects true/false when provided as --yes=<value>.');
-            }
-        }
-        let format = 'text';
-        if (formatFlag !== undefined) {
-            if (formatFlag === true) {
-                throw new Error('--format requires a value of "text" or "json".');
-            }
-            if (formatFlag === 'json') {
-                format = 'json';
-            }
-            else if (formatFlag === 'text') {
-                format = 'text';
-            }
-            else {
-                throw new Error('--format must be "text" or "json".');
-            }
-        }
-        let serverNames;
-        if (serversFlag !== undefined) {
-            if (typeof serversFlag !== 'string') {
-                throw new Error('--servers must include a comma-separated list of MCP server names.');
-            }
-            serverNames = serversFlag
-                .split(',')
-                .map((entry) => entry.trim())
-                .filter((entry) => entry.length > 0);
-            if (serverNames.length === 0) {
-                throw new Error('--servers must include a comma-separated list of MCP server names.');
-            }
-        }
-        const result = await runMcpEnable({ apply, serverNames });
-        const hasApplyFailures = apply
-            && result.actions.some((action) => action.status !== 'enabled' && action.status !== 'already_enabled');
-        if (format === 'json') {
-            console.log(JSON.stringify(result, null, 2));
-        }
-        else {
-            for (const line of formatMcpEnableSummary(result)) {
-                console.log(line);
-            }
-        }
-        if (hasApplyFailures) {
-            process.exitCode = 1;
-        }
+        await runMcpEnableCliShell({ rawArgs: rawArgs.slice(1) });
         return;
     }
     throw new Error(`Unknown mcp subcommand: ${subcommand}`);
 }
 async function handlePr(rawArgs) {
-    if (rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h' || rawArgs[0] === 'help') {
+    if (rawArgs.length === 0 || isCliHelpToken(rawArgs[0])) {
         printPrHelp();
         return;
     }
     const [subcommand, ...subcommandArgs] = rawArgs;
-    const modeBySubcommand = {
-        'watch-merge': {
-            usage: 'codex-orchestrator pr watch-merge'
-        },
-        'resolve-merge': {
-            usage: 'codex-orchestrator pr resolve-merge',
-            defaultExitOnActionRequired: true
-        }
-    };
-    const mode = modeBySubcommand[subcommand];
-    if (!mode) {
-        throw new Error(`Unknown pr subcommand: ${subcommand}`);
-    }
-    const exitCode = await runPrWatchMerge(subcommandArgs, mode);
-    if (exitCode !== 0) {
-        process.exitCode = exitCode;
+    if (isPrHelpSubcommand(subcommand) && shouldPrintPrSubcommandHelp(subcommandArgs)) {
+        printPrSubcommandHelp(subcommand);
+        return;
     }
+    const { runPrCliShell } = await import('../orchestrator/src/cli/prCliShell.js');
+    await runPrCliShell({ rawArgs });
 }
 async function handleDelegationServer(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
-    if (isHelpRequest(positionals, flags)) {
-        printDelegationServerHelp();
-        return;
-    }
-    const repoRoot = typeof flags['repo'] === 'string' ? flags['repo'] : process.cwd();
-    const modeFlag = typeof flags['mode'] === 'string' ? flags['mode'] : undefined;
-    const overrideFlag = typeof flags['config'] === 'string'
-        ? flags['config']
-        : typeof flags['config-override'] === 'string'
-            ? flags['config-override']
-            : undefined;
-    const envMode = process.env.CODEX_DELEGATE_MODE?.trim();
-    const resolvedMode = modeFlag ?? envMode;
-    let mode;
-    if (resolvedMode) {
-        if (resolvedMode === 'full' || resolvedMode === 'question_only') {
-            mode = resolvedMode;
-        }
-        else {
-            console.warn(`Invalid delegate mode "${resolvedMode}". Falling back to config default.`);
-        }
-    }
-    const configOverrides = overrideFlag
-        ? splitDelegationConfigOverrides(overrideFlag).map((value) => ({
-            source: 'cli',
-            value
-        }))
-        : [];
-    await startDelegationServer({ repoRoot, mode, configOverrides });
+    await runDelegationServerCliShell({
+        positionals,
+        flags,
+        printHelp: printDelegationServerHelp
+    });
 }
 function parseExecArgs(rawArgs) {
     const notifyTargets = [];
@@ -2136,6 +1275,20 @@ Commands:
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
+  control-host [options]
+    Start a persistent Linear intake and Telegram/status host without tying it to a foreground run.
+    --task <id>             Artifact task id for the host state (default: local-mcp).
+    --run <id>              Host run id for persisted state files (default: control-host).
+    --pipeline <id>         Pipeline used for provider-driven starts (default: diagnostics).
+    --format json           Emit machine-readable readiness output.
+  control-host freshness-gauge [options]
+    Replay local provider/control-host artifacts and emit throughput/freshness health JSON.
+
+  co-status [options]
+    Attach the CO STATUS terminal viewer or emit the current snapshot from an already-running local control-host.
+  co-status attach [options]
+    Attach a read-only CO STATUS viewer to an already-running local control-host.
+
   status --run <id> [--watch] [--interval N] [--format json]
 
   self-check [--format json]
@@ -2186,11 +1339,15 @@ Commands:
     --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).
+  delegation cleanup-stale
+    --yes                 Terminate stale delegate-server processes not rooted in a live codex client.
+    --format json         Emit machine-readable output.
   skills install          Install bundled skills into $CODEX_HOME/skills.
     --force               Overwrite existing skill files.
     --only <skills>       Install only selected skills (comma-separated).
     --codex-home <path>   Override the target Codex home directory.
     --format json         Emit machine-readable output.
+  linear <subcommand>     Run worker-visible Linear helper operations.
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
   mcp enable [--servers <csv>] [--yes] [--format json]
     --servers <csv>       Comma-separated MCP server names to enable (default: all disabled).
@@ -2202,10 +1359,15 @@ Commands:
   pr resolve-merge [options]
     Monitor until merge-ready or actionable feedback appears; exits early when author action is required.
     Use \`codex-orchestrator pr resolve-merge --help\` for full options.
+  pr ready-review [options]
+    Wait through a bounded automated-feedback drain before human review handoff; exits early when author action is required.
+    Use \`codex-orchestrator pr ready-review --help\` for full options.
   delegate-server         Run the delegation MCP server (stdio).
     --repo <path>         Repo root for config + manifests (default cwd).
-    --mode <full|question_only>  Limit tool surface for child runs.
+    --mode <full|question_only|status_only>  Limit tool surface for child runs.
     --config "<key>=<value>[;...]"  Apply config overrides (repeat via separators).
+  control-host            Run the persistent provider intake + oversight host.
+  co-status               Attach the CO STATUS terminal viewer or emit the current snapshot from an already-running local control-host.
   version | --version
 
   help                      Show this message.
@@ -2213,6 +1375,7 @@ Commands:
 Quickstart (agent-first):
   codex-orchestrator flow --task <task-id>
   NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>
+  codex-orchestrator doctor --format json
   codex-orchestrator doctor --usage --window-days 30
   codex-orchestrator rlm --multi-agent auto "<goal>"
   codex-orchestrator start implementation-gate --cloud --target <stage-id>
@@ -2223,7 +1386,9 @@ Notes:
   Review artifacts guide: docs/guides/review-artifacts.md
 `);
 }
-void main();
+if (isDirectExecution()) {
+    void runCodexOrchestratorCli();
+}
 function printVersion() {
     const pkg = loadPackageInfo();
     console.log(pkg.version ?? 'unknown');
@@ -2239,6 +1404,144 @@ Commands:
     --format json           Emit machine-readable output.
 `);
 }
+function printLinearHelp() {
+    console.log(`Usage: codex-orchestrator linear <subcommand> [options]
+
+Subcommands:
+  issue-context
+    --issue-id <id>       Linear issue id/key to inspect.
+    --workspace-id <id>   Optional workspace scope check (falls back to env when configured).
+    --team-id <id>        Optional team scope check (falls back to env when configured).
+    --project-id <id>     Optional project scope check (falls back to env when configured).
+    --format json         Emit machine-readable output.
+
+  upsert-workpad
+    --issue-id <id>       Linear issue id/key to update.
+    --body <text>         Workpad body to create/update. Local markdown image refs are uploaded to Linear.
+    --body-file <path>    Read workpad body from a file. Supports local image refs like file:///abs/proof.png or <file:///abs/proof (1).png>.
+    --comment-id <id>     Optional persisted workpad comment id.
+    --workspace-id <id>   Optional workspace scope check.
+    --team-id <id>        Optional team scope check.
+    --project-id <id>     Optional project scope check.
+    --format json         Emit machine-readable output.
+
+  delete-workpad
+    --issue-id <id>       Linear issue id/key whose workpad should be deleted.
+    --comment-id <id>     Optional persisted workpad comment id to delete.
+    --workspace-id <id>   Optional workspace scope check.
+    --team-id <id>        Optional team scope check.
+    --project-id <id>     Optional project scope check.
+    --format json         Emit machine-readable output.
+
+  transition
+    --issue-id <id>       Linear issue id/key to update.
+    --state <name>        Destination Linear state name (resolved to stateId via team workflow states).
+    --expected-state <name>
+                         Optional expected live state name; conflicts fail closed before mutation.
+    --expected-state-type <type>
+                         Optional expected live workflow type; conflicts fail closed before mutation.
+    --expected-updated-at <iso>
+                         Optional expected live updated_at timestamp; conflicts fail closed before mutation.
+    --force               Allow terminal-to-reopen transitions with an audited force reason.
+    --force-reason <text> Required whenever --force is set.
+    --workspace-id <id>   Optional workspace scope check.
+    --team-id <id>        Optional team scope check.
+    --project-id <id>     Optional project scope check.
+    --format json         Emit machine-readable output.
+
+  attach-pr
+    --issue-id <id>       Linear issue id/key to update.
+    --url <url>           GitHub PR URL to attach.
+    --title <title>       Optional attachment title.
+    --workspace-id <id>   Optional workspace scope check.
+    --team-id <id>        Optional team scope check.
+    --project-id <id>     Optional project scope check.
+    --format json         Emit machine-readable output.
+
+  parallelization
+    --issue-id <id>       Linear issue id/key for the active provider-worker turn.
+    --decision <mode>     parallelize_now, stay_serial, or forbid_parallel.
+    --reason <code>       Reason code allowed for the selected decision.
+    --summary <text>      Required operator summary. Include matrix/cap evidence.
+    Parallel-first rule: create a pre-turn decomposition matrix before the decision.
+    Matrix columns: candidate lane, file/phase scope, dependencies, overlap risk,
+      expected validation artifact, child-lane owner, and cap-slot use.
+    stay_serial is invalid while any safe independent child-lane candidate remains;
+      single_bounded_change must label docs/test/research/review slice justifications.
+    Child-lane cap: at most 2 active, pending, or unaccepted same-issue child lanes.
+      On cap exhaustion, use stay_serial/existing_child_lane_active and include cap_exhausted: evidence.
+      Stale in-flight accept claims older than 30 minutes, or legacy claims without timestamps, are recoverable and do not consume cap.
+    Parent ownership: avoid delegated files/phases while a child lane is active; collisions
+      require invalidate/reject/rebase reasoning before child patch acceptance.
+    --format json         Emit machine-readable output.
+
+  create-follow-up
+    --issue-id <id>                   Source Linear issue id/key.
+    --title <title>                   Follow-up issue title.
+    --description <text>              Follow-up issue description.
+    --description-file <path>         Read follow-up issue description from a file.
+    --intent-checksum <text>          Exact wording, protected terms, and wrong interpretations to reject.
+    --intent-checksum-file <path>     Read the intent checksum from a file.
+    --non-goals <text>                Explicit follow-up non-goals.
+    --non-goals-file <path>           Read follow-up non-goals from a file.
+    --not-done-if <text>              Readiness blockers / false-done conditions.
+    --not-done-if-file <path>         Read the false-done block from a file.
+    --acceptance-criteria <text>      Follow-up acceptance criteria.
+    --acceptance-criteria-file <path> Read follow-up acceptance criteria from a file.
+    --parity-lane                     Require a parity/alignment matrix for this follow-up.
+    --parity-matrix <text>            Current/reference/target matrix (required when --parity-lane is set).
+    --parity-matrix-file <path>       Read the parity/alignment matrix from a file (required when --parity-lane is set).
+    --canonical-owner-key <text>      Exact canonical owner key for reuse before creating a new issue.
+    --canonical-owner-key-file <path> Read the canonical owner key from a file.
+    --blocked-by-source               Add blocker linkage when the follow-up depends on the source issue.
+    --workspace-id <id>               Optional workspace scope check.
+    --team-id <id>                    Optional team scope check.
+    --project-id <id>                 Optional project scope check.
+    --format json                     Emit machine-readable output.
+
+  runtime-proof
+    --issue-id <id>       Linear issue id/key for audit continuity.
+    --origin <url>        App origin whose permit posture should be evaluated.
+    --kind <mode>         Optional proof kind: screenshot, external-link, or video.
+    --proof-url <url>     Reviewer-usable proof URL for workpad/PR handoff generation.
+    --title <title>       Optional proof label (defaults by kind).
+    --summary <text>      Optional short proof summary for workpad/PR handoff text.
+    --reachability-mode <mode>
+                         Optional reviewer reachability mode: deterministic (default) or dns-public.
+    --workspace-id <id>   Optional workspace scope check.
+    --team-id <id>        Optional team scope check.
+    --project-id <id>     Optional project scope check.
+    --format json         Emit machine-readable output.
+
+  screenshot-proof
+    --issue-id <id>       Linear issue id/key for audit continuity.
+    --output <path>       Optional local screenshot path (.png/.jpg/.jpeg). Defaults under .tmp/.
+    --display-id <id>     Optional macOS display id for bounded display capture.
+    --window-id <id>      Optional macOS window id for bounded window capture.
+    --open-preview        Open the captured file in Preview and attempt bounded AppleScript cleanup.
+    --workspace-id <id>   Optional workspace scope check.
+    --team-id <id>        Optional team scope check.
+    --project-id <id>     Optional project scope check.
+    --format json         Emit machine-readable output.
+
+  child-stream
+    --pipeline <id>       Allowlisted child pipeline: docs-review, implementation-gate, or docs-relevance-advisory.
+    --stream <name>       Optional task-id suffix for the child stream (defaults to the pipeline id).
+    --format json         Emit machine-readable output.
+
+  child-lane
+    --action <mode>       launch, accept, reject, or invalidate.
+    --stream <name>       Lane stream name / task-id suffix.
+    --purpose <text>      Required for launch: bounded lane objective.
+    --files <csv>         Optional comma-separated file ownership scope.
+    --phases <csv>        Optional comma-separated phase ownership scope.
+    --instructions <text> Optional extra bounded instructions for launch.
+    --instructions-file <path>
+                         Optional file containing extra bounded instructions for launch.
+    --reason <text>       Optional parent decision rationale for accept/reject/invalidate.
+    --format json         Emit machine-readable output.
+`);
+}
 function printCodexHelp() {
     console.log(`Usage: codex-orchestrator codex <subcommand> [options]
 
@@ -2268,6 +1571,158 @@ Options:
   --format json      Emit machine-readable status output.
 `);
 }
+function printControlHostHelp() {
+    console.log(`Usage:
+  codex-orchestrator control-host [options]
+  codex-orchestrator control-host freshness-gauge [options]
+  codex-orchestrator control-host supervise <install|status|restart|uninstall|run> [options]
+
+Options:
+  --task <id>           Artifact task id for the host state (default: local-mcp).
+  --run <id>            Host run id for persisted state files (default: control-host).
+  --pipeline <id>       Pipeline used for provider-driven starts (default: ${DEFAULT_PROVIDER_START_PIPELINE_ID}).
+  --format json         Emit the startup readiness payload to stdout, then keep the host running.
+  --help                Show this message.
+
+Read-only gauge subcommand:
+  freshness-gauge      Replay existing local/sanitized artifacts and classify provider/control-host freshness.
+
+Supervision subcommands:
+  supervise install     Install a launchd LaunchAgent-backed local control-host supervisor.
+  supervise status      Show the installed launchd/config/state status.
+  supervise restart     Restart the installed control-host supervisor.
+  supervise uninstall   Remove the installed launchd supervisor and generated artifacts.
+  supervise run         Internal long-lived runner for launchd ProgramArguments.
+`);
+}
+function printControlHostFreshnessGaugeHelp() {
+    console.log(`Usage: codex-orchestrator control-host freshness-gauge [options]
+
+Replay existing provider/control-host artifacts without starting a host or polling Linear/GitHub.
+
+Options:
+  --artifact-root <path>        Directory to scan for local artifacts (required unless explicit paths are provided).
+  --run-dir <path>              Alias for --artifact-root when checking one run directory.
+  --provider-intake-state <csv> Explicit provider-intake-state.json path(s).
+  --provider-manifest <csv>     Explicit manifest.json path(s).
+  --provider-proof <csv>        Explicit provider-linear-worker-proof.json path(s).
+  --worker-audit-jsonl <csv>    Explicit provider worker audit JSONL path(s).
+  --control-endpoint-metadata <csv> Explicit control endpoint metadata path(s).
+  --status-dataset <csv>        Explicit CO STATUS/status dataset path(s).
+  --polling-health <csv>        Explicit provider polling health path(s).
+  --linear-budget-state <csv>   Explicit Linear shared-budget state path(s).
+  --now <iso>                   Deterministic reference time for age/latency calculations.
+  --strict                      Exit non-zero when the verdict is stale or contradictory.
+  --max-depth <n>               Recursive artifact scan depth (default: 8).
+  --stale-refresh-after-ms <n>  Refresh age threshold (default: 300000).
+  --stale-heartbeat-after-ms <n> Active heartbeat age threshold (default: 600000).
+  --stale-retry-after-ms <n>    Retry/backoff overdue threshold (default: 600000).
+  --stale-claim-queue-after-ms <n> Claim queue age threshold (default: 1800000).
+  --claim-to-start-degraded-after-ms <n> Claim-to-start degraded threshold (default: 300000).
+  --start-to-heartbeat-degraded-after-ms <n> Start-to-first-heartbeat degraded threshold (default: 120000).
+  --linear-headroom-low-ratio <n> Low Linear shared-budget remaining ratio (default: 0.05).
+  --child-lane-cap <n>          Same-parent active/pending child-lane cap (default: 2).
+  --format json                 Emit machine-readable gauge output.
+  --help                        Show this message.
+`);
+}
+function printControlHostSupervisionHelp() {
+    console.log(`Usage: codex-orchestrator control-host supervise <install|status|restart|uninstall|run> [options]
+
+Subcommands:
+  install               Install the macOS launchd LaunchAgent plus generated config/state files.
+  status                Show the current install, launchctl, and restart-reason state.
+  restart               Kickstart the installed launchd service.
+  uninstall             Boot out the launchd service and remove generated artifacts.
+  run                   Internal long-lived supervision runner for launchd use.
+
+Common options:
+  --label <value>             LaunchAgent label (default: com.kbediako.co.control-host).
+  --config <path>             Explicit config path for status, restart, uninstall, or run.
+  --format json               Emit machine-readable output for install, status, restart, or uninstall.
+
+Install options:
+  --repo-root <path>          Repo root used as the supervised control-host working directory.
+  --node <path>               Explicit Node executable for launchd ProgramArguments.
+  --cli-entrypoint <path>     Explicit codex-orchestrator JS entrypoint for launchd ProgramArguments.
+  --task <id>                 Control-host task id (default: local-mcp).
+  --run <id>                  Control-host run id (default: control-host).
+  --pipeline <id>             Provider start pipeline (default: provider-linear-worker).
+  --health-interval <sec>     Health poll interval in seconds (default: 30).
+  --unhealthy-threshold <n>   Consecutive unhealthy samples before launchd restart (default: 3).
+  --launchd-throttle <sec>    LaunchAgent ThrottleInterval value (default: 15).
+  --kill-timeout <sec>        Grace period before force-killing the child host (default: 10).
+  --env-files <csv|none>      Comma-separated env/bootstrap files to source before launch.
+  --shell <path>              Shell used to source env/bootstrap files (default: $SHELL or /bin/zsh).
+`);
+}
+function printCoStatusHelp() {
+    console.log(`Usage:
+  codex-orchestrator co-status [options]
+  codex-orchestrator co-status attach [options]
+  codex-orchestrator co-status operator-autopilot local-rollout <acknowledge|clear|dismiss> [options]
+
+Attach the CO STATUS terminal viewer to an already-running local JSON control-host,
+or emit the current CO STATUS snapshot from that host in JSON mode.
+
+Viewer options:
+  --task <id>           Artifact task id for the host state (default: local-mcp).
+  --run <id>            Host run id for persisted state files (default: control-host).
+  --format json         Emit the current CO STATUS snapshot from the local control-host and exit.
+  --help                Show this message.
+
+JSON contract:
+  co-status --format json reads the authenticated operator-dashboard snapshot from the
+  current local control-host and exits. Use \`control-host --format json\` for startup readiness output.
+
+Attach subcommand:
+  attach                Attach to an already-running local JSON control-host.
+                        Run \`codex-orchestrator co-status attach --help\` for attach flags.
+
+Operator autopilot lifecycle:
+  operator-autopilot    Acknowledge, clear, or dismiss a pending local rollout action.
+                        Run \`codex-orchestrator co-status operator-autopilot --help\` for lifecycle flags.
+`);
+}
+function printCoStatusOperatorAutopilotHelp() {
+    console.log(`Usage: codex-orchestrator co-status operator-autopilot local-rollout <acknowledge|clear|dismiss> [options]
+
+Record durable lifecycle metadata for one pending operator-autopilot local rollout
+action from an already-running local JSON control-host.
+
+Options:
+  --issue <id|identifier>   Pending Linear issue id or identifier to match.
+  --action-id <id>          Stable local rollout action instance id to match.
+  --actor <name>            Operator recording the lifecycle event (default: current user).
+  --reason <text>           Required reason for the lifecycle event.
+  --task <id>               Artifact task id for the host state (default: local-mcp).
+  --run <id>                Host run id for persisted state files (default: control-host).
+  --run-dir <path>          Resolve the host from a specific existing run directory.
+  --manifest-path <path>    Resolve the host from an explicit manifest.json path.
+  --format json             Emit machine-readable lifecycle output.
+  --help                    Show this message.
+`);
+}
+function printCoStatusAttachHelp() {
+    console.log(`Usage: codex-orchestrator co-status attach [options]
+
+Attach a read-only CO STATUS viewer to an already-running local JSON control-host.
+This reads persisted endpoint/auth artifacts and does not start another control-host,
+Linear poller, or Telegram poller.
+If the supervised control-host restarts and rotates control_endpoint.json while
+attached, the viewer re-resolves the endpoint on fetch failures and reports
+stale endpoint, unavailable host, auth, and timeout guidance in the dashboard.
+
+Options:
+  --task <id>               Artifact task id for the host state (default: local-mcp).
+  --run <id>                Host run id for persisted state files (default: control-host).
+  --run-dir <path>          Resolve the host from a specific existing run directory.
+  --manifest-path <path>    Resolve the host from an explicit manifest.json path.
+  --refresh-interval-ms <n> Viewer refresh interval in milliseconds (default: 1000).
+  --format json             Emit machine-readable attach target output instead of launching the viewer.
+  --help                    Show this message.
+`);
+}
 function printResumeHelp() {
     console.log(`Usage: codex-orchestrator resume --run <id> [options]
 
@@ -2284,12 +1739,43 @@ Options:
   --no-interactive      Force disable HUD.
 `);
 }
+function printDoctorHelp() {
+    console.log(`Usage: codex-orchestrator doctor [options]
+
+Inspect the current repo/user environment for downstream readiness:
+- packaged and seeded provider onboarding files
+- DevTools + delegation MCP wiring
+- Codex defaults and current CLI posture
+- optional local usage and cloud preflight checks
+
+Options:
+  --format json         Emit machine-readable output (not supported with --apply).
+  --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.
+  --cloud-preflight     Run cloud readiness preflight checks (env/codex/git/branch).
+  --cloud-env-id <id>   Override env id for --cloud-preflight (default: CODEX_CLOUD_ENV_ID).
+  --cloud-branch <name> Override branch for --cloud-preflight (default: CODEX_CLOUD_BRANCH).
+  --issue-log           Append markdown issue entry + JSON bundle for downstream triage.
+  --issue-title <text>  Optional title for --issue-log entries.
+  --issue-notes <text>  Optional notes for --issue-log entries.
+  --issue-log-path <p>  Output markdown path (default: docs/codex-orchestrator-issues.md).
+  --apply               Plan/apply quick fixes for DevTools + delegation wiring (use with --yes).
+  --yes                 Apply fixes when --apply is set.
+  --help                Show this message.
+
+Examples:
+  codex-orchestrator doctor --format json
+  codex-orchestrator doctor --usage --window-days 30
+  codex-orchestrator doctor --cloud-preflight --cloud-env-id <env-id> --cloud-branch main
+`);
+}
 function printDelegationServerHelp() {
     console.log(`Usage: codex-orchestrator delegate-server [options]
 
 Options:
   --repo <path>                    Repo root for config + manifests (default cwd).
-  --mode <full|question_only>      Limit tool surface for child runs.
+  --mode <full|question_only|status_only>      Limit tool surface for child runs.
   --config "<key>=<value>[;...]"   Apply config overrides.
   --help                           Show this message.
 `);
@@ -2316,17 +1802,144 @@ Subcommands:
                           Supports PR_MONITOR_* env vars and standard flags (see: pr watch-merge --help).
   resolve-merge           Watch for merge readiness but exit early on actionable feedback requiring author response.
                           Inherits watch-merge flags; defaults exit-on-action-required to on.
+  ready-review           Wait through a bounded automated-feedback drain before review handoff.
+                          Reuses watch-merge polling, treats REVIEW_REQUIRED as informational, and defaults exit-on-action-required to on.
 
 Examples:
   codex-orchestrator pr watch-merge --pr 211 --dry-run --quiet-minutes 10
   codex-orchestrator pr watch-merge --pr 211 --auto-merge --merge-method squash
   codex-orchestrator pr resolve-merge --pr 211 --quiet-minutes 15
   codex-orchestrator pr resolve-merge --pr 211 --auto-merge --quiet-minutes 10
+  codex-orchestrator pr ready-review --pr 211 --quiet-minutes 15 --timeout-minutes 20
 
 Guide:
   Review artifacts (prompt + output log paths): docs/guides/review-artifacts.md
 `);
 }
+function isCliHelpToken(value) {
+    return value === '--help' || value === '-h' || value === 'help';
+}
+function envFlagEnabled(value, fallback = false) {
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return fallback;
+    }
+    if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+        return true;
+    }
+    if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+        return false;
+    }
+    return fallback;
+}
+function isPrHelpSubcommand(value) {
+    return value === 'watch-merge' || value === 'resolve-merge' || value === 'ready-review';
+}
+function shouldPrintPrSubcommandHelp(args) {
+    if (args.length === 0) {
+        return false;
+    }
+    if (args[0] === 'help') {
+        return true;
+    }
+    return args.some((arg) => arg === '--help' || arg === '-h');
+}
+function printPrSubcommandHelp(subcommand) {
+    const defaultAutoMerge = envFlagEnabled(process.env.PR_MONITOR_AUTO_MERGE, false);
+    switch (subcommand) {
+        case 'watch-merge':
+            console.log(`Usage: codex-orchestrator pr watch-merge [options]
+
+Monitor PR checks/reviews with polling and optionally merge after a quiet window.
+
+Options:
+  --pr <number>             PR number (default: PR for current branch)
+  --owner <name>            Repo owner (default: inferred via gh repo view)
+  --repo <name>             Repo name (default: inferred via gh repo view)
+  --interval-seconds <n>    Poll interval in seconds (default: 30)
+  --quiet-minutes <n>       Required quiet window after ready state (default: 15)
+  --timeout-minutes <n>     Max monitor duration before failing (default: 180)
+  --merge-method <method>   merge|squash|rebase (default: squash)
+  --auto-merge              Merge automatically after quiet window
+  --no-auto-merge           Never merge automatically (monitor only)
+  --delete-branch           Delete remote branch when merging
+  --no-delete-branch        Keep remote branch after merge
+  --exit-on-action-required Exit non-zero when author action is required
+  --no-exit-on-action-required Keep monitoring even when author action is required
+  --dry-run                 Never call gh pr merge (report only)
+  -h, --help                Show this help message
+
+Environment:
+  PR_MONITOR_QUIET_MINUTES=<n>  Override quiet window default
+  PR_MONITOR_INTERVAL_SECONDS=<n>
+  PR_MONITOR_TIMEOUT_MINUTES=<n>
+  PR_MONITOR_AUTO_MERGE=1       Default auto-merge on (current default: ${defaultAutoMerge ? 'on' : 'off'})
+  PR_MONITOR_DELETE_BRANCH=1    Default delete branch on merge
+  PR_MONITOR_MERGE_METHOD=<method>
+`);
+            return;
+        case 'resolve-merge':
+            console.log(`Usage: codex-orchestrator pr resolve-merge [options]
+
+Monitor until merge-ready or actionable feedback appears; exits early when author action is required.
+
+Options:
+  --pr <number>             PR number (default: PR for current branch)
+  --owner <name>            Repo owner (default: inferred via gh repo view)
+  --repo <name>             Repo name (default: inferred via gh repo view)
+  --interval-seconds <n>    Poll interval in seconds (default: 30)
+  --quiet-minutes <n>       Required quiet window after ready state (default: 15)
+  --timeout-minutes <n>     Max monitor duration before failing (default: 180)
+  --merge-method <method>   merge|squash|rebase (default: squash)
+  --auto-merge              Merge automatically after quiet window
+  --no-auto-merge           Never merge automatically (monitor only)
+  --delete-branch           Delete remote branch when merging
+  --no-delete-branch        Keep remote branch after merge
+  --exit-on-action-required Exit non-zero when author action is required
+  --no-exit-on-action-required Keep monitoring even when author action is required
+  --dry-run                 Never call gh pr merge (report only)
+  -h, --help                Show this help message
+
+Environment:
+  PR_MONITOR_QUIET_MINUTES=<n>  Override quiet window default
+  PR_MONITOR_INTERVAL_SECONDS=<n>
+  PR_MONITOR_TIMEOUT_MINUTES=<n>
+  PR_MONITOR_AUTO_MERGE=1       Default auto-merge on (current default: ${defaultAutoMerge ? 'on' : 'off'})
+  PR_MONITOR_DELETE_BRANCH=1    Default delete branch on merge
+  PR_MONITOR_MERGE_METHOD=<method>
+  resolve-merge default: exit-on-action-required is on
+`);
+            return;
+        case 'ready-review':
+            console.log(`Usage: codex-orchestrator pr ready-review [options]
+
+Monitor PR checks/reviews with polling and report when review handoff is safe after a bounded automated-feedback drain.
+
+Options:
+  --pr <number>             PR number (default: PR for current branch)
+  --owner <name>            Repo owner (default: inferred via gh repo view)
+  --repo <name>             Repo name (default: inferred via gh repo view)
+  --interval-seconds <n>    Poll interval in seconds (default: 30)
+  --quiet-minutes <n>       Required quiet window after ready state (default: 15)
+  --timeout-minutes <n>     Max monitor duration before failing (default: 180)
+  --exit-on-action-required Exit non-zero when author action is required
+  --no-exit-on-action-required Keep monitoring even when author action is required
+  --dry-run                 Never call gh pr merge (report only)
+  -h, --help                Show this help message
+
+Environment:
+  PR_MONITOR_QUIET_MINUTES=<n>  Override quiet window default
+  PR_MONITOR_INTERVAL_SECONDS=<n>
+  PR_MONITOR_TIMEOUT_MINUTES=<n>
+  ready-review default: exit-on-action-required is on
+  ready-review treats REVIEW_REQUIRED as informational; CHANGES_REQUESTED and actionable machine feedback still block handoff.
+`);
+            return;
+    }
+}
 function printRlmHelp() {
     console.log(`Usage: codex-orchestrator rlm "<goal>" [options]
 
@@ -2356,6 +1969,29 @@ Tips:
   - Ensure multi-agent is enabled in Codex: codex features enable multi_agent (legacy alias: collab).
 `);
 }
+function printFrontendTestHelp() {
+    console.log(`Usage: codex-orchestrator frontend-test [options]
+
+Runs the frontend-testing pipeline.
+
+Options:
+  --devtools              Enable Chrome DevTools MCP for this run.
+  --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+  --runtime-mode <cli|appserver>  Force runtime mode for this run.
+  --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
+  --parent-run <id>       Link run to parent run id.
+  --approval-policy <p>   Record approval policy metadata.
+  --format json           Emit machine-readable output.
+  --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
+  --interactive | --ui    Enable read-only HUD when running in a TTY.
+  --no-interactive        Force disable HUD.
+  --help                  Show this message.
+
+Examples:
+  codex-orchestrator frontend-test
+  codex-orchestrator frontend-test --devtools --format json
+`);
+}
 function printFlowHelp() {
     console.log(`Usage: codex-orchestrator flow [options]
 
@@ -2393,6 +2029,7 @@ Common options:
   --manifest <path>                Explicit manifest path for review evidence.
   --runs-dir <path>                Root runs directory when auto-resolving manifest.
   --task <id>                      Task id used for prompt context.
+  --surface <diff|audit|architecture>  Select review surface (default: diff).
   --uncommitted                    Review uncommitted diff scope.
   --base <branch>                  Review against a base branch.
   --commit <sha>                   Review a specific commit.
@@ -2425,6 +2062,10 @@ Options:
   --task <id>               Override task identifier.
   --parent-run <id>         Link run to parent run id.
   --approval-policy <p>     Record approval policy metadata.
+  --issue-provider <name>   Persist provider identity for autonomous intake handoff.
+  --issue-id <id>           Persist provider issue id on the run manifest.
+  --issue-identifier <id>   Persist human issue identifier on the run manifest.
+  --issue-updated-at <iso>  Persist provider issue updated timestamp on the run manifest.
   --format json             Emit machine-readable output.
   --execution-mode <mcp|cloud>  Force execution mode for this run.
   --cloud                   Shortcut for --execution-mode cloud.