@kbediako/codex-orchestrator 0.1.30 → 0.1.32

package/README.md

@@ -176,6 +176,7 @@ codex-orchestrator doctor --usage
 ## Downstream usage cheatsheet (agent-first)
 
 - Bootstrap + wire everything: `codex-orchestrator setup --yes`
+- 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)
@@ -189,6 +190,7 @@ codex-orchestrator devtools setup
 ## Common commands
 
 - `codex-orchestrator start <pipeline>` — run a pipeline.
+- `codex-orchestrator flow --task <task-id>` — run `docs-review` then `implementation-gate` in sequence.
 - `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.

package/dist/bin/codex-orchestrator.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { opendir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import process from 'node:process';
 import { CodexOrchestrator } from '../orchestrator/src/cli/orchestrator.js';
@@ -44,6 +44,9 @@ async function main() {
             case 'frontend-test':
                 await handleFrontendTest(orchestrator, args);
                 break;
+            case 'flow':
+                await handleFlow(orchestrator, args);
+                break;
             case 'plan':
                 await handlePlan(orchestrator, args);
                 break;
@@ -145,6 +148,132 @@ function resolveTargetStageId(flags) {
     }
     return undefined;
 }
+const FLOW_TARGET_PIPELINE_SCOPES = new Set(['docs-review', 'implementation-gate']);
+function isFlowTargetPipelineScope(scope) {
+    return FLOW_TARGET_PIPELINE_SCOPES.has(scope);
+}
+function normalizeFlowTargetToken(candidate) {
+    const trimmed = candidate.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const tokens = trimmed.split(':');
+    if (tokens.length > 1 && !(tokens[0] ?? '').trim()) {
+        return null;
+    }
+    let scoped = false;
+    let scopeToken = null;
+    let suffixToken = trimmed;
+    if (tokens.length > 1) {
+        const candidateScope = (tokens[0] ?? '').trim().toLowerCase();
+        if (isFlowTargetPipelineScope(candidateScope)) {
+            scoped = true;
+            scopeToken = candidateScope;
+            suffixToken = (tokens[tokens.length - 1] ?? '').trim();
+        }
+    }
+    if (!suffixToken) {
+        return null;
+    }
+    return {
+        literal: trimmed,
+        literalLower: trimmed.toLowerCase(),
+        stageTokenLower: suffixToken.toLowerCase(),
+        scopeLower: scopeToken,
+        scoped
+    };
+}
+function flowPlanItemPipelineId(item) {
+    const metadataPipelineId = item.metadata && typeof item.metadata['pipelineId'] === 'string'
+        ? item.metadata['pipelineId'].trim().toLowerCase()
+        : '';
+    if (metadataPipelineId) {
+        return metadataPipelineId;
+    }
+    const delimiterIndex = item.id.indexOf(':');
+    if (delimiterIndex <= 0) {
+        return null;
+    }
+    return item.id.slice(0, delimiterIndex).trim().toLowerCase() || null;
+}
+function flowPlanItemMatchesTarget(item, candidate) {
+    const normalized = normalizeFlowTargetToken(candidate);
+    if (!normalized) {
+        return false;
+    }
+    if (item.id.toLowerCase() === normalized.literalLower) {
+        return true;
+    }
+    if (normalized.scoped && normalized.scopeLower) {
+        const itemPipelineId = flowPlanItemPipelineId(item);
+        if (itemPipelineId && itemPipelineId !== normalized.scopeLower) {
+            return false;
+        }
+    }
+    const metadataStageId = item.metadata && typeof item.metadata['stageId'] === 'string'
+        ? item.metadata['stageId'].toLowerCase()
+        : null;
+    const aliases = Array.isArray(item.metadata?.['aliases'])
+        ? item.metadata?.['aliases']
+        : [];
+    const aliasTokens = aliases.filter((alias) => typeof alias === 'string')
+        .map((alias) => alias.toLowerCase());
+    if (normalized.scoped) {
+        if (metadataStageId
+            && (metadataStageId === normalized.literalLower || metadataStageId === normalized.stageTokenLower)) {
+            return true;
+        }
+        return aliasTokens.some((alias) => alias === normalized.literalLower || alias === normalized.stageTokenLower);
+    }
+    if (item.id.toLowerCase().endsWith(`:${normalized.stageTokenLower}`)) {
+        return true;
+    }
+    if (metadataStageId
+        && (metadataStageId === normalized.stageTokenLower
+            || metadataStageId.endsWith(`:${normalized.stageTokenLower}`))) {
+        return true;
+    }
+    return aliasTokens.some((alias) => alias === normalized.stageTokenLower || alias.endsWith(`:${normalized.stageTokenLower}`));
+}
+function planIncludesStageId(plan, stageId) {
+    if (!stageId.trim()) {
+        return false;
+    }
+    return plan.plan.items.some((item) => flowPlanItemMatchesTarget(item, stageId));
+}
+function resolveFlowTargetScope(stageId) {
+    const delimiterIndex = stageId.indexOf(':');
+    if (delimiterIndex <= 0) {
+        return null;
+    }
+    const scope = stageId.slice(0, delimiterIndex).trim().toLowerCase();
+    if (!isFlowTargetPipelineScope(scope)) {
+        return null;
+    }
+    return scope;
+}
+async function resolveFlowTargetStageSelection(orchestrator, taskId, requestedTargetStageId) {
+    if (!requestedTargetStageId) {
+        return {};
+    }
+    const [docsPlan, implementationPlan] = (await Promise.all([
+        orchestrator.plan({ pipelineId: 'docs-review', taskId }),
+        orchestrator.plan({ pipelineId: 'implementation-gate', taskId })
+    ]));
+    const requestedScope = resolveFlowTargetScope(requestedTargetStageId);
+    const docsScopeMatch = !requestedScope || requestedScope === 'docs-review';
+    const implementationScopeMatch = !requestedScope || requestedScope === 'implementation-gate';
+    const docsReviewTargetStageId = docsScopeMatch && planIncludesStageId(docsPlan, requestedTargetStageId)
+        ? requestedTargetStageId
+        : undefined;
+    const implementationGateTargetStageId = implementationScopeMatch && planIncludesStageId(implementationPlan, requestedTargetStageId)
+        ? requestedTargetStageId
+        : undefined;
+    if (!docsReviewTargetStageId && !implementationGateTargetStageId) {
+        throw new Error(`Target stage "${requestedTargetStageId}" is not defined in docs-review or implementation-gate.`);
+    }
+    return { docsReviewTargetStageId, implementationGateTargetStageId };
+}
 function readStringFlag(flags, key) {
     const value = flags[key];
     if (typeof value !== 'string') {
@@ -313,6 +442,84 @@ async function handleFrontendTest(orchestrator, rawArgs) {
         }
     }
 }
+async function handleFlow(orchestrator, rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        printFlowHelp();
+        return;
+    }
+    if (positionals.length > 0) {
+        throw new Error(`flow does not accept positional arguments: ${positionals.join(' ')}`);
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const executionMode = resolveExecutionModeFlag(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;
+            if (format === 'json') {
+                const payload = {
+                    status: docsReviewResult.manifest.status,
+                    failed_stage: 'docs-review',
+                    docs_review: docsPayload,
+                    implementation_gate: null
+                };
+                console.log(JSON.stringify(payload, null, 2));
+            }
+            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));
+            if (implementationGateResult.manifest.status !== 'succeeded') {
+                process.exitCode = 1;
+            }
+            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.');
+    });
+}
 async function handlePlan(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const pipelineId = positionals[0];
@@ -464,14 +671,7 @@ async function withRunUi(flags, format, action) {
     }
 }
 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,
-        summary: result.manifest.summary ?? null
-    };
+    const payload = toRunOutputPayload(result);
     if (format === 'json') {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -487,6 +687,16 @@ function emitRunOutput(result, format, label) {
         }
     }
 }
+function toRunOutputPayload(result) {
+    return {
+        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,
+        summary: result.manifest.summary ?? null
+    };
+}
 async function handleExec(rawArgs) {
     const parsed = parseExecArgs(rawArgs);
     if (parsed.commandTokens.length === 0) {
@@ -519,6 +729,55 @@ async function handleExec(rawArgs) {
     else if (result.status !== 'succeeded') {
         process.exitCode = 1;
     }
+    if (outputMode === 'interactive') {
+        await maybeEmitExecAdoptionHint(env.taskId);
+    }
+}
+async function shouldScanExecAdoptionHint(taskFilter) {
+    if (!taskFilter) {
+        return false;
+    }
+    const env = resolveEnvironmentPaths();
+    const taskCliRunsRoot = join(env.runsRoot, taskFilter, 'cli');
+    let handle = null;
+    try {
+        handle = await opendir(taskCliRunsRoot);
+        let runCount = 0;
+        for await (const entry of handle) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            runCount += 1;
+            if (runCount > 150) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (handle) {
+            await handle.close().catch(() => undefined);
+        }
+    }
+}
+async function maybeEmitExecAdoptionHint(taskFilter) {
+    try {
+        if (!(await shouldScanExecAdoptionHint(taskFilter))) {
+            return;
+        }
+        const usage = await runDoctorUsage({ windowDays: 7, taskFilter });
+        const recommendation = usage.adoption.recommendations[0];
+        if (!recommendation) {
+            return;
+        }
+        console.log(`Adoption hint: ${recommendation}`);
+    }
+    catch {
+        // Exec command behavior should not fail when usage telemetry cannot be read.
+    }
 }
 async function handleSelfCheck(rawArgs) {
     const { flags } = parseArgs(rawArgs);
@@ -599,6 +858,7 @@ Options:
         throw new Error('No bundled skills detected; cannot run setup.');
     }
     const forceSkills = bundledSkills.filter((skill) => skill !== 'chrome-devtools');
+    const guidance = buildSetupGuidance();
     if (!apply) {
         const forceOnly = forceSkills.join(',');
         const forceCommand = forceOnly ? `codex-orchestrator skills install --force --only ${forceOnly}` : null;
@@ -615,7 +875,8 @@ Options:
                     note: 'Installs bundled skills into $CODEX_HOME/skills (setup avoids overwriting chrome-devtools when already present).'
                 },
                 delegation,
-                devtools
+                devtools,
+                guidance
             }
         };
         if (format === 'json') {
@@ -629,6 +890,9 @@ Options:
         }
         console.log(`- Delegation: codex-orchestrator delegation setup --yes${delegationRepoArg}`);
         console.log('- DevTools: codex-orchestrator devtools setup --yes');
+        for (const line of formatSetupGuidanceSummary(guidance)) {
+            console.log(line);
+        }
         console.log('Run with --yes to apply this setup.');
         return;
     }
@@ -659,8 +923,41 @@ Options:
     for (const line of formatDevtoolsSetupSummary(devtools)) {
         console.log(line);
     }
+    for (const line of formatSetupGuidanceSummary(guidance)) {
+        console.log(line);
+    }
     console.log('Next: codex-orchestrator doctor --usage');
 }
+function buildSetupGuidance() {
+    return {
+        note: 'Agent-first default: run docs-review before implementation and implementation-gate before handoff.',
+        references: [
+            'https://github.com/Kbediako/CO#downstream-usage-cheatsheet-agent-first',
+            'https://github.com/Kbediako/CO/blob/main/docs/AGENTS.md',
+            'https://github.com/Kbediako/CO/blob/main/docs/guides/collab-vs-mcp.md'
+        ],
+        recommended_commands: [
+            'codex-orchestrator flow --task <task-id>',
+            'codex-orchestrator doctor --usage'
+        ]
+    };
+}
+function formatSetupGuidanceSummary(guidance) {
+    const lines = ['Setup guidance:', `- ${guidance.note}`];
+    if (guidance.recommended_commands.length > 0) {
+        lines.push('- Recommended commands:');
+        for (const command of guidance.recommended_commands) {
+            lines.push(`  - ${command}`);
+        }
+    }
+    if (guidance.references.length > 0) {
+        lines.push('- References:');
+        for (const reference of guidance.references) {
+            lines.push(`  - ${reference}`);
+        }
+    }
+    return lines;
+}
 async function handleDoctor(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
@@ -1159,6 +1456,17 @@ Commands:
     --interactive | --ui    Enable read-only HUD when running in a TTY.
     --no-interactive        Force disable HUD (default is off unless requested).
 
+  flow                      Run docs-review then implementation-gate sequentially.
+    --task <id>             Override task identifier (defaults to MCP_RUNNER_TASK_ID).
+    --parent-run <id>       Link docs-review run to parent run id.
+    --approval-policy <p>   Record approval policy metadata.
+    --format json           Emit machine-readable output summary for both runs.
+    --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).
+    --interactive | --ui    Enable read-only HUD when running in a TTY.
+    --no-interactive        Force disable HUD (default is off unless requested).
+
   plan [pipeline]           Preview pipeline stages without executing.
     --task <id>             Override task identifier.
     --format json           Emit machine-readable output.
@@ -1324,3 +1632,20 @@ Options:
   --help                  Show this message.
 `);
 }
