@kbediako/codex-orchestrator 0.1.35 → 0.1.36

package/README.md

@@ -51,6 +51,7 @@ Use this when you want Codex to drive work inside another repo with the CO defau
    ```bash
    codex-orchestrator init codex --codex-cli --yes
    ```
+   This seeds `AGENTS.md`, `mcp-client.json`, and downstream .codex/config.toml + .codex/agents/* role files (sourced from `templates/codex/.codex/*`), plus `codex.orchestrator.json`.
 2. Register the delegation MCP server (one-time per machine):
    ```bash
    codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
@@ -64,7 +65,13 @@ Use this when you want Codex to drive work inside another repo with the CO defau
    ```bash
    export CODEX_CLI_USE_MANAGED=1
    ```
-4. Optional (fast refresh helper for downstream users):
+4. Optional (additive global defaults in `~/.codex/config.toml`):
+   ```bash
+   codex-orchestrator codex defaults
+   codex-orchestrator codex defaults --yes
+   ```
+   This updates only the CO baseline keys/role wiring and preserves unrelated config entries.
+5. Optional (fast refresh helper for downstream users):
    ```bash
    scripts/codex-cli-refresh.sh --repo /path/to/codex --align-only
    ```
@@ -87,55 +94,57 @@ codex -c 'mcp_servers.delegation.enabled=true' ...
 
 ## Agent role defaults (recommended)
 
-Codex built-ins are `default`, `explorer`, and `worker`. `researcher` is user-defined.
-- `spawn_agent` defaults to `default` when `agent_type` is omitted, so always set `agent_type` explicitly when using collab subagents.
+Codex built-ins are `default`, `explorer`, `worker`, and `awaiter`. `researcher` is user-defined.
+- `spawn_agent` defaults to `default` when `agent_type` is omitted, so always set `agent_type` explicitly.
+- Multi-turn loops are supported (`spawn_agent` -> `send_input` -> `wait`/`resume_agent` -> `close_agent`), so subagents can iterate before parent synthesis.
 
-Built-in `explorer` in Codex currently uses `gpt-5.1-codex-mini` with `medium` reasoning unless you override it. If you want latest-codex defaults end-to-end, add role overrides in `~/.codex/config.toml`:
+In Codex CLI `0.105.0`, built-in `explorer` no longer pins an older model profile; it inherits top-level defaults unless you attach a role `config_file`.
+CO now ships this downstream starter config via `init codex` (source template: `templates/codex/.codex/config.toml`; installed as .codex/config.toml in target repos):
 
 ```toml
 model = "gpt-5.3-codex"
 model_reasoning_effort = "xhigh"
 
 [agents]
-max_threads = 8
-
-[agents.explorer]
-description = "Explorer role override (no config_file): keep built-in explorer on top-level model defaults."
+max_threads = 12
+max_depth = 4
+max_spawn_depth = 4
 
 [agents.explorer_fast]
 description = "Fast explorer (spark text-only)."
-config_file = "/absolute/path/to/.codex/agents/explorer-fast.toml"
-
-[agents.explorer_detailed]
-description = "Detailed explorer."
-config_file = "/absolute/path/to/.codex/agents/explorer-detailed.toml"
+config_file = "./agents/explorer-fast.toml"
 
 [agents.worker_complex]
 description = "Complex worker role."
-config_file = "/absolute/path/to/.codex/agents/worker-complex.toml"
+config_file = "./agents/worker-complex.toml"
+
+[agents.awaiter]
+description = "Awaiter override (keeps awaiter behavior with latest codex/high reasoning)."
+config_file = "./agents/awaiter-high.toml"
 ```
 
 ```toml
-# ~/.codex/agents/explorer-fast.toml
+# .codex/agents/explorer-fast.toml
 model = "gpt-5.3-codex-spark"
 model_reasoning_effort = "xhigh"
 ```
 
 ```toml
-# ~/.codex/agents/explorer-detailed.toml
-model = "gpt-5.3-codex"
-model_reasoning_effort = "high"
-```
-
-```toml
-# ~/.codex/agents/worker-complex.toml
+# .codex/agents/worker-complex.toml
 model = "gpt-5.3-codex"
 model_reasoning_effort = "xhigh"
 ```
 
+`init codex` also writes downstream .codex/agents/awaiter-high.toml from `templates/codex/.codex/agents/awaiter-high.toml` so CO users can keep awaiter semantics while meeting a high-reasoning minimum.
+
 Caveats:
 - `gpt-5.3-codex-spark` is text-only (no image inputs). Keep it for fast search/synthesis.
-- Use `max_threads = 8` as a balanced default; only move to `12` after verifying your machine/tooling stays stable under higher concurrency.
+- Leave `agents.explorer` undefined unless you intentionally want to override built-in explorer behavior.
+- Keep RLM/collab built-ins-first by default; add specialist custom roles only when a measured benefit justifies ongoing maintenance.
+- `max_threads = 12`, `max_depth = 4`, and `max_spawn_depth = 4` are CO's standard multi-agent baseline.
+- Fallbacks are contingency-only: use `8/2/2` on constrained hosts or deterministic high-risk lanes; use `6/1/1` only as break-glass under severe contention.
+- Awaiter triage: long waits are expected for long-running jobs; treat it as stuck only after multiple polling windows with no status/progress movement.
+- `codex review` delegates with collab tools disabled in review threads; keep review expectations single-agent even when multi-agent is enabled elsewhere.
 
 Delegation guard profile:
 - `CODEX_ORCHESTRATOR_GUARD_PROFILE=auto` (default): strict in CO-style repos, warn in lightweight repos.
@@ -147,6 +156,7 @@ Delegation guard profile:
 RLM (Recursive Language Model) is the long-horizon loop used by the `rlm` pipeline (`codex-orchestrator rlm "<goal>"` or `codex-orchestrator start rlm --goal "<goal>"`). Delegated runs only enter RLM when the child is launched with the `rlm` pipeline (or the rlm runner directly). In auto mode it resolves to symbolic only when context is large (`RLM_SYMBOLIC_MIN_BYTES`) and an explicit context signal is present (`RLM_CONTEXT_PATH` or delegated run); otherwise it stays iterative. The runner writes state to `.runs/<task-id>/cli/<run-id>/rlm/state.json` and stops when the validator passes or budgets are exhausted.
 For symbolic mode, the Option 2 alignment checker is enabled by default (`RLM_ALIGNMENT_CHECKER=1`) and writes append-only alignment artifacts under `.runs/<task-id>/cli/<run-id>/rlm/alignment/` (ledger + projection). Rollback toggle: set `RLM_ALIGNMENT_CHECKER=0`. Enforcement is opt-in via `RLM_ALIGNMENT_CHECKER_ENFORCE=1`.
 Symbolic subcalls can optionally use collab tools. Fast path: `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; sets `RLM_SYMBOLIC_MULTI_AGENT=1` plus legacy `RLM_SYMBOLIC_COLLAB=1` for compatibility, and implies symbolic mode). Collab requires `multi_agent=true` in `codex features list` (`collab` remains a legacy alias). Collab tool calls parsed from `codex exec --json --enable multi_agent` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable). For auditable role routing, prefix spawned prompts with `[agent_type:<role>]` and set `spawn_agent.agent_type` when supported; lifecycle validation enforces prompt-role evidence and validates `agent_type` when present (`RLM_SYMBOLIC_MULTI_AGENT_ROLE_POLICY=warn|off`, legacy alias `RLM_COLLAB_ROLE_POLICY`; `RLM_SYMBOLIC_MULTI_AGENT_ALLOW_DEFAULT_ROLE=1`, legacy alias `RLM_COLLAB_ALLOW_DEFAULT_ROLE`). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path (opt-in via `CODEX_CLI_USE_MANAGED=1`).
+For batch fan-out jobs, prefer native `spawn_agents_on_csv` before building custom orchestration wrappers.
 
 ### Delegation flow
 ```mermaid
@@ -212,7 +222,9 @@ Bundled skills (may vary by release):
 - `docs-first`
 - `collab-evals`
 - `collab-deliberation`
+- `long-poll-wait`
 - `release`
+- `agent-first-adoption-steering`
 - `delegate-early` (compatibility alias; use `delegation-usage`)
 
 ## DevTools readiness
@@ -232,6 +244,7 @@ Usage snapshot (scans local `.runs/`):
 codex-orchestrator doctor --usage
 ```
 `doctor --usage` prints adoption KPIs (advanced/cloud/rlm/collab/delegation coverage), and per-run `run-summary.json` now includes a `usageKpi` section plus cloud fallback metadata when preflight downgrades to MCP.
+`doctor` also includes a codex-defaults advisory section (model/reasoning/agent baseline drift) and points to additive remediation via `codex-orchestrator codex defaults --yes`.
 
 Issue bundle logging (downstream dogfooding / repro handoff):
 ```bash
@@ -257,8 +270,13 @@ codex-orchestrator doctor --cloud-preflight
 - Enable required MCP servers with least privilege: `codex-orchestrator mcp enable --servers delegation --yes` (plan with `--format json`; omit `--servers` only when you intentionally want all disabled servers enabled; env/secret values are redacted in displayed command lines)
 - Low-friction docs->implementation guardrails: `codex-orchestrator flow --task <task-id>`
 - Validate + measure adoption locally: `codex-orchestrator doctor --usage --format json`
+- Run docs relevance as an advisory lane (non-blocking): `codex-orchestrator start docs-relevance-advisory --task <task-id>`
 - Capture reproducible downstream failures: `codex-orchestrator doctor --issue-log --issue-title "<title>" --issue-notes "<notes>"`
 - Auto-capture failed run issue bundles: `codex-orchestrator start <pipeline> --auto-issue-log` or `codex-orchestrator flow --auto-issue-log`
+- Active PR watch-resolve-merge loop: `codex-orchestrator pr resolve-merge --pr <number> --quiet-minutes <window>` (add `--auto-merge` when approved; exits early when author action is required).
+- Passive PR monitor loop: `codex-orchestrator pr watch-merge --pr <number> --quiet-minutes <window>` (monitor-only behavior; keeps waiting unless terminal/timeout).
+- Review checkpoints (npm-only safe): `NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>` for manifest-backed standalone review wrapper behavior (auto-skips repo-only diff-budget script when unavailable in downstream installs); use `codex review "<focus>"` for quick prompt-only checks; use `codex-orchestrator start implementation-gate --task <task-id> --format json` when you want a full gate run.
+- Downstream simulation before shipping wrapper/skill changes: `npm run pack:smoke` (packaged CLI in temp mock repo; validates `review` artifacts and `long-poll-wait` install path).
 - Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
 - Collab (symbolic RLM subagents): `codex-orchestrator rlm --multi-agent auto "<goal>"` (legacy alias: `--collab auto`; requires Codex `features.multi_agent=true`)
 - Cloud: set `CODEX_CLOUD_ENV_ID` (and optional `CODEX_CLOUD_BRANCH`), then run: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`
@@ -275,17 +293,21 @@ codex-orchestrator devtools setup
 
 - `codex-orchestrator start <pipeline>` — run a pipeline (add `--auto-issue-log` for automatic failure bundle capture; add `--repo-config-required` for strict repo-local config mode).
 - `codex-orchestrator flow --task <task-id>` — run `docs-review` then `implementation-gate` in sequence (supports `--auto-issue-log` and `--repo-config-required`).
+- `codex-orchestrator start docs-relevance-advisory --task <task-id>` — run non-blocking docs relevance signals (warn-mode freshness + advisory review lane).
+- `NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>` — run standalone review wrapper with manifest-backed evidence (supports run-review flags/env).
 - `codex-orchestrator plan <pipeline>` — preview pipeline stages.
 - `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
-- `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`, `codex.orchestrator.json`) into a repo.
+- `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`, downstream .codex/config.toml + .codex/agents/* role files sourced from `templates/codex/.codex/*`, `codex.orchestrator.json`) into a repo.
 - `codex-orchestrator setup --yes` — install bundled skills and configure delegation + DevTools wiring (add `--refresh-skills` to overwrite existing skills in `$CODEX_HOME/skills`).
 - `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — optionally provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time, and `CODEX_CLI_USE_MANAGED=1` to route runs to it).
 - `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.
 - `codex-orchestrator codex setup` — plan/apply a CO-managed Codex CLI install (optional managed/pinned path; use `--download-url` + `--download-sha256` for prebuilts; activate with `CODEX_CLI_USE_MANAGED=1`).
+- `codex-orchestrator codex defaults` — plan/apply additive global defaults in `~/.codex/config.toml` and `~/.codex/agents/*.toml` (`--yes` applies, `--force` allows role file overwrite).
 - `codex-orchestrator delegation setup --yes` — configure delegation MCP server wiring.
 - `codex-orchestrator mcp enable --servers <csv> --yes` — enable specific disabled MCP servers from existing Codex config entries.
 - `codex-orchestrator self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
+- `npm run pack:smoke` — maintainer smoke gate for packaged downstream behavior (tarball install + review/skill checks).
 
 ## What ships in the npm release
 
@@ -302,7 +324,8 @@ Repo internals, development workflows, and deeper architecture notes (contributo
 - `docs/guides/collab-vs-mcp.md` (agent-first decision guide)
 - `docs/guides/rlm-recursion-v2.md` (RLM recursion reference)
 - `docs/guides/cloud-mode-preflight.md` (cloud-mode preflight + fallback guidance)
-- `docs/guides/review-artifacts.md` (where `npm run review` writes prompt/output artifacts)
+- `docs/guides/review-artifacts.md` (where `codex-orchestrator review` / `npm run review` write prompt/output artifacts)
+- `docs/standalone-review-guide.md` (repo-local wrapper behavior + downstream-safe review alternatives)
 
 ## RLM benchmark graphs
 

package/codex.orchestrator.json

@@ -50,6 +50,29 @@
         "command": "npm run docs:freshness"
       }
     ],
+    "docs-relevance-advisory-checks": [
+      {
+        "kind": "command",
+        "id": "docs-freshness-advisory",
+        "title": "npm run docs:freshness -- --warn",
+        "command": "npm run docs:freshness -- --warn",
+        "allowFailure": true,
+        "summaryHint": "Advisory docs-freshness signal (non-blocking)"
+      },
+      {
+        "kind": "command",
+        "id": "docs-relevance-review",
+        "title": "npm run review (docs relevance advisory)",
+        "command": "npm run review",
+        "env": {
+          "SKIP_DIFF_BUDGET": "1",
+          "CODEX_REVIEW_NON_INTERACTIVE": "1",
+          "NOTES": "Goal: docs relevance advisory | Summary: semantic docs relevance review lane with manifest context | Risks: advisory-only lane; false positives/negatives possible"
+        },
+        "allowFailure": true,
+        "summaryHint": "Agent-first docs relevance advisory review"
+      }
+    ],
     "design-artifacts": [
       {
         "kind": "command",
@@ -190,6 +213,22 @@
         }
       ]
     },
+    {
+      "id": "docs-relevance-advisory",
+      "title": "Docs Relevance Advisory",
+      "description": "Runs a non-blocking docs relevance signal lane (warn-mode freshness + advisory review).",
+      "tags": [
+        "docs",
+        "advisory"
+      ],
+      "guardrailsRequired": false,
+      "stages": [
+        {
+          "kind": "stage-set",
+          "ref": "docs-relevance-advisory-checks"
+        }
+      ]
+    },
     {
       "id": "frontend-testing",
       "title": "Frontend Testing",

package/dist/bin/codex-orchestrator.js

@@ -1,8 +1,10 @@
 #!/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 process from 'node:process';
+import { fileURLToPath } 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';
@@ -18,9 +20,10 @@ import { formatDoctorUsageSummary, runDoctorUsage } from '../orchestrator/src/cl
 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 { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
+import { findPackageRoot, 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';
@@ -52,6 +55,9 @@ async function main() {
             case 'flow':
                 await handleFlow(orchestrator, args);
                 break;
+            case 'review':
+                await handleReview(args);
+                break;
             case 'plan':
                 await handlePlan(orchestrator, args);
                 break;
@@ -795,6 +801,65 @@ async function handleFlow(orchestrator, rawArgs) {
         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);
+        });
+    });
+}
+async function handleReview(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printReviewHelp();
+        return;
+    }
+    const runner = resolveReviewRunner();
+    const exitCode = await runPassthroughCommand(runner.command, [...runner.args, ...rawArgs], {
+        cwd: process.cwd(),
+        env: process.env
+    });
+    if (exitCode !== 0) {
+        process.exitCode = exitCode;
+    }
+}
 async function handlePlan(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     if (isHelpRequest(positionals, flags)) {
@@ -1243,6 +1308,7 @@ function buildSetupGuidance() {
             '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'
         ]
     };
@@ -1460,35 +1526,55 @@ async function handleDelegation(rawArgs) {
 async function handleCodex(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const subcommand = positionals.shift();
-    if (!subcommand) {
-        throw new Error('codex requires a subcommand (setup).');
-    }
-    if (subcommand !== 'setup') {
-        throw new Error(`Unknown codex subcommand: ${subcommand}`);
+    if (flags['help'] === true || flags['--help'] === true || flags['h'] === true || !subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+        printCodexHelp();
+        return;
     }
-    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));
+    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;
     }
-    const summary = formatCodexCliSetupSummary(result);
-    for (const line of summary) {
-        console.log(line);
+    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}`);
 }
 async function handleSkills(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -1668,10 +1754,20 @@ async function handlePr(rawArgs) {
         return;
     }
     const [subcommand, ...subcommandArgs] = rawArgs;
-    if (subcommand !== 'watch-merge') {
+    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, { usage: 'codex-orchestrator pr watch-merge' });
+    const exitCode = await runPrWatchMerge(subcommandArgs, mode);
     if (exitCode !== 0) {
         process.exitCode = exitCode;
     }
@@ -1953,6 +2049,18 @@ Commands:
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
+  review [options]          Run manifest-backed standalone review wrapper.
+    Forwards flags/env to scripts/run-review (source) or dist/scripts/run-review.js (npm).
+    Common flags:
+      --manifest <path>     Explicit manifest path for review evidence.
+      --task <id>           Task id used for prompt context.
+      --uncommitted         Review uncommitted diff scope.
+      --base <branch>       Review against base branch.
+      --commit <sha>        Review specific commit.
+      --non-interactive     Force non-interactive review behavior.
+      --auto-issue-log [true|false]  Auto-capture issue bundle on review failure.
+      --disable-delegation-mcp [true|false]  Disable delegation MCP for this review.
+
   plan [pipeline]           Preview pipeline stages without executing.
     --task <id>             Override task identifier.
     --format json           Emit machine-readable output.
@@ -1981,7 +2089,7 @@ Commands:
 
   self-check [--format json]
   init codex [--cwd <path>] [--force]
-    Installs AGENTS.md, mcp-client.json, and codex.orchestrator.json.
+    Installs AGENTS.md, mcp-client.json, .codex/config.toml (+ role files), 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.
@@ -2016,6 +2124,10 @@ Commands:
     --force                Overwrite existing CO-managed codex binary.
     --yes                  Apply setup (otherwise plan only; stock codex remains default until CODEX_CLI_USE_MANAGED=1).
     --format json          Emit machine-readable output.
+  codex defaults
+    --yes                  Apply setup (otherwise dry-run plan only).
+    --force                Allow overwriting existing role files in ~/.codex/agents.
+    --format json          Emit machine-readable output.
   devtools setup          Print DevTools MCP setup instructions.
     --yes                 Apply setup by running "codex mcp add ...".
     --format json         Emit machine-readable output (dry-run only).
@@ -2036,6 +2148,9 @@ Commands:
   pr watch-merge [options]
     Monitor PR checks/reviews with polling and optional auto-merge after a quiet window.
     Use \`codex-orchestrator pr watch-merge --help\` for full options.
+  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.
   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.
@@ -2046,6 +2161,7 @@ Commands:
 
 Quickstart (agent-first):
   codex-orchestrator flow --task <task-id>
+  NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>
   codex-orchestrator doctor --usage --window-days 30
   codex-orchestrator rlm --multi-agent auto "<goal>"
   codex-orchestrator start implementation-gate --cloud --target <stage-id>
@@ -2072,6 +2188,25 @@ Commands:
     --format json           Emit machine-readable output.
 `);
 }
+function printCodexHelp() {
+    console.log(`Usage: codex-orchestrator codex <subcommand> [options]
+
+Subcommands:
+  setup                    Plan/apply CO-managed Codex CLI install.
+    --source <path>        Build from local Codex repo (or git URL).
+    --ref <ref>            Git ref (branch/tag/sha) when building from repo.
+    --download-url <url>   Download a prebuilt codex binary.
+    --download-sha256 <sha>  Expected SHA256 for the prebuilt download.
+    --force                Overwrite existing CO-managed codex binary.
+    --yes                  Apply setup (otherwise plan only).
+    --format json          Emit machine-readable output.
+
+  defaults                 Plan/apply additive global Codex defaults in ~/.codex/config.toml.
+    --yes                  Apply setup (otherwise dry-run plan only).
+    --force                Overwrite existing role files in ~/.codex/agents.
+    --format json          Emit machine-readable output.
+`);
+}
 function printStatusHelp() {
     console.log(`Usage: codex-orchestrator status --run <id> [--watch] [--interval N] [--format json]
 
@@ -2127,10 +2262,14 @@ function printPrHelp() {
 Subcommands:
   watch-merge             Monitor PR checks/reviews with polling and optional auto-merge.
                           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.
 
 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
 
 Guide:
   Review artifacts (prompt + output log paths): docs/guides/review-artifacts.md
@@ -2190,6 +2329,38 @@ Post-run check:
   codex-orchestrator doctor --usage --window-days 30 --task <task-id>
 `);
 }
+function printReviewHelp() {
+    console.log(`Usage: codex-orchestrator review [options]
+
+Runs the standalone review wrapper with manifest-backed evidence.
+This command forwards arguments/environment to run-review and preserves its behavior.
+
+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.
+  --uncommitted                    Review uncommitted diff scope.
+  --base <branch>                  Review against a base branch.
+  --commit <sha>                   Review a specific commit.
+  --title "<text>"                 Optional review title in the prompt.
+  --non-interactive                Force non-interactive behavior.
+  --auto-issue-log [true|false]    Auto-capture issue bundle on review failure.
+  --disable-delegation-mcp [true|false]  Disable delegation MCP for this review.
+  --enable-delegation-mcp [true|false]   Legacy delegation MCP toggle (disable via false).
+
+Environment controls (selected):
+  NOTES                            Recommended review notes ("Goal | Summary | Risks ..."); fallback notes are generated when omitted.
+  CODEX_REVIEW_ALLOW_HEAVY_COMMANDS=1      Allow unrestricted heavy commands.
+  CODEX_REVIEW_ENFORCE_BOUNDED_MODE=1      Enforce bounded mode (hard-stop heavy commands).
+  CODEX_REVIEW_TIMEOUT_SECONDS             Optional overall timeout (0 disables when set).
+  CODEX_REVIEW_STALL_TIMEOUT_SECONDS       Optional stall timeout (0 disables when set).
+  CODEX_REVIEW_MONITOR_INTERVAL_SECONDS    Patience checkpoint cadence (0 disables).
+
+Examples:
+  TASK=<task-id> NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review
+  TASK=<task-id> NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --manifest .runs/<task-id>/cli/<run-id>/manifest.json
+`);
+}
 function printStartHelp() {
     console.log(`Usage: codex-orchestrator start [pipeline] [options]
 
@@ -2241,6 +2412,7 @@ function printInitHelp() {
 Install starter templates into the target repository:
 - AGENTS.md
 - mcp-client.json
+- .codex/config.toml (+ .codex/agents/* role files)
 - codex.orchestrator.json
 
 Options: