@kbediako/codex-orchestrator 0.1.33 → 0.1.34

package/dist/bin/codex-orchestrator.js

@@ -15,6 +15,7 @@ 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 { 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 { formatDelegationSetupSummary, runDelegationSetup } from '../orchestrator/src/cli/delegationSetup.js';
@@ -25,6 +26,9 @@ 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 { 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);
     const command = args.shift();
@@ -117,6 +121,7 @@ function parseArgs(raw) {
     const queue = [...raw];
     const booleanFlagKeys = new Set([
         'apply',
+        'auto-issue-log',
         'cloud',
         'cloud-preflight',
         'codex-cli',
@@ -127,8 +132,10 @@ function parseArgs(raw) {
         'force',
         'help',
         'interactive',
+        'issue-log',
         'multi-agent',
         'no-interactive',
+        'repo-config-required',
         'refresh-skills',
         'ui',
         'usage',
@@ -327,6 +334,41 @@ function readStringFlag(flags, key) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function parseBooleanSetting(raw, label) {
+    if (typeof raw === 'boolean') {
+        return raw;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+        return true;
+    }
+    if (['0', 'false', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    throw new Error(`Invalid ${label} value "${raw}". Expected true|false.`);
+}
+function resolveBooleanOption(flags, key, envKey) {
+    const fromFlag = flags[key];
+    if (fromFlag !== undefined) {
+        return parseBooleanSetting(fromFlag, `--${key}`);
+    }
+    if (!envKey) {
+        return false;
+    }
+    const fromEnv = process.env[envKey];
+    if (typeof fromEnv !== 'string' || fromEnv.trim().length === 0) {
+        return false;
+    }
+    return parseBooleanSetting(fromEnv, envKey);
+}
+function applyRepoConfigRequiredPolicy(flags) {
+    const required = resolveBooleanOption(flags, 'repo-config-required', REPO_CONFIG_REQUIRED_ENV_KEY);
+    process.env[REPO_CONFIG_REQUIRED_ENV_KEY] = required ? '1' : '0';
+    return required;
+}
+function resolveAutoIssueLogEnabled(flags) {
+    return resolveBooleanOption(flags, 'auto-issue-log', AUTO_ISSUE_LOG_ENV_KEY);
+}
 function resolveExecutionModeFlag(flags) {
     const cloudShortcut = flags['cloud'] === true;
     const rawMode = readStringFlag(flags, 'execution-mode');
@@ -474,11 +516,66 @@ async function readRlmState(statePath) {
         return null;
     }
 }
+async function maybeCaptureAutoIssueLog(params) {
+    if (!params.enabled) {
+        return { issueLog: null, issueLogError: null };
+    }
+    try {
+        const issueLog = await writeDoctorIssueLog({
+            doctor: runDoctor(),
+            issueTitle: params.issueTitle,
+            issueNotes: params.issueNotes,
+            taskFilter: params.taskFilter
+        });
+        return { issueLog, issueLogError: null };
+    }
+    catch (error) {
+        const issueLogError = error?.message ?? String(error);
+        return { issueLog: null, issueLogError };
+    }
+}
+function withAutoIssueLogContext(error, capture) {
+    const baseMessage = error?.message ?? String(error);
+    const lines = [baseMessage];
+    if (capture.issueLog) {
+        lines.push(`Auto issue log: saved to ${capture.issueLog.issue_log_path} (bundle: ${capture.issueLog.bundle_path}).`);
+    }
+    if (capture.issueLogError) {
+        lines.push(`Auto issue log: failed (${capture.issueLogError})`);
+    }
+    return new Error(lines.join('\n'));
+}
+function resolveTaskFilter(preferredTaskId, taskIdOverride) {
+    const preferred = preferredTaskId?.trim();
+    if (preferred) {
+        return preferred;
+    }
+    const taskOverride = taskIdOverride?.trim();
+    if (taskOverride) {
+        return taskOverride;
+    }
+    const mcpTask = process.env.MCP_RUNNER_TASK_ID?.trim();
+    if (mcpTask) {
+        return mcpTask;
+    }
+    const taskEnv = process.env.TASK?.trim();
+    if (taskEnv) {
+        return taskEnv;
+    }
+    const codexTask = process.env.CODEX_ORCHESTRATOR_TASK_ID?.trim();
+    return codexTask && codexTask.length > 0 ? codexTask : null;
+}
 async function handleStart(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printStartHelp();
+        return;
+    }
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const executionMode = resolveExecutionModeFlag(flags);
+    applyRepoConfigRequiredPolicy(flags);
+    const autoIssueLogEnabled = resolveAutoIssueLogEnabled(flags);
     if (pipelineId === 'rlm') {
         const goal = readStringFlag(flags, 'goal');
         const warnLegacyEnvAlias = shouldWarnLegacyMultiAgentEnv(flags, process.env);
@@ -487,31 +584,51 @@ async function handleStart(orchestrator, rawArgs) {
             console.warn('Warning: RLM_SYMBOLIC_COLLAB is a legacy alias; prefer RLM_SYMBOLIC_MULTI_AGENT.');
         }
     }
-    await withRunUi(flags, format, async (runEvents) => {
-        let taskIdOverride = typeof flags['task'] === 'string' ? flags['task'] : undefined;
-        if (pipelineId === 'rlm') {
-            taskIdOverride = resolveRlmTaskId(taskIdOverride);
-            process.env.MCP_RUNNER_TASK_ID = taskIdOverride;
-            if (format !== 'json') {
-                console.log(`Task: ${taskIdOverride}`);
+    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,
-            runEvents
+            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,
+                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);
         });
-        emitRunOutput(result, format, 'Run started');
-    });
+    }
+    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']);
+    applyRepoConfigRequiredPolicy(flags);
     if (positionals.length > 0) {
         console.error(`[frontend-test] ignoring extra arguments: ${positionals.join(' ')}`);
     }
@@ -554,75 +671,127 @@ async function handleFlow(orchestrator, rawArgs) {
     }
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const executionMode = resolveExecutionModeFlag(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);
-    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,
-            runEvents
-        });
-        const docsPayload = toRunOutputPayload(docsReviewResult);
-        if (format === 'text') {
-            emitRunOutput(docsReviewResult, format, 'Docs-review run');
-        }
-        if (docsReviewResult.manifest.status !== 'succeeded') {
-            process.exitCode = 1;
+    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,
+                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,
+                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: docsReviewResult.manifest.status,
-                    failed_stage: 'docs-review',
+                    status: implementationGateResult.manifest.status,
+                    failed_stage: implementationGateResult.manifest.status === 'succeeded' ? null : 'implementation-gate',
                     docs_review: docsPayload,
-                    implementation_gate: null
+                    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;
             }
-            else {
-                console.log('Flow halted: docs-review failed.');
-            }
-            return;
-        }
-        const implementationGateResult = await orchestrator.start({
-            pipelineId: 'implementation-gate',
-            taskId,
-            parentRunId: docsReviewResult.manifest.run_id,
-            approvalPolicy,
-            targetStageId: implementationGateTargetStageId,
-            executionMode,
-            runEvents
-        });
-        const implementationPayload = toRunOutputPayload(implementationGateResult);
-        if (format === 'json') {
-            const payload = {
-                status: implementationGateResult.manifest.status,
-                failed_stage: implementationGateResult.manifest.status === 'succeeded' ? null : 'implementation-gate',
-                docs_review: docsPayload,
-                implementation_gate: implementationPayload
-            };
-            console.log(JSON.stringify(payload, null, 2));
+            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;
             }
-            return;
-        }
-        emitRunOutput(implementationGateResult, format, 'Implementation-gate run');
-        if (implementationGateResult.manifest.status !== 'succeeded') {
-            process.exitCode = 1;
-            console.log('Flow halted: implementation-gate failed.');
-            return;
-        }
-        console.log('Flow complete: docs-review -> implementation-gate.');
-    });
+            console.log('Flow complete: docs-review -> implementation-gate.');
+        });
+    }
+    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);
+    }
 }
 async function handlePlan(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printPlanHelp();
+        return;
+    }
+    applyRepoConfigRequiredPolicy(flags);
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const result = await orchestrator.plan({
@@ -642,6 +811,7 @@ async function handleRlm(orchestrator, rawArgs) {
         printRlmHelp();
         return;
     }
+    applyRepoConfigRequiredPolicy(flags);
     const goalFromArgs = positionals.length > 0 ? positionals.join(' ') : undefined;
     const goal = goalFromArgs ?? readStringFlag(flags, 'goal') ?? process.env.RLM_GOAL?.trim();
     if (!goal) {
@@ -704,6 +874,7 @@ async function handleResume(orchestrator, rawArgs) {
         printResumeHelp();
         return;
     }
+    applyRepoConfigRequiredPolicy(flags);
     const runId = (flags['run'] ?? positionals[0]);
     if (!runId) {
         throw new Error('resume requires --run <run-id>.');
@@ -778,8 +949,8 @@ async function withRunUi(flags, format, action) {
         runEvents.dispose();
     }
 }
-function emitRunOutput(result, format, label) {
-    const payload = toRunOutputPayload(result);
+function emitRunOutput(result, format, label, issueLogCapture = { issueLog: null, issueLogError: null }) {
+    const payload = toRunOutputPayload(result, issueLogCapture);
     if (format === 'json') {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -797,8 +968,16 @@ function emitRunOutput(result, format, label) {
             console.log(`  ${line}`);
         }
     }
+    if (payload.issue_log) {
+        for (const line of formatDoctorIssueLogSummary(payload.issue_log)) {
+            console.log(line);
+        }
+    }
+    if (payload.issue_log_error) {
+        console.log(`Auto issue log: failed (${payload.issue_log_error})`);
+    }
 }
-function toRunOutputPayload(result) {
+function toRunOutputPayload(result, issueLogCapture = { issueLog: null, issueLogError: null }) {
     return {
         run_id: result.manifest.run_id,
         status: result.manifest.status,
@@ -806,7 +985,9 @@ function toRunOutputPayload(result) {
         manifest: `${result.manifest.artifact_root}/manifest.json`,
         log_path: result.manifest.log_path,
         summary: result.manifest.summary ?? null,
-        cloud_fallback_reason: result.manifest.cloud_fallback?.reason ?? null
+        cloud_fallback_reason: result.manifest.cloud_fallback?.reason ?? null,
+        issue_log: issueLogCapture.issueLog,
+        issue_log_error: issueLogCapture.issueLogError
     };
 }
 async function handleExec(rawArgs) {
@@ -907,6 +1088,10 @@ async function handleSelfCheck(rawArgs) {
 }
 async function handleInit(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printInitHelp();
+        return;
+    }
     const template = positionals[0];
     if (!template) {
         throw new Error('init requires a template name (e.g. init codex).');
@@ -965,8 +1150,9 @@ Options:
     }
     const repoFlag = readStringFlag(flags, 'repo');
     const repoRoot = repoFlag ?? process.cwd();
-    const repoFlagValue = repoFlag ? (/\s/u.test(repoFlag) ? JSON.stringify(repoFlag) : repoFlag) : null;
-    const delegationRepoArg = repoFlagValue ? ` --repo ${repoFlagValue}` : '';
+    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.');
@@ -1000,7 +1186,7 @@ Options:
         for (const commandLine of payload.steps.skills.commandLines) {
             console.log(`  - ${commandLine}`);
         }
-        console.log(`- Delegation: codex-orchestrator delegation setup --yes${delegationRepoArg}`);
+        console.log(`- Delegation: ${delegationCommandPreview}`);
         console.log('- DevTools: codex-orchestrator devtools setup --yes');
         for (const line of formatSetupGuidanceSummary(guidance)) {
             console.log(line);
@@ -1063,11 +1249,18 @@ async function handleDoctor(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') {
@@ -1096,6 +1289,17 @@ async function handleDoctor(rawArgs) {
             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) {
@@ -1104,6 +1308,9 @@ async function handleDoctor(rawArgs) {
         if (cloudPreflightResult) {
             payload.cloud_preflight = cloudPreflightResult;
         }
+        if (issueLogResult) {
+            payload.issue_log = issueLogResult;
+        }
         console.log(JSON.stringify(payload, null, 2));
         return;
     }
@@ -1120,6 +1327,11 @@ async function handleDoctor(rawArgs) {
             console.log(line);
         }
     }
+    if (issueLogResult) {
+        for (const line of formatDoctorIssueLogSummary(issueLogResult)) {
+            console.log(line);
+        }
+    }
     if (!wantsApply) {
         return;
     }
@@ -1672,6 +1884,8 @@ Commands:
     --execution-mode <mcp|cloud>  Force execution mode for this run and child subpipelines.
     --cloud                 Shortcut for --execution-mode cloud.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
+    --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
+    --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --goal "<goal>"         When pipeline is rlm, set the RLM goal.
     --multi-agent [auto|true|false]  Preferred alias for multi-agent collab subagents (implies symbolic mode).
     --collab [auto|true|false]  Legacy alias for --multi-agent.
@@ -1684,6 +1898,7 @@ Commands:
 
   rlm "<goal>"              Run RLM loop until validator passes.
     --task <id>             Override task identifier.
+    --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --multi-agent [auto|true|false]  Preferred alias for multi-agent collab subagents (implies symbolic mode).
     --collab [auto|true|false]  Legacy alias for --multi-agent.
     --validator <cmd|none>  Set validator command or disable validation.
@@ -1698,6 +1913,7 @@ Commands:
   frontend-test             Run frontend testing pipeline.
     --devtools             Enable Chrome DevTools MCP for this run.
     --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+    --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.
@@ -1713,6 +1929,8 @@ Commands:
     --execution-mode <mcp|cloud>  Force execution mode for both runs.
     --cloud                 Shortcut for --execution-mode cloud.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
+    --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
+    --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
@@ -1720,6 +1938,7 @@ Commands:
     --task <id>             Override task identifier.
     --format json           Emit machine-readable output.
     --target <stage-id>     Highlight the stage chosen for orchestration (alias: --target-stage).
+    --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
 
   exec [command]            Run a one-off command with unified exec runtime.
     --json [compact]        Emit final JSON summary (optional compact mode).
@@ -1734,6 +1953,7 @@ Commands:
     --actor <name>          Record who resumed the run.
     --reason <text>         Record why the run was resumed.
     --target <stage-id>     Override stage selection before resuming (alias: --target-stage).
+    --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
     --format json           Emit machine-readable output.
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
@@ -1742,6 +1962,7 @@ Commands:
 
   self-check [--format json]
   init codex [--cwd <path>] [--force]
+    Installs AGENTS.md, mcp-client.json, and codex.orchestrator.json.
     --codex-cli            Also run CO-managed Codex CLI setup (plan unless --yes; activate with CODEX_CLI_USE_MANAGED=1).
     --codex-source <path>  Build from local Codex repo (or git URL).
     --codex-ref <ref>      Git ref (branch/tag/sha) when building from repo.
@@ -1761,6 +1982,10 @@ Commands:
     --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.
     --format json         Emit machine-readable output (not supported with --apply).
@@ -1841,6 +2066,7 @@ Options:
   --actor <name>        Record who resumed the run.
   --reason <text>       Record why the run was resumed.
   --target <stage-id>   Override stage selection before resuming.
+  --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
   --format json         Emit machine-readable output.
   --interactive | --ui  Enable read-only HUD when running in a TTY.
   --no-interactive      Force disable HUD.
@@ -1891,6 +2117,7 @@ function printRlmHelp() {
 Options:
   --goal "<goal>"         Alternate way to set the goal (positional is preferred).
   --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+  --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
   --multi-agent [auto|true|false]  Preferred alias for multi-agent collab subagents (implies symbolic mode).
   --collab [auto|true|false]  Legacy alias for --multi-agent.
   --validator <cmd|none>  Set validator command or disable validation.
@@ -1925,7 +2152,67 @@ Options:
   --execution-mode <mcp|cloud>  Force execution mode for both runs.
   --cloud                   Shortcut for --execution-mode cloud.
   --target <stage-id>       Focus plan/build metadata (applies where the stage exists).
+  --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
+  --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
   --interactive | --ui      Enable read-only HUD when running in a TTY.
   --no-interactive          Force disable HUD.
 `);
 }
+function printStartHelp() {
+    console.log(`Usage: codex-orchestrator start [pipeline] [options]
+
+Start a new run. If no pipeline is provided, diagnostics is used.
+
+Options:
+  --task <id>               Override task identifier.
+  --parent-run <id>         Link run to parent run id.
+  --approval-policy <p>     Record approval policy metadata.
+  --format json             Emit machine-readable output.
+  --execution-mode <mcp|cloud>  Force execution mode for this run.
+  --cloud                   Shortcut for --execution-mode cloud.
+  --target <stage-id>       Focus plan/build metadata on a specific stage.
+  --auto-issue-log [true|false]  On failure, auto-write doctor issue bundle/log entry.
+  --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
+  --goal "<goal>"           When pipeline is rlm, set the RLM goal.
+  --multi-agent [auto|true|false]  Preferred alias for multi-agent collab subagents.
+  --collab [auto|true|false]  Legacy alias for --multi-agent.
+  --validator <cmd|none>    When pipeline is rlm, set validator command.
+  --max-iterations <n>      When pipeline is rlm, override max iterations.
+  --max-minutes <n>         When pipeline is rlm, override max minutes.
+  --roles <single|triad>    When pipeline is rlm, set role split.
+  --interactive | --ui      Enable read-only HUD when running in a TTY.
+  --no-interactive          Force disable HUD.
+`);
+}
+function printPlanHelp() {
+    console.log(`Usage: codex-orchestrator plan [pipeline] [options]
+
+Preview pipeline stages without executing.
+
+Options:
+  --task <id>               Override task identifier.
+  --format json             Emit machine-readable output.
+  --target <stage-id>       Highlight the stage chosen for orchestration.
+  --repo-config-required [true|false]  Require repo-local codex.orchestrator.json (no package fallback).
+`);
+}
+function printInitHelp() {
+    console.log(`Usage: codex-orchestrator init codex [options]
+
+Install starter templates into the target repository:
+- AGENTS.md
+- mcp-client.json
+- codex.orchestrator.json
+
+Options:
+  --cwd <path>              Target directory (default current directory).
+  --force                   Overwrite existing template files.
+  --codex-cli               Also run CO-managed Codex CLI setup (plan unless --yes).
+  --codex-source <path>     Build managed Codex CLI from local repo (or git URL).
+  --codex-ref <ref>         Git ref for --codex-source.
+  --codex-download-url <url>  Download managed Codex CLI prebuilt binary.
+  --codex-download-sha256 <sha>  Expected SHA256 for the prebuilt download.
+  --codex-force             Overwrite existing managed Codex CLI binary.
+  --yes                     Apply managed Codex CLI setup.
+`);
+}