@kbediako/codex-orchestrator 0.1.2 → 0.1.4

package/README.md

@@ -122,7 +122,7 @@ Notes:
 - These prompts are consumed by the Codex CLI UI only; the orchestrator does not read them. Keep updates synced across machines during onboarding.
 - To install or refresh the prompts (repo-only), run `scripts/setup-codex-prompts.sh` (use `--force` to overwrite existing files).
 - `/prompts:diagnostics` takes `TASK=<task-id> MANIFEST=<path> [NOTES=<free text>]`, exports `MCP_RUNNER_TASK_ID=$TASK`, runs `npx codex-orchestrator start diagnostics --format json`, tails `.runs/$TASK/cli/<run-id>/manifest.json` (or `npx codex-orchestrator status --watch`), and records evidence to `/tasks`, `docs/TASKS.md`, `.agent/task/...`, `.runs/$TASK/metrics.json`, and `out/$TASK/state.json` using `$MANIFEST`.
-- `/prompts:review-handoff` takes `TASK=<task-id> MANIFEST=<path> NOTES=<goal + summary + risks + optional questions>`, re-exports `MCP_RUNNER_TASK_ID`, and (repo-only) runs `node scripts/spec-guard.mjs --dry-run`, `npm run lint`, `npm run test`, optional `npm run eval:test`, plus `npm run review` (wraps `codex review` against the current diff and includes the latest run manifest path as evidence). It also reminds you to log approvals in `$MANIFEST` and mirror the evidence to the same docs/metrics/state targets.
+- `/prompts:review-handoff` takes `TASK=<task-id> MANIFEST=<path> NOTES=<goal + summary + risks + optional questions>`, re-exports `MCP_RUNNER_TASK_ID`, and (repo-only) runs `node scripts/delegation-guard.mjs`, `node scripts/spec-guard.mjs --dry-run`, `npm run lint`, `npm run test`, optional `npm run eval:test`, plus `npm run review` (wraps `codex review` against the current diff and includes the latest run manifest path as evidence). It also reminds you to log approvals in `$MANIFEST` and mirror the evidence to the same docs/metrics/state targets.
 - In CI / `--no-interactive` pipelines (or when stdin is not a TTY), `npm run review` prints the review handoff prompt (including evidence paths) and exits successfully instead of invoking `codex review`. Set `FORCE_CODEX_REVIEW=1` to run `codex review` in those environments.
 - Always trigger diagnostics and review workflows through these prompts whenever you run the orchestrator so contributors consistently execute the required command sequences and capture auditable manifests.
 
