@kbediako/codex-orchestrator 0.1.34 → 0.1.35

package/README.md

@@ -145,6 +145,7 @@ 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 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`).
 
 ### Delegation flow

package/dist/bin/codex-orchestrator.js

@@ -612,6 +612,12 @@ async function handleStart(orchestrator, rawArgs) {
                 })
                 : { issueLog: null, issueLogError: null };
             emitRunOutput(result, format, 'Run started', issueLogCapture);
+            if (result.manifest.status === 'succeeded' && result.manifest.pipeline_id !== 'rlm') {
+                await maybeEmitRunAdoptionHint({
+                    format,
+                    taskFilter: resolveTaskFilter(result.manifest.task_id, taskIdOverride)
+                });
+            }
         });
     }
     catch (error) {
@@ -773,6 +779,10 @@ async function handleFlow(orchestrator, rawArgs) {
                 return;
             }
             console.log('Flow complete: docs-review -> implementation-gate.');
+            await maybeEmitRunAdoptionHint({
+                format,
+                taskFilter: resolveTaskFilter(implementationGateResult.manifest.task_id, taskId)
+            });
         });
     }
     catch (error) {
@@ -1026,7 +1036,7 @@ async function handleExec(rawArgs) {
         await maybeEmitExecAdoptionHint(env.taskId);
     }
 }
-async function shouldScanExecAdoptionHint(taskFilter) {
+async function shouldScanAdoptionHint(taskFilter) {
     if (!taskFilter) {
         return false;
     }
@@ -1056,9 +1066,9 @@ async function shouldScanExecAdoptionHint(taskFilter) {
         }
     }
 }
-async function maybeEmitExecAdoptionHint(taskFilter) {
+async function maybeEmitAdoptionHint(taskFilter) {
     try {
-        if (!(await shouldScanExecAdoptionHint(taskFilter))) {
+        if (!(await shouldScanAdoptionHint(taskFilter))) {
             return;
         }
         const usage = await runDoctorUsage({ windowDays: 7, taskFilter });
@@ -1072,6 +1082,15 @@ async function maybeEmitExecAdoptionHint(taskFilter) {
         // Exec command behavior should not fail when usage telemetry cannot be read.
     }
 }
+async function maybeEmitRunAdoptionHint(params) {
+    if (params.format !== 'text') {
+        return;
+    }
+    await maybeEmitAdoptionHint(params.taskFilter);
+}
+async function maybeEmitExecAdoptionHint(taskFilter) {
+    await maybeEmitAdoptionHint(taskFilter);
+}
 async function handleSelfCheck(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
@@ -2025,6 +2044,12 @@ Commands:
 
   help                      Show this message.
 
+Quickstart (agent-first):
+  codex-orchestrator flow --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>
+
 Notes:
   RLM recursion guidance: docs/guides/rlm-recursion-v2.md
   Cloud-mode preflight/fallback guide: docs/guides/cloud-mode-preflight.md
@@ -2156,6 +2181,13 @@ Options:
   --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.
+
+Examples:
+  codex-orchestrator flow --task <task-id>
+  codex-orchestrator flow --task <task-id> --cloud --target implementation-gate:review
+
+Post-run check:
+  codex-orchestrator doctor --usage --window-days 30 --task <task-id>
 `);
 }
 function printStartHelp() {
@@ -2182,6 +2214,13 @@ Options:
   --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.
+
+Examples:
+  codex-orchestrator start docs-review --task <task-id>
+  codex-orchestrator start implementation-gate --task <task-id> --cloud --target review
+
+Post-run check:
+  codex-orchestrator doctor --usage --window-days 30 --task <task-id>
 `);
 }
 function printPlanHelp() {

package/dist/orchestrator/src/cli/doctorUsage.js

@@ -411,7 +411,10 @@ function buildAdoptionRecommendations(params) {
     if (params.cloudConfigured && params.cloudRuns === 0) {
         hints.push('CODEX_CLOUD_ENV_ID is configured but no cloud runs were observed; route one long-running stage through cloud: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`.');
     }
-    if (params.cloudConfigured && params.cloudRuns > 0 && cloudShare < 0.1) {
+    else if (params.cloudRuns === 0) {
+        hints.push('No cloud runs detected; configure CODEX_CLOUD_ENV_ID and run `codex-orchestrator start <pipeline> --cloud --target <stage-id>` for long-running stages.');
+    }
+    else if (params.cloudConfigured && cloudShare < 0.1) {
         hints.push(`Cloud is configured but adoption is low (${Math.round(cloudShare * 1000) / 10}%); prefer cloud for heavy stages and confirm readiness with \`codex-orchestrator doctor --cloud-preflight\`.`);
     }
     if (params.rlmRuns === 0) {
@@ -420,9 +423,6 @@ function buildAdoptionRecommendations(params) {
     if (params.rlmRuns > 0 && rlmShare < 0.1) {
         hints.push(`RLM usage is low (${Math.round(rlmShare * 1000) / 10}%); route multi-step ambiguous work through \`codex-orchestrator rlm --multi-agent auto "<goal>"\`.`);
     }
-    if (params.cloudRuns === 0) {
-        hints.push('No cloud runs detected; configure CODEX_CLOUD_ENV_ID and run `codex-orchestrator start <pipeline> --cloud --target <stage-id>` for long-running stages.');
-    }
     if (params.rlmRuns > 0 && params.collabRunsWithToolCalls === 0) {
         hints.push('RLM is used without collab activity; ensure multi-agent is enabled (`codex features enable multi_agent`, legacy alias: `collab`).');
     }