+function printFlowHelp() {
+    console.log(`Usage: codex-orchestrator flow [options]
+
+Runs docs-review first, then implementation-gate. Stops on the first failure.
+
+Options:
+  --task <id>               Override task identifier.
+  --parent-run <id>         Link docs-review run to parent run id.
+  --approval-policy <p>     Record approval policy metadata.
+  --format json             Emit machine-readable output for both runs.
+  --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).
+  --interactive | --ui      Enable read-only HUD when running in a TTY.
+  --no-interactive          Force disable HUD.
+`);
+}

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

@@ -132,6 +132,18 @@ export async function runDoctorUsage(options = {}) {
         .sort((a, b) => b[1] - a[1])
         .slice(0, 10)
         .map(([id, runs]) => ({ id, runs }));
+    const execRuns = pipelines.get('exec') ?? 0;
+    const gateRuns = (pipelines.get('docs-review') ?? 0) + (pipelines.get('implementation-gate') ?? 0);
+    const execSharePct = statusCounts.total > 0 ? Math.round((execRuns / statusCounts.total) * 1000) / 10 : 0;
+    const gateSharePct = statusCounts.total > 0 ? Math.round((gateRuns / statusCounts.total) * 1000) / 10 : 0;
+    const adoptionRecommendations = buildAdoptionRecommendations({
+        totalRuns: statusCounts.total,
+        execRuns,
+        gateRuns,
+        rlmRuns,
+        cloudRuns,
+        collabRunsWithToolCalls
+    });
     const delegationErrors = [];
     let activeWithSubagents = 0;
     let totalSubagentManifests = 0;
@@ -193,6 +205,13 @@ export async function runDoctorUsage(options = {}) {
         pipelines: {
             total: pipelines.size,
             top: pipelineTop
+        },
+        adoption: {
+            exec_runs: execRuns,
+            exec_share_pct: execSharePct,
+            gate_runs: gateRuns,
+            gate_share_pct: gateSharePct,
+            recommendations: adoptionRecommendations
         }
     };
 }
@@ -235,6 +254,14 @@ export function formatDoctorUsageSummary(result) {
             lines.push(`  - ${entry.id}: ${entry.runs}`);
         }
     }
+    lines.push(`Pipeline adoption: exec=${result.adoption.exec_runs} (${result.adoption.exec_share_pct}%), ` +
+        `docs-review+implementation-gate=${result.adoption.gate_runs} (${result.adoption.gate_share_pct}%)`);
+    if (result.adoption.recommendations.length > 0) {
+        lines.push('Adoption hints:');
+        for (const recommendation of result.adoption.recommendations) {
+            lines.push(`  - ${recommendation}`);
+        }
+    }
     if (result.delegation.errors.length > 0) {
         lines.push('Delegation scan warnings:');
         for (const warning of result.delegation.errors.slice(0, 3)) {
@@ -243,6 +270,29 @@ export function formatDoctorUsageSummary(result) {
     }
     return lines;
 }
+function buildAdoptionRecommendations(params) {
+    if (params.totalRuns <= 0) {
+        return [];
+    }
+    const hints = [];
+    const execShare = params.execRuns / params.totalRuns;
+    if (execShare >= 0.6) {
+        hints.push('Most runs are plain exec; prefer `codex-orchestrator start docs-review` or `start implementation-gate` for manifest-backed guardrails.');
+    }
+    if (params.gateRuns === 0) {
+        hints.push('No gate pipelines detected; use docs-review before implementation and implementation-gate before handoff.');
+    }
+    if (params.rlmRuns === 0) {
+        hints.push('No RLM runs detected; try `codex-orchestrator rlm --collab auto "<goal>"` for long-horizon or ambiguous tasks.');
+    }
+    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 collab is enabled (`codex features enable collab`).');
+    }
+    return hints.slice(0, 3);
+}
 function extractRunIdFromManifestPath(manifestPath) {
     if (!manifestPath) {
         return null;

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

@@ -9,6 +9,7 @@ import { resolveEnvironmentPaths } from '../../../scripts/lib/run-manifests.js';
 import { normalizeEnvironmentPaths } from './run/environment.js';
 import { bootstrapManifest, loadManifest, updateHeartbeat, finalizeStatus, appendSummary, ensureGuardrailStatus, resetForResume, recordResumeEvent } from './run/manifest.js';
 import { ManifestPersister, persistManifest } from './run/manifestPersister.js';
+import { resolveRuntimeActivitySnapshot } from './run/runtimeActivity.js';
 import { generateRunId } from './utils/runId.js';
 import { runCommandStage } from './services/commandRunner.js';
 import { appendMetricsEntry } from './metrics/metricsRecorder.js';
@@ -437,12 +438,13 @@ export class CodexOrchestrator {
     async status(options) {
         const env = this.baseEnv;
         const { manifest, paths } = await loadManifest(env, options.runId);
+        const activity = await resolveRuntimeActivitySnapshot(manifest, paths);
         if (options.format === 'json') {
-            const payload = this.buildStatusPayload(env, manifest, paths);
+            const payload = this.buildStatusPayload(env, manifest, paths, activity);
             process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
             return manifest;
         }
-        this.renderStatus(manifest);
+        this.renderStatus(manifest, activity);
         return manifest;
     }
     async plan(options = {}) {
@@ -1121,7 +1123,7 @@ export class CodexOrchestrator {
             throw new Error('Resume token mismatch.');
         }
     }
-    buildStatusPayload(env, manifest, paths) {
+    buildStatusPayload(env, manifest, paths, activity) {
         return {
             run_id: manifest.run_id,
             status: manifest.status,
@@ -1132,17 +1134,24 @@ export class CodexOrchestrator {
             artifact_root: manifest.artifact_root,
             log_path: manifest.log_path,
             heartbeat_at: manifest.heartbeat_at,
+            activity,
             commands: manifest.commands,
             child_runs: manifest.child_runs,
             cloud_execution: manifest.cloud_execution ?? null
         };
     }
-    renderStatus(manifest) {
+    renderStatus(manifest, activity) {
         logger.info(`Run: ${manifest.run_id}`);
         logger.info(`Status: ${manifest.status}${manifest.status_detail ? ` (${manifest.status_detail})` : ''}`);
         logger.info(`Started: ${manifest.started_at}`);
         logger.info(`Completed: ${manifest.completed_at ?? 'in-progress'}`);
         logger.info(`Manifest: ${manifest.artifact_root}/manifest.json`);
+        if (activity.observed_at) {
+            const staleSuffix = activity.stale === null ? '' : activity.stale ? ' [stale]' : ' [active]';
+            const sourceLabel = activity.observed_source ? ` via ${activity.observed_source}` : '';
+            const ageLabel = activity.age_seconds === null ? '' : ` age=${activity.age_seconds}s`;
+            logger.info(`Activity: ${activity.observed_at}${sourceLabel}${ageLabel}${staleSuffix}`);
+        }
         if (manifest.cloud_execution?.task_id) {
             logger.info(`Cloud: ${manifest.cloud_execution.task_id} [${manifest.cloud_execution.status}]` +
                 (manifest.cloud_execution.status_url ? ` ${manifest.cloud_execution.status_url}` : ''));

package/dist/orchestrator/src/cli/run/runtimeActivity.js

@@ -0,0 +1,79 @@
+import { readFile, stat } from 'node:fs/promises';
+export async function resolveRuntimeActivitySnapshot(manifest, paths, options = {}) {
+    const manifestHeartbeat = normalizeTimestamp(manifest.heartbeat_at);
+    const heartbeatFileAt = await readHeartbeatTimestamp(paths.heartbeatPath);
+    const runnerLogMtime = await readMtimeIso(paths.logPath);
+    const candidates = [];
+    if (manifestHeartbeat) {
+        candidates.push({ source: 'manifest', ...manifestHeartbeat });
+    }
+    const heartbeatCandidate = normalizeTimestamp(heartbeatFileAt);
+    if (heartbeatCandidate) {
+        candidates.push({ source: 'heartbeat_file', ...heartbeatCandidate });
+    }
+    const logCandidate = normalizeTimestamp(runnerLogMtime);
+    if (logCandidate) {
+        candidates.push({ source: 'runner_log', ...logCandidate });
+    }
+    const latest = pickLatest(candidates);
+    const nowMs = Number.isFinite(options.nowMs) ? Number(options.nowMs) : Date.now();
+    const staleThresholdSeconds = Number.isFinite(manifest.heartbeat_stale_after_seconds) && manifest.heartbeat_stale_after_seconds > 0
+        ? Math.floor(manifest.heartbeat_stale_after_seconds)
+        : null;
+    let stale = null;
+    let ageSeconds = null;
+    if (manifest.status === 'in_progress' && latest && staleThresholdSeconds !== null) {
+        ageSeconds = Math.max(0, Math.floor((nowMs - latest.ms) / 1000));
+        stale = ageSeconds > staleThresholdSeconds;
+    }
+    return {
+        manifest_heartbeat_at: manifestHeartbeat?.iso ?? null,
+        heartbeat_file_at: heartbeatCandidate?.iso ?? null,
+        runner_log_mtime_at: logCandidate?.iso ?? null,
+        observed_at: latest?.iso ?? null,
+        observed_source: latest?.source ?? null,
+        stale,
+        stale_threshold_seconds: staleThresholdSeconds,
+        age_seconds: ageSeconds
+    };
+}
+async function readHeartbeatTimestamp(heartbeatPath) {
+    try {
+        const raw = await readFile(heartbeatPath, 'utf8');
+        const trimmed = raw.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readMtimeIso(filePath) {
+    try {
+        const fileStat = await stat(filePath);
+        return fileStat.mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeTimestamp(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const ms = Date.parse(trimmed);
+    if (!Number.isFinite(ms)) {
+        return null;
+    }
+    return { iso: new Date(ms).toISOString(), ms };
+}
+function pickLatest(candidates) {
+    if (candidates.length === 0) {
+        return null;
+    }
+    candidates.sort((a, b) => b.ms - a.ms);
+    return candidates[0] ?? null;
+}

package/dist/orchestrator/src/cli/services/commandRunner.js

@@ -171,7 +171,6 @@ export async function runCommandStage(context, hooks = {}) {
         try {
             result = await runner.run({
                 command: stage.command,
-                args: [],
                 cwd: stage.cwd ?? env.repoRoot,
                 env: execEnv,
                 sessionId: sessionId ?? undefined,

package/dist/orchestrator/src/cli/services/execRuntime.js

@@ -19,10 +19,13 @@ const sessionManager = new ExecSessionManager({
 const privacyGuard = new PrivacyGuard({ mode: resolvePrivacyGuardMode() });
 const handleService = new RemoteExecHandleService({ guard: privacyGuard, now: () => new Date() });
 const cliExecutor = async (request) => {
+    const hasExplicitArgs = Array.isArray(request.args);
     const child = spawn(request.command, request.args ?? [], {
         cwd: request.cwd,
         env: request.env,
-        shell: true,
+        // Use shell mode only for string-style commands. When args are provided we
+        // want argv semantics (`cmd arg1 arg2`) rather than `sh -c cmd` behavior.
+        shell: !hasExplicitArgs,
         stdio: ['ignore', 'pipe', 'pipe']
     });
     if (!child.stdout || !child.stderr) {

package/dist/packages/orchestrator/src/exec/unified-exec.js

@@ -27,7 +27,8 @@ export class UnifiedExecRunner {
         };
     }
     async run(options) {
-        const args = options.args ?? [];
+        const args = options.args;
+        const resolvedArgs = args ?? [];
         const invocationId = options.invocationId ?? this.idGenerator();
         const correlationId = this.idGenerator();
         const issuedHandle = this.handleService ? this.handleService.issueHandle(correlationId) : undefined;
@@ -49,7 +50,7 @@ export class UnifiedExecRunner {
         const metadata = {
             ...options.metadata,
             command: options.command,
-            args,
+            args: resolvedArgs,
             cwd: options.cwd,
             sessionId: lease.id,
             correlationId,
@@ -81,7 +82,7 @@ export class UnifiedExecRunner {
                         attempt,
                         correlationId,
                         command: options.command,
-                        args,
+                        args: resolvedArgs,
                         cwd: options.cwd,
                         sandboxState,
                         sessionId: lease.id,
@@ -403,7 +404,7 @@ function getErrorMessage(error) {
     return String(error);
 }
 const defaultExecutor = async (request) => {
-    const child = spawn(request.command, request.args, {
+    const child = spawn(request.command, request.args ?? [], {
         cwd: request.cwd,
         env: request.env,
         stdio: ['ignore', 'pipe', 'pipe']

package/dist/scripts/lib/pr-watch-merge.js

@@ -15,6 +15,12 @@ const REQUIRED_BUCKET_FAILED = new Set(['fail', 'cancel', 'skipping']);
 const MERGEABLE_STATES = new Set(['CLEAN', 'HAS_HOOKS', 'UNSTABLE']);
 const BLOCKED_REVIEW_DECISIONS = new Set(['CHANGES_REQUESTED', 'REVIEW_REQUIRED']);
 const DO_NOT_MERGE_LABEL = /do[\s_-]*not[\s_-]*merge/i;
+const ACTIONABLE_BOT_LOGINS = new Set([
+    'chatgpt-codex-connector',
+    'chatgpt-codex-connector[bot]',
+    'coderabbitai',
+    'coderabbitai[bot]'
+]);
 const PR_QUERY = `
 query($owner:String!, $repo:String!, $number:Int!) {
   repository(owner:$owner, name:$repo) {
@@ -73,6 +79,29 @@ function normalizeEnum(value) {
 function normalizeBucket(value) {
     return typeof value === 'string' ? value.trim().toLowerCase() : '';
 }
+function normalizeLogin(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function isActionableBot(login) {
+    return ACTIONABLE_BOT_LOGINS.has(normalizeLogin(login));
+}
+export function isHumanReviewActor(user) {
+    if (!user || typeof user !== 'object') {
+        return false;
+    }
+    const login = normalizeLogin(user.login);
+    if (!login) {
+        return false;
+    }
+    if (isActionableBot(login)) {
+        return false;
+    }
+    const accountType = typeof user.type === 'string' ? user.type.trim().toUpperCase() : '';
+    if (accountType) {
+        return accountType === 'USER';
+    }
+    return !login.endsWith('[bot]');
+}
 function formatDuration(ms) {
     if (ms <= 0) {
         return '0s';
@@ -218,6 +247,15 @@ async function runGhJson(args) {
         throw new Error(`Failed to parse JSON from gh ${args.join(' ')}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+async function runGhJsonSlurped(args) {
+    const result = await runGh([...args, '--paginate', '--slurp']);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse paginated JSON from gh ${args.join(' ')}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 async function ensureGhAuth() {
     const result = await runGh(['auth', 'status', '-h', 'github.com'], { allowFailure: true });
     if (result.exitCode !== 0) {
@@ -378,7 +416,7 @@ export function resolveCachedRequiredChecksSummary(previousCache, currentHeadOid
     }
     return hasRequiredChecksSummary(previousCache.summary) ? previousCache.summary : null;
 }
-export function buildStatusSnapshot(response, requiredChecks = null) {
+export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFeedback = null) {
     const pr = response?.data?.repository?.pullRequest;
     if (!pr) {
         throw new Error('GraphQL response missing pullRequest payload.');
@@ -391,10 +429,15 @@ export function buildStatusSnapshot(response, requiredChecks = null) {
     const hasDoNotMergeLabel = labels.some((label) => DO_NOT_MERGE_LABEL.test(label));
     const threads = Array.isArray(pr.reviewThreads?.nodes) ? pr.reviewThreads.nodes : [];
     const unresolvedThreadCount = threads.filter((thread) => thread && !thread.isResolved && !thread.isOutdated).length;
+    const hasUnresolvedThread = unresolvedThreadCount > 0;
     const contexts = pr.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts?.nodes;
     const checkNodes = Array.isArray(contexts) ? contexts : [];
     const checks = summarizeChecks(checkNodes);
     const requiredCheckSummary = requiredChecks && typeof requiredChecks === 'object' && requiredChecks.total > 0 ? requiredChecks : null;
+    const unacknowledgedBotFeedbackCount = inlineBotFeedback && typeof inlineBotFeedback.unacknowledgedCount === 'number'
+        ? inlineBotFeedback.unacknowledgedCount
+        : 0;
+    const botFeedbackFetchError = inlineBotFeedback?.fetchError === true;
     const gateChecks = requiredCheckSummary ?? checks;
     const gateChecksSource = requiredCheckSummary ? 'required' : 'rollup';
     const reviewDecision = normalizeEnum(pr.reviewDecision);
@@ -422,9 +465,15 @@ export function buildStatusSnapshot(response, requiredChecks = null) {
     if (BLOCKED_REVIEW_DECISIONS.has(reviewDecision)) {
         gateReasons.push(`review=${reviewDecision}`);
     }
-    if (unresolvedThreadCount > 0) {
+    if (hasUnresolvedThread) {
         gateReasons.push(`unresolved_threads=${unresolvedThreadCount}`);
     }
+    if (botFeedbackFetchError) {
+        gateReasons.push('bot_feedback=unknown');
+    }
+    else if (unacknowledgedBotFeedbackCount > 0) {
+        gateReasons.push(`unacknowledged_bot_feedback=${unacknowledgedBotFeedbackCount}`);
+    }
     return {
         number: Number(pr.number),
         url: typeof pr.url === 'string' ? pr.url : null,
@@ -437,6 +486,8 @@ export function buildStatusSnapshot(response, requiredChecks = null) {
         labels,
         hasDoNotMergeLabel,
         unresolvedThreadCount,
+        unacknowledgedBotFeedbackCount,
+        botFeedbackFetchError,
         checks,
         requiredChecks: requiredCheckSummary,
         gateChecksSource,
@@ -467,6 +518,8 @@ function formatStatusLine(snapshot, quietRemainingMs) {
         `required_checks_pending=${requiredChecks ? requiredChecks.pending.length : 'n/a'}`,
         `required_checks_failed=${requiredChecks ? requiredChecks.failed.length : 'n/a'}`,
         `unresolved_threads=${snapshot.unresolvedThreadCount}`,
+        `unack_bot_feedback=${snapshot.unacknowledgedBotFeedbackCount}`,
+        `bot_feedback_fetch_error=${snapshot.botFeedbackFetchError ? 'yes' : 'no'}`,
         `quiet_remaining=${formatDuration(quietRemainingMs)}`,
         `blocked_by=${reasons}`,
         `pending=[${pendingNames}]`,
@@ -501,6 +554,77 @@ async function fetchRequiredChecks(owner, repo, prNumber) {
         };
     }
 }
+function flattenReviewCommentPages(pagesPayload) {
+    if (!Array.isArray(pagesPayload)) {
+        return [];
+    }
+    const comments = [];
+    for (const page of pagesPayload) {
+        if (Array.isArray(page)) {
+            comments.push(...page);
+            continue;
+        }
+        if (page && typeof page === 'object') {
+            comments.push(page);
+        }
+    }
+    return comments;
+}
+async function fetchInlineBotFeedback(owner, repo, prNumber, headOid) {
+    if (!headOid) {
+        return { fetchError: false, unacknowledgedCount: 0 };
+    }
+    try {
+        const pagedPayload = await runGhJsonSlurped([
+            'api',
+            `repos/${owner}/${repo}/pulls/${prNumber}/comments`
+        ]);
+        const comments = flattenReviewCommentPages(pagedPayload);
+        const repliesByParentId = new Map();
+        for (const comment of comments) {
+            if (!comment || typeof comment !== 'object') {
+                continue;
+            }
+            const parentId = Number(comment.in_reply_to_id);
+            if (!Number.isInteger(parentId) || parentId <= 0) {
+                continue;
+            }
+            const bucket = repliesByParentId.get(parentId) ?? [];
+            bucket.push(comment);
+            repliesByParentId.set(parentId, bucket);
+        }
+        let unacknowledgedCount = 0;
+        for (const comment of comments) {
+            if (!comment || typeof comment !== 'object') {
+                continue;
+            }
+            const commentId = Number(comment.id);
+            if (!Number.isInteger(commentId) || commentId <= 0) {
+                continue;
+            }
+            if (comment.in_reply_to_id !== null && comment.in_reply_to_id !== undefined) {
+                continue;
+            }
+            if (!isActionableBot(comment.user?.login)) {
+                continue;
+            }
+            const commitId = typeof comment.commit_id === 'string' ? comment.commit_id : null;
+            const originalCommitId = typeof comment.original_commit_id === 'string' ? comment.original_commit_id : null;
+            if (commitId !== headOid && originalCommitId !== headOid) {
+                continue;
+            }
+            const replies = repliesByParentId.get(commentId) ?? [];
+            const hasHumanReply = replies.some((reply) => isHumanReviewActor(reply?.user));
+            if (!hasHumanReply) {
+                unacknowledgedCount += 1;
+            }
+        }
+        return { fetchError: false, unacknowledgedCount };
+    }
+    catch {
+        return { fetchError: true, unacknowledgedCount: 0 };
+    }
+}
 async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache = null) {
     const response = await runGhJson([
         'api',
@@ -518,8 +642,9 @@ async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache
     const previousRequiredChecks = resolveCachedRequiredChecksSummary(previousRequiredChecksCache, currentHeadOid);
     const requiredChecksResult = await fetchRequiredChecks(owner, repo, prNumber);
     const requiredChecks = resolveRequiredChecksSummary(requiredChecksResult.summary, previousRequiredChecks, requiredChecksResult.fetchError);
+    const inlineBotFeedback = await fetchInlineBotFeedback(owner, repo, prNumber, currentHeadOid);
     return {
-        snapshot: buildStatusSnapshot(response, requiredChecks),
+        snapshot: buildStatusSnapshot(response, requiredChecks, inlineBotFeedback),
         requiredChecksForNextPoll: requiredChecks
             ? {
                 headOid: currentHeadOid,

package/docs/README.md

@@ -101,7 +101,8 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 ## Companion Package Commands
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (includes `mcp-client.json` and `AGENTS.md`; no overwrite unless `--force`).
-- `codex-orchestrator setup [--yes]`: one-shot bootstrap for downstream users (installs bundled skills and configures delegation + DevTools wiring).
+- `codex-orchestrator setup [--yes]`: one-shot bootstrap for downstream users (installs bundled skills, configures delegation + DevTools wiring, and prints policy/usage guidance).
+- `codex-orchestrator flow [--task <task-id>]`: runs `docs-review` then `implementation-gate` in sequence; stops on the first failure.
 - `codex-orchestrator doctor [--format json] [--usage] [--apply]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`). `--apply` plans/applies quick fixes (use with `--yes`).
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
 - `codex-orchestrator delegation setup [--yes]`: configure delegation MCP wiring (`--yes` applies `codex mcp add ...`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/collab-subagents-first/SKILL.md

@@ -52,6 +52,19 @@ Skip subagents when all conditions are true:
 - Include objective, scope, constraints, acceptance criteria, and expected output format.
 - Require concise summaries and evidence paths; avoid long logs in chat.
 
+4a) Declare write policy and track ownership against git status
+- Capture a baseline before spawning: `git status --porcelain`.
+- Declare each stream as either:
+  - `read-only` (research/scout/review), or
+  - `write-enabled` (implementation/tests).
+- For `read-only` streams, include an explicit "no file edits" constraint.
+- After each `wait`, compare status against baseline and map changed files to stream ownership.
+- Treat in-scope edits from active write-enabled streams as expected delegated output.
+- Escalate only for out-of-scope changes, overlapping ownership collisions, or edits appearing without an active stream owner.
+- If the agent surfaces a generic "unexpected local edits" pause prompt, treat it as a classification step: keep and continue when edits are in-scope; escalate only violations.
+- Prefer the built-in helper when available (`node scripts/subagent-edit-guard.mjs ...`); canonical command examples live in `docs/delegation-runner-workflow.md` (section `3a`). If the helper is not present in the current repo, use the same baseline/scope logic manually.
+- If `finish` exits non-zero, escalate only the reported `out_of_scope_paths` / `violations`.
+
 5) Run streams in parallel when independent
 - Spawn multiple subagents for independent streams.
 - Wait for all subagents to finish before final synthesis.
@@ -159,6 +172,7 @@ Do not treat wrapper handoff-only output as a completed review.
 - Do not skip delegation solely because there is only one implementation stream; single-stream delegation is valid for context offload.
 - Do not rely on human-readable agent names in TUI labels for control flow; use stream ownership and evidence paths as source of truth.
 - Do not end the parent work with unclosed collab agent ids.
+- Do not treat every delegated edit as "unexpected"; first verify whether the edit belongs to an active stream owner.
 
 ## Completion checklist
 

package/skills/collab-subagents-first/references/subagent-brief-template.md

@@ -30,6 +30,7 @@ Out of scope:
 Ownership:
 - Files/paths you may edit: <paths>
 - Files/paths you must not edit: <paths>
+- Write policy: read-only | write-enabled
 
 Acceptance criteria:
 - <bullet 1>
@@ -59,6 +60,7 @@ Keep the response concise. Put detailed notes in a file and return the path.
 
 - Include enough context so the subagent can act without back-and-forth.
 - Include explicit file ownership boundaries.
+- Include explicit write policy (`read-only` or `write-enabled`).
 - Include a concrete output format and validation expectations.
 - Include at least one "do not do" constraint to prevent drift.
 - If task is review-only, explicitly prohibit implementation edits.
@@ -87,4 +89,3 @@ Objective: validate <existing change>.
 Deliverable: failing/passing checks, defect list by severity, and minimal fix suggestions.
 No broad refactors.
 ```
-

package/skills/delegation-usage/SKILL.md

@@ -23,6 +23,12 @@ Collab multi-agent mode is separate from delegation. For symbolic RLM subcalls t
 - **Lifecycle is mandatory:** for every successful `spawn_agent`, run `wait` and then `close_agent` for that same id before task completion.
 - Keep a local list of spawned ids and run a final cleanup pass so no agent id is left unclosed on timeout/error paths.
 - If spawn fails with `agent thread limit reached`, stop spawning, close any known ids first, then surface a concise recovery note.
+- In a shared checkout, spawned subagents may produce file edits. Treat edits inside that stream's declared ownership as expected delegated output, not external interference.
+- Before spawning, capture a baseline (`git status --porcelain`). After `wait`, diff against baseline and classify file changes by stream ownership.
+- Escalate "unexpected local edits" only when changed files are outside all active stream scopes (or when no subagent was active).
+- If a generic safety prompt appears after delegation (for example "unexpected local edits"), run scope classification first; when edits are in-scope, keep them and continue without user escalation.
+- For scout/research streams, set an explicit no-write constraint and verify the post-run status matches baseline.
+- Prefer `scripts/subagent-edit-guard.mjs` for low-friction enforcement when the helper exists in the repo (`start` before spawn, `finish` after `wait`); canonical command examples live in `docs/delegation-runner-workflow.md` (section `3a`). If the helper is absent, apply the same baseline/scope checks manually.
 
 ## Quick-start workflow (canned)
 
@@ -186,3 +192,4 @@ repeat:
 - **Collab payload mismatch:** `spawn_agent` rejects calls that include both `message` and `items`.
 - **Collab UI assumptions:** agent rows/records are id-based today; use explicit stream role text in prompts/artifacts for operator clarity.
 - **Collab lifecycle leaks:** missing `close_agent` calls accumulate open threads and can trigger `agent thread limit reached`; always finish `spawn -> wait -> close_agent` per id.
+- **False "unexpected edits" stops:** when a live subagent owns the touched files, treat those edits as expected output and continue with scope-aware review.

package/skills/elegance-review/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: elegance-review
+description: Run an explicit post-implementation elegance/minimality pass to keep the smallest correct solution and remove avoidable complexity before handoff.
+---
+
+# Elegance Review
+
+## Overview
+
+Use this skill after non-trivial edits to verify the implementation is minimal, coherent, and easy to maintain. This is a simplification pass, not a feature-expansion pass.
+
+## Auto-trigger policy (required)
+
+Run this skill whenever any condition is true:
+- You changed behavior across about 2+ files.
+- You added a new helper/module/pathway and could possibly collapse it.
+- You finished addressing review feedback and are preparing to hand off.
+- You are about to recommend merge/release.
+- The user explicitly asks for elegance/minimality/overengineering checks.
+
+## Quick start
+
+Focused uncommitted review:
+```bash
+codex review --uncommitted "Find avoidable complexity, duplicate abstractions, and unnecessary indirection. Prioritize simplifications that preserve behavior."
+```
+
+Diff-vs-base review:
+```bash
+codex review --base <branch> "Focus on smallest viable design and maintenance cost."
+```
+
+## Workflow
+
+1) Lock invariants first
+- State what behavior cannot change.
+- Keep tests/acceptance criteria as the guardrail.
+
+2) Identify complexity hotspots
+- Unused abstractions, wrappers, or config layers.
+- Duplicate logic that can be consolidated safely.
+- Over-generalized interfaces used in one place only.
+- Extra branching/state that can be simplified.
+
+3) Simplify in smallest safe steps
+- Prefer deleting code over adding knobs.
+- Collapse one-off abstractions into local logic when clearer.
+- Keep naming and control flow direct.
+
+4) Re-validate
+- Run targeted tests/lint for touched areas.
+- Confirm no behavior regressions.
+
+5) Record result
+- Report what was simplified.
+- Report residual complexity that is intentionally kept and why.
+
+## Guardrails
+
+- Do not broaden scope into unrelated refactors.
+- Do not trade readability for cleverness.
+- If `codex review` is unavailable, run a manual checklist using the same criteria and note that fallback.