@@ -130,11 +130,16 @@ Notes:
 - `MCP_RUNNER_TASK_ID` is no longer coerced or lowercased silently. The CLI calls the shared `sanitizeTaskId` helper and fails fast when the value contains control characters, traversal attempts, or Windows-reserved characters (`<`, `>`, `:`, `"`, `/`, `\`, `|`, `?`, `*`). Set the correct task ID in your environment *before* invoking the CLI.
 - Run IDs used for manifest or artifact storage must come from the CLI (or pass the shared `sanitizeRunId` helper). Strings with colons, control characters, or `../` are rejected to ensure every run directory lives under `.runs/<task-id>/cli/<run-id>` (and legacy `mcp` mirrors) without risking traversal.
 
+### Delegation Guardrails
+- `delegate.question.poll` clamps `wait_ms` to `MAX_QUESTION_POLL_WAIT_MS` (10s); each poll timeout is bounded by the remaining `wait_ms`.
+- Confirm-to-act fallback only triggers on confirmation-specific errors (`error.code`), not generic tool failures.
+- Tool profile entries used for MCP overrides are sanitized; only alphanumeric + `_`/`-` names are allowed (rejects `;`, `/`, `\n`, `=` and similar).
+
 ## Pipelines & Execution Plans
 - Default pipelines live in `codex.orchestrator.json` (repository-specific) and `orchestrator/src/cli/pipelines/` (built-in defaults). Each stage is either a command (shell execution) or a nested pipeline.
 - The `CommandPlanner` inspects the selected pipeline and target stage; you can pass `--target <stage-id>` (alias: `--target-stage`) or set `CODEX_ORCHESTRATOR_TARGET_STAGE` to focus on a specific step (e.g., rerun tests only).
 - Stage execution records stdout/stderr logs, exit codes, optional summaries, and failure data directly into the manifest (`commands[]` array).
-- Guardrails (repo-only): before review, run `node scripts/spec-guard.mjs --dry-run` to ensure specs touched in the PR are current; the orchestrator tracks guardrail outcomes in the manifest (`guardrail_status`).
+- Guardrails (repo-only): before review, run `node scripts/delegation-guard.mjs` and `node scripts/spec-guard.mjs --dry-run` to ensure delegation and spec freshness; the orchestrator tracks guardrail outcomes in the manifest (`guardrail_status`).
 
 ## Approval & Sandbox Model
 - Approval policies (`never`, `on-request`, `auto`, or custom strings) flow through `packages/orchestrator`. Tool invocations can require approval before sandbox elevation, and all prompts/decisions are persisted.
@@ -149,7 +154,7 @@ Notes:
 - `TaskStateStore` writes per-task snapshots with bounded lock retries; failures degrade gracefully while still writing the main manifest.
 - `RunManifestWriter` generates the canonical manifest JSON for each run (mirrored under `.runs/`), while metrics appenders and summary writers keep `out/` up to date.
 - Heartbeat files and timestamps guard against stalled runs. `orchestrator/src/cli/metrics/metricsRecorder.ts` aggregates command durations, exit codes, and guardrail stats for later review.
-- Optional caps: `CODEX_ORCHESTRATOR_EXEC_EVENT_MAX_CHUNKS` limits captured exec chunk events per command (0 = no cap), and `CODEX_METRICS_PRIVACY_EVENTS_MAX` limits privacy decision events stored in `metrics.json` (-1 = no cap; `privacy_event_count` still reflects total).
+- Optional caps: `CODEX_ORCHESTRATOR_EXEC_EVENT_MAX_CHUNKS` limits captured exec chunk events per command (defaults to 500; set 0 for no cap), `CODEX_ORCHESTRATOR_TELEMETRY_MAX_EVENTS` caps in-memory telemetry events queued before flush (defaults to 1000; set 0 for no cap), and `CODEX_METRICS_PRIVACY_EVENTS_MAX` limits privacy decision events stored in `metrics.json` (-1 = no cap; `privacy_event_count` still reflects total).
 
 ## Customizing for New Projects
 - Duplicate the templates under `/tasks`, `docs/`, and `.agent/` for your task ID and keep checklist status mirrored (`[ ]` → `[x]`) with links to the manifest that proves each outcome.
@@ -166,6 +171,8 @@ Note: the commands below assume a source checkout; `scripts/` helpers are not in
 | `npm run test` | Vitest suite covering orchestration core, CLI services, and patterns. |
 | `npm run eval:test` | Optional evaluation harness (enable when `evaluation/fixtures/**` is populated). |
 | `npm run docs:check` | Deterministically validates scripts/pipelines/paths referenced in agent-facing docs. |
+| `npm run docs:freshness` | Validates docs registry coverage + review recency; writes `out/<task-id>/docs-freshness.json`. |
+| `node scripts/delegation-guard.mjs` | Enforces subagent delegation evidence before review (repo-only). |
 | `node scripts/spec-guard.mjs --dry-run` | Validates spec freshness; required before review (repo-only). |
 | `node scripts/diff-budget.mjs` | Guards against oversized diffs before review (repo-only; defaults: 25 files / 800 lines; supports explicit overrides). |
 | `npm run review` | Runs `codex review` with the latest run manifest path as evidence (repo-only; CI disables stdin; set `CODEX_REVIEW_NON_INTERACTIVE=1` to enforce locally). |
@@ -198,18 +205,18 @@ Use an explicit handoff note for reviewers. `NOTES` is required for review runs;
 Template: `Goal: ... | Summary: ... | Risks: ... | Questions (optional): ...`
 
 To enable Chrome DevTools for review runs, set `CODEX_REVIEW_DEVTOOLS=1` (uses a codex config override; no repo scripts required).
-Default to the standard `implementation-gate` for general reviews; use `implementation-gate-devtools` only when the review needs Chrome DevTools capabilities (visual/layout checks, network/perf diagnostics). After fixing review feedback, rerun the same gate and include any follow-up questions in `NOTES`.
-To run the full implementation gate with DevTools-enabled review, use `npx codex-orchestrator start implementation-gate-devtools --format json --no-interactive --task <task-id>`.
+Default to the standard `implementation-gate` for general reviews; enable DevTools only when the review needs Chrome DevTools capabilities (visual/layout checks, network/perf diagnostics). After fixing review feedback, rerun the same gate and include any follow-up questions in `NOTES`.
+To run the full implementation gate with DevTools-enabled review, use `CODEX_REVIEW_DEVTOOLS=1 npx codex-orchestrator start implementation-gate --format json --no-interactive --task <task-id>`.
 
 ## Frontend Testing
 Frontend testing is a first-class pipeline with DevTools off by default. The shipped pipelines already set `CODEX_NON_INTERACTIVE=1`; add it explicitly for custom automation or when you want the `frontend-test` shortcut to suppress Codex prompts:
 - `CODEX_NON_INTERACTIVE=1 npx codex-orchestrator start frontend-testing --format json --no-interactive --task <task-id>`
-- `CODEX_NON_INTERACTIVE=1 npx codex-orchestrator start frontend-testing-devtools --format json --no-interactive --task <task-id>` (DevTools enabled)
+- `CODEX_NON_INTERACTIVE=1 CODEX_REVIEW_DEVTOOLS=1 npx codex-orchestrator start frontend-testing --format json --no-interactive --task <task-id>` (DevTools enabled)
 - `CODEX_NON_INTERACTIVE=1 codex-orchestrator frontend-test` (shortcut; add `--devtools` to enable DevTools)
 
 If you run the pipelines from this repo, run `npm run build` first so `dist/` stays current (the pipeline executes the compiled runner).
 
-Note: the frontend-testing pipelines toggle the shared `CODEX_REVIEW_DEVTOOLS` flag under the hood; prefer `--devtools` or the devtools pipeline instead of setting it manually.
+Note: the frontend-testing pipeline reads the shared `CODEX_REVIEW_DEVTOOLS` flag; prefer `--devtools` or `CODEX_REVIEW_DEVTOOLS=1` for explicit enablement.
 
 Optional prompt overrides:
 - `CODEX_FRONTEND_TEST_PROMPT` (inline prompt)
@@ -254,4 +261,4 @@ Use the hi-fi pipeline to snapshot complex marketing sites (motion, interactions
 
 ---
 
-When preparing a review (repo-only), always capture the latest manifest path, run `node scripts/spec-guard.mjs --dry-run`, and ensure checklist mirrors (`/tasks`, `docs/`, `.agent/`) point at the evidence generated by Codex Orchestrator. That keeps the automation trustworthy and auditable across projects.
+When preparing a review (repo-only), always capture the latest manifest path, run `node scripts/delegation-guard.mjs` and `node scripts/spec-guard.mjs --dry-run`, and ensure checklist mirrors (`/tasks`, `docs/`, `.agent/`) point at the evidence generated by Codex Orchestrator. That keeps the automation trustworthy and auditable across projects.

package/dist/bin/codex-orchestrator.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
 import process from 'node:process';
 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 { resolveEnvironment, sanitizeTaskId } from '../orchestrator/src/cli/run/environment.js';
+import { resolveEnvironmentPaths } from '../scripts/lib/run-manifests.js';
+import { normalizeEnvironmentPaths, 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';
@@ -11,7 +14,10 @@ import { initCodexTemplates, formatInitSummary } from '../orchestrator/src/cli/i
 import { runDoctor, formatDoctorSummary } from '../orchestrator/src/cli/doctor.js';
 import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.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 { startDelegationServer } from '../orchestrator/src/cli/delegationServer.js';
+import { splitDelegationConfigOverrides } from '../orchestrator/src/cli/config/delegationConfig.js';
 async function main() {
     const args = process.argv.slice(2);
     const command = args.shift();
@@ -35,6 +41,9 @@ async function main() {
             case 'plan':
                 await handlePlan(orchestrator, args);
                 break;
+            case 'rlm':
+                await handleRlm(orchestrator, args);
+                break;
             case 'resume':
                 await handleResume(orchestrator, args);
                 break;
@@ -59,6 +68,10 @@ async function main() {
             case 'mcp':
                 await handleMcp(args);
                 break;
+            case 'delegate-server':
+            case 'delegation-server':
+                await handleDelegationServer(args);
+                break;
             case 'version':
                 printVersion();
                 break;
@@ -111,110 +124,133 @@ function resolveTargetStageId(flags) {
     }
     return undefined;
 }
+function readStringFlag(flags, key) {
+    const value = flags[key];
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function applyRlmEnvOverrides(flags, goal) {
+    if (goal) {
+        process.env.RLM_GOAL = goal;
+    }
+    const validator = readStringFlag(flags, 'validator');
+    if (validator) {
+        process.env.RLM_VALIDATOR = validator;
+    }
+    const maxIterations = readStringFlag(flags, 'max-iterations');
+    if (maxIterations) {
+        process.env.RLM_MAX_ITERATIONS = maxIterations;
+    }
+    const maxMinutes = readStringFlag(flags, 'max-minutes');
+    if (maxMinutes) {
+        process.env.RLM_MAX_MINUTES = maxMinutes;
+    }
+    const roles = readStringFlag(flags, 'roles');
+    if (roles) {
+        process.env.RLM_ROLES = roles;
+    }
+}
+function resolveRlmTaskId(taskFlag) {
+    if (taskFlag) {
+        return sanitizeTaskId(taskFlag);
+    }
+    const envTask = process.env.MCP_RUNNER_TASK_ID?.trim();
+    if (envTask) {
+        return sanitizeTaskId(envTask);
+    }
+    const { repoRoot } = resolveEnvironmentPaths();
+    const repoName = basename(repoRoot);
+    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 handleStart(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    const interactiveRequested = Boolean(flags['interactive'] || flags['ui']);
-    const interactiveDisabled = Boolean(flags['no-interactive']);
-    const runEvents = new RunEventEmitter();
-    const gate = evaluateInteractiveGate({
-        requested: interactiveRequested,
-        disabled: interactiveDisabled,
-        format,
-        stdoutIsTTY: process.stdout.isTTY === true,
-        stderrIsTTY: process.stderr.isTTY === true,
-        term: process.env.TERM ?? null
-    });
-    const hud = await maybeStartHud(gate, runEvents);
-    if (!gate.enabled && interactiveRequested && !interactiveDisabled && gate.reason) {
-        console.error(`[HUD disabled] ${gate.reason}`);
-    }
-    try {
+    if (pipelineId === 'rlm') {
+        const goal = readStringFlag(flags, 'goal');
+        applyRlmEnvOverrides(flags, goal);
+    }
+    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}`);
+            }
+        }
         const result = await orchestrator.start({
             pipelineId,
-            taskId: typeof flags['task'] === 'string' ? flags['task'] : undefined,
+            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),
             runEvents
         });
-        hud?.stop();
-        const payload = {
-            run_id: result.manifest.run_id,
-            status: result.manifest.status,
-            artifact_root: result.manifest.artifact_root,
-            manifest: `${result.manifest.artifact_root}/manifest.json`,
-            log_path: result.manifest.log_path
-        };
-        if (format === 'json') {
-            console.log(JSON.stringify(payload, null, 2));
-        }
-        else {
-            console.log(`Run started: ${payload.run_id}`);
-            console.log(`Status: ${payload.status}`);
-            console.log(`Manifest: ${payload.manifest}`);
-            console.log(`Log: ${payload.log_path}`);
-        }
-    }
-    finally {
-        hud?.stop();
-        runEvents.dispose();
-    }
+        emitRunOutput(result, format, 'Run started');
+    });
 }
 async function handleFrontendTest(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const devtools = Boolean(flags['devtools']);
-    const interactiveRequested = Boolean(flags['interactive'] || flags['ui']);
-    const interactiveDisabled = Boolean(flags['no-interactive']);
-    const runEvents = new RunEventEmitter();
-    const gate = evaluateInteractiveGate({
-        requested: interactiveRequested,
-        disabled: interactiveDisabled,
-        format,
-        stdoutIsTTY: process.stdout.isTTY === true,
-        stderrIsTTY: process.stderr.isTTY === true,
-        term: process.env.TERM ?? null
-    });
-    const hud = await maybeStartHud(gate, runEvents);
-    if (!gate.enabled && interactiveRequested && !interactiveDisabled && gate.reason) {
-        console.error(`[HUD disabled] ${gate.reason}`);
-    }
     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 {
-        const pipelineId = devtools ? 'frontend-testing-devtools' : 'frontend-testing';
-        const result = await orchestrator.start({
-            pipelineId,
-            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),
-            runEvents
+        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),
+                runEvents
+            });
+            emitRunOutput(result, format, 'Run started');
         });
-        hud?.stop();
-        const payload = {
-            run_id: result.manifest.run_id,
-            status: result.manifest.status,
-            artifact_root: result.manifest.artifact_root,
-            manifest: `${result.manifest.artifact_root}/manifest.json`,
-            log_path: result.manifest.log_path
-        };
-        if (format === 'json') {
-            console.log(JSON.stringify(payload, null, 2));
-        }
-        else {
-            console.log(`Run started: ${payload.run_id}`);
-            console.log(`Status: ${payload.status}`);
-            console.log(`Manifest: ${payload.manifest}`);
-            console.log(`Log: ${payload.log_path}`);
-        }
     }
     finally {
-        hud?.stop();
-        runEvents.dispose();
+        if (devtools) {
+            if (originalDevtools === undefined) {
+                delete process.env.CODEX_REVIEW_DEVTOOLS;
+            }
+            else {
+                process.env.CODEX_REVIEW_DEVTOOLS = originalDevtools;
+            }
+        }
     }
 }
 async function handlePlan(orchestrator, rawArgs) {
@@ -232,6 +268,47 @@ async function handlePlan(orchestrator, rawArgs) {
     }
     process.stdout.write(`${formatPlanPreview(result)}\n`);
 }
+async function handleRlm(orchestrator, rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    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;
+    applyRlmEnvOverrides(flags, goal);
+    console.log(`Task: ${taskId}`);
+    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,
+            runEvents
+        });
+        emitRunOutput(startResult, 'text', 'Run started');
+    });
+    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);
     const runId = (flags['run'] ?? positionals[0]);
@@ -239,22 +316,7 @@ async function handleResume(orchestrator, rawArgs) {
         throw new Error('resume requires --run <run-id>.');
     }
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    const interactiveRequested = Boolean(flags['interactive'] || flags['ui']);
-    const interactiveDisabled = Boolean(flags['no-interactive']);
-    const runEvents = new RunEventEmitter();
-    const gate = evaluateInteractiveGate({
-        requested: interactiveRequested,
-        disabled: interactiveDisabled,
-        format,
-        stdoutIsTTY: process.stdout.isTTY === true,
-        stderrIsTTY: process.stderr.isTTY === true,
-        term: process.env.TERM ?? null
-    });
-    const hud = await maybeStartHud(gate, runEvents);
-    if (!gate.enabled && interactiveRequested && !interactiveDisabled && gate.reason) {
-        console.error(`[HUD disabled] ${gate.reason}`);
-    }
-    try {
+    await withRunUi(flags, format, async (runEvents) => {
         const result = await orchestrator.resume({
             runId,
             resumeToken: typeof flags['token'] === 'string' ? flags['token'] : undefined,
@@ -263,28 +325,8 @@ async function handleResume(orchestrator, rawArgs) {
             targetStageId: resolveTargetStageId(flags),
             runEvents
         });
-        hud?.stop();
-        const payload = {
-            run_id: result.manifest.run_id,
-            status: result.manifest.status,
-            artifact_root: result.manifest.artifact_root,
-            manifest: `${result.manifest.artifact_root}/manifest.json`,
-            log_path: result.manifest.log_path
-        };
-        if (format === 'json') {
-            console.log(JSON.stringify(payload, null, 2));
-        }
-        else {
-            console.log(`Run resumed: ${payload.run_id}`);
-            console.log(`Status: ${payload.status}`);
-            console.log(`Manifest: ${payload.manifest}`);
-            console.log(`Log: ${payload.log_path}`);
-        }
-    }
-    finally {
-        hud?.stop();
-        runEvents.dispose();
-    }
+        emitRunOutput(result, format, 'Run resumed');
+    });
 }
 async function handleStatus(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -315,6 +357,47 @@ async function maybeStartHud(gate, emitter) {
     const { startHud } = await import('../orchestrator/src/cli/ui/controller.js');
     return startHud({ emitter, footerNote: 'interactive HUD (read-only)' });
 }
+async function withRunUi(flags, format, action) {
+    const interactiveRequested = Boolean(flags['interactive'] || flags['ui']);
+    const interactiveDisabled = Boolean(flags['no-interactive']);
+    const runEvents = new RunEventEmitter();
+    const gate = evaluateInteractiveGate({
+        requested: interactiveRequested,
+        disabled: interactiveDisabled,
+        format,
+        stdoutIsTTY: process.stdout.isTTY === true,
+        stderrIsTTY: process.stderr.isTTY === true,
+        term: process.env.TERM ?? null
+    });
+    const hud = await maybeStartHud(gate, runEvents);
+    if (!gate.enabled && interactiveRequested && !interactiveDisabled && gate.reason) {
+        console.error(`[HUD disabled] ${gate.reason}`);
+    }
+    try {
+        await action(runEvents);
+    }
+    finally {
+        hud?.stop();
+        runEvents.dispose();
+    }
+}
+function emitRunOutput(result, format, label) {
+    const payload = {
+        run_id: result.manifest.run_id,
+        status: result.manifest.status,
+        artifact_root: result.manifest.artifact_root,
+        manifest: `${result.manifest.artifact_root}/manifest.json`,
+        log_path: result.manifest.log_path
+    };
+    if (format === 'json') {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log(`${label}: ${payload.run_id}`);
+    console.log(`Status: ${payload.status}`);
+    console.log(`Manifest: ${payload.manifest}`);
+    console.log(`Log: ${payload.log_path}`);
+}
 async function handleExec(rawArgs) {
     const parsed = parseExecArgs(rawArgs);
     if (parsed.commandTokens.length === 0) {
@@ -322,7 +405,7 @@ async function handleExec(rawArgs) {
     }
     const isInteractive = process.stdout.isTTY === true && process.stderr.isTTY === true;
     const outputMode = parsed.requestedMode ?? (isInteractive ? 'interactive' : 'jsonl');
-    const env = resolveEnvironment();
+    const env = normalizeEnvironmentPaths(resolveEnvironmentPaths());
     if (parsed.taskId) {
         env.taskId = sanitizeTaskId(parsed.taskId);
     }
@@ -429,6 +512,34 @@ async function handleMcp(rawArgs) {
     const dryRun = Boolean(flags['dry-run']);
     await serveMcp({ repoRoot, dryRun, extraArgs: positionals });
 }
+async function handleDelegationServer(rawArgs) {
+    const { flags } = parseArgs(rawArgs);
+    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 });
+}
 function parseExecArgs(rawArgs) {
     const notifyTargets = [];
     let otelEndpoint = null;
@@ -550,6 +661,22 @@ Commands:
     --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).
+    --goal "<goal>"         When pipeline is rlm, set the RLM goal.
+    --validator <cmd|none>  When pipeline is rlm, set the validator command.
+    --max-iterations <n>    When pipeline is rlm, override max iterations.
+    --max-minutes <n>       When pipeline is rlm, override max minutes.
+    --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 (default is off unless requested).
+
+  rlm "<goal>"              Run RLM loop until validator passes.
+    --task <id>             Override task identifier.
+    --validator <cmd|none>  Set validator command or disable validation.
+    --max-iterations <n>    Override max iterations (0 = unlimited with validator).
+    --max-minutes <n>       Optional time-based guardrail in minutes.
+    --roles <single|triad>  Choose single or triad role split.
+    --parent-run <id>       Link run to parent run id.
+    --approval-policy <p>   Record approval policy metadata.
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
@@ -594,6 +721,10 @@ Commands:
     --yes                 Apply setup by running "codex mcp add ...".
     --format json         Emit machine-readable output (dry-run only).
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
+  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.
+    --config "<key>=<value>[;...]"  Apply config overrides (repeat via separators).
   version | --version
 
   help                      Show this message.