@kbediako/codex-orchestrator 0.1.32 → 0.1.33

package/README.md

@@ -47,7 +47,7 @@ Use this when you want Codex to drive work inside another repo with the CO defau
    ```bash
    codex-orchestrator init codex --cwd /path/to/repo
    ```
-   One-shot (templates + CO-managed Codex CLI):
+   One-shot (templates + optional CO-managed Codex CLI install):
    ```bash
    codex-orchestrator init codex --codex-cli --yes
    ```
@@ -59,7 +59,11 @@ Use this when you want Codex to drive work inside another repo with the CO defau
    ```bash
    codex-orchestrator codex setup
    ```
-   Use this when you want a pinned binary, build-from-source behavior, or a custom fork. Stock `codex` works for default flows.
+   Use this when you want a pinned binary, build-from-source behavior, or a custom fork.
+   Stock/global `codex` is still the default selection; activate managed binary routing with:
+   ```bash
+   export CODEX_CLI_USE_MANAGED=1
+   ```
 4. Optional (fast refresh helper for downstream users):
    ```bash
    scripts/codex-cli-refresh.sh --repo /path/to/codex --align-only
@@ -81,6 +85,58 @@ codex -c 'mcp_servers.delegation.enabled=true' ...
 ```
 `delegate-server` is the canonical name; `delegation-server` is supported as an alias (older docs may use it).
 
+## 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.
+
+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`:
+
+```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."
+
+[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"
+
+[agents.worker_complex]
+description = "Complex worker role."
+config_file = "/absolute/path/to/.codex/agents/worker-complex.toml"
+```
+
+```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
+model = "gpt-5.3-codex"
+model_reasoning_effort = "xhigh"
+```
+
+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.
+
 Delegation guard profile:
 - `CODEX_ORCHESTRATOR_GUARD_PROFILE=auto` (default): strict in CO-style repos, warn in lightweight repos.
 - Set `CODEX_ORCHESTRATOR_GUARD_PROFILE=warn` for ad-hoc/no-task-id runs.
@@ -88,8 +144,8 @@ Delegation guard profile:
 
 ## Delegation + RLM flow
 
-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 when delegated, when `RLM_CONTEXT_PATH` is set, or when the context exceeds `RLM_SYMBOLIC_MIN_BYTES`; 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.
-Symbolic subcalls can optionally use collab tools. Fast path: `codex-orchestrator rlm --collab auto "<goal>"` (sets `RLM_SYMBOLIC_COLLAB=1` and implies symbolic mode). Collab requires `collab=true` in `codex features list`. Collab tool calls parsed from `codex exec --json --enable collab` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable). `codex-orchestrator codex setup` remains available when you want a managed/pinned CLI path.
+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.
+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`).
 
 ### Delegation flow
 ```mermaid
@@ -133,6 +189,8 @@ flowchart TB
 Recommended one-shot bootstrap (skills + delegation + DevTools wiring):
 ```bash
 codex-orchestrator setup --yes
+# Optional: overwrite existing bundled skills in $CODEX_HOME/skills
+# codex-orchestrator setup --yes --refresh-skills
 ```
 
 The release ships skills under `skills/` for downstream packaging. If you already have global skills installed, treat those as the primary reference and use bundled skills as the shipped fallback. Install bundled skills into `$CODEX_HOME/skills`:
@@ -172,15 +230,24 @@ Usage snapshot (scans local `.runs/`):
 ```bash
 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.
+
+Cloud preflight check (without starting a pipeline):
+```bash
+codex-orchestrator doctor --cloud-preflight
+```
 
 ## Downstream usage cheatsheet (agent-first)
 
-- Bootstrap + wire everything: `codex-orchestrator setup --yes`
+- Bootstrap + wire everything: `codex-orchestrator setup --yes` (non-destructive for existing skills by default; add `--refresh-skills` to overwrite)
+- 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`
 - 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 --collab auto "<goal>"` (requires collab feature enabled in Codex)
+- 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>`
+- Cloud fail-fast (avoid fallback reliance): set `CODEX_ORCHESTRATOR_CLOUD_FALLBACK=deny`
+- Cloud status retry tuning (optional): `CODEX_CLOUD_STATUS_RETRY_LIMIT`, `CODEX_CLOUD_STATUS_RETRY_BACKOFF_MS`
 
 Print DevTools MCP setup guidance:
 ```bash
@@ -194,11 +261,12 @@ codex-orchestrator devtools setup
 - `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`) into a repo.
-- `codex-orchestrator setup --yes` — install bundled skills and configure delegation + DevTools wiring.
-- `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).
+- `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).
+- `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 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.