@kbediako/codex-orchestrator 0.1.28 → 0.1.30

package/README.md

@@ -215,6 +215,7 @@ 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)
 
 ## RLM benchmark graphs
 

package/dist/bin/codex-orchestrator.js

@@ -1238,6 +1238,7 @@ Commands:
 Notes:
   RLM recursion guidance: docs/guides/rlm-recursion-v2.md
   Cloud-mode preflight/fallback guide: docs/guides/cloud-mode-preflight.md
+  Review artifacts guide: docs/guides/review-artifacts.md
 `);
 }
 void main();
@@ -1300,6 +1301,9 @@ Subcommands:
 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
+
+Guide:
+  Review artifacts (prompt + output log paths): docs/guides/review-artifacts.md
 `);
 }
 function printRlmHelp() {

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

@@ -9,6 +9,9 @@ const DEFAULT_MERGE_METHOD = 'squash';
 const CHECKRUN_PASS_CONCLUSIONS = new Set(['SUCCESS', 'SKIPPED', 'NEUTRAL']);
 const STATUS_CONTEXT_PASS_STATES = new Set(['SUCCESS']);
 const STATUS_CONTEXT_PENDING_STATES = new Set(['EXPECTED', 'PENDING']);
+const REQUIRED_BUCKET_PASS = new Set(['pass']);
+const REQUIRED_BUCKET_PENDING = new Set(['pending']);
+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;
@@ -67,6 +70,9 @@ query($owner:String!, $repo:String!, $number:Int!) {
 function normalizeEnum(value) {
     return typeof value === 'string' ? value.trim().toUpperCase() : '';
 }
+function normalizeBucket(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
 function formatDuration(ms) {
     if (ms <= 0) {
         return '0s';
@@ -299,7 +305,80 @@ function summarizeChecks(nodes) {
     }
     return summary;
 }
-function buildStatusSnapshot(response) {
+export function summarizeRequiredChecks(entries) {
+    const summary = {
+        total: 0,
+        successCount: 0,
+        pending: [],
+        failed: []
+    };
+    if (!Array.isArray(entries)) {
+        return summary;
+    }
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object') {
+            continue;
+        }
+        summary.total += 1;
+        const name = typeof entry.name === 'string' && entry.name.trim() ? entry.name.trim() : 'required-check';
+        const bucket = normalizeBucket(entry.bucket);
+        const state = normalizeEnum(entry.state);
+        const detailsUrl = typeof entry.link === 'string' ? entry.link : null;
+        if (REQUIRED_BUCKET_PASS.has(bucket)) {
+            summary.successCount += 1;
+            continue;
+        }
+        if (REQUIRED_BUCKET_PENDING.has(bucket)) {
+            summary.pending.push(name);
+            continue;
+        }
+        if (REQUIRED_BUCKET_FAILED.has(bucket)) {
+            summary.failed.push({
+                name,
+                state: state || bucket.toUpperCase() || 'UNKNOWN',
+                detailsUrl
+            });
+            continue;
+        }
+        if (STATUS_CONTEXT_PENDING_STATES.has(state)) {
+            summary.pending.push(name);
+            continue;
+        }
+        if (STATUS_CONTEXT_PASS_STATES.has(state)) {
+            summary.successCount += 1;
+            continue;
+        }
+        summary.failed.push({
+            name,
+            state: state || 'UNKNOWN',
+            detailsUrl
+        });
+    }
+    return summary;
+}
+function hasRequiredChecksSummary(summary) {
+    return Boolean(summary && typeof summary === 'object' && summary.total > 0);
+}
+export function resolveRequiredChecksSummary(freshSummary, previousSummary, fetchError = false) {
+    if (hasRequiredChecksSummary(freshSummary)) {
+        return freshSummary;
+    }
+    if (fetchError && hasRequiredChecksSummary(previousSummary)) {
+        return previousSummary;
+    }
+    return null;
+}
+export function resolveCachedRequiredChecksSummary(previousCache, currentHeadOid) {
+    if (!previousCache || typeof previousCache !== 'object') {
+        return null;
+    }
+    const cachedHeadOid = typeof previousCache.headOid === 'string' ? previousCache.headOid : null;
+    if (!cachedHeadOid || !currentHeadOid || cachedHeadOid !== currentHeadOid) {
+        return null;
+    }
+    return hasRequiredChecksSummary(previousCache.summary) ? previousCache.summary : null;
+}
+export function buildStatusSnapshot(response, requiredChecks = null) {
     const pr = response?.data?.repository?.pullRequest;
     if (!pr) {
         throw new Error('GraphQL response missing pullRequest payload.');
@@ -315,6 +394,9 @@ function buildStatusSnapshot(response) {
     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 gateChecks = requiredCheckSummary ?? checks;
+    const gateChecksSource = requiredCheckSummary ? 'required' : 'rollup';
     const reviewDecision = normalizeEnum(pr.reviewDecision);
     const mergeStateStatus = normalizeEnum(pr.mergeStateStatus);
     const state = normalizeEnum(pr.state);
@@ -329,8 +411,10 @@ function buildStatusSnapshot(response) {
     if (hasDoNotMergeLabel) {
         gateReasons.push('label:do-not-merge');
     }
-    if (checks.pending.length > 0) {
-        gateReasons.push(`checks_pending=${checks.pending.length}`);
+    if (gateChecks.pending.length > 0) {
+        gateReasons.push(gateChecksSource === 'required'
+            ? `required_checks_pending=${gateChecks.pending.length}`
+            : `checks_pending=${gateChecks.pending.length}`);
     }
     if (!MERGEABLE_STATES.has(mergeStateStatus)) {
         gateReasons.push(`merge_state=${mergeStateStatus || 'UNKNOWN'}`);
@@ -354,31 +438,70 @@ function buildStatusSnapshot(response) {
         hasDoNotMergeLabel,
         unresolvedThreadCount,
         checks,
+        requiredChecks: requiredCheckSummary,
+        gateChecksSource,
         gateReasons,
         readyToMerge: gateReasons.length === 0,
         headOid: pr.commits?.nodes?.[0]?.commit?.oid || null
     };
 }
 function formatStatusLine(snapshot, quietRemainingMs) {
+    const requiredChecks = snapshot.requiredChecks;
     const failedNames = snapshot.checks.failed.map((item) => `${item.name}:${item.state}`).join(', ') || '-';
     const pendingNames = snapshot.checks.pending.join(', ') || '-';
+    const requiredFailedNames = requiredChecks
+        ? requiredChecks.failed.map((item) => `${item.name}:${item.state}`).join(', ') || '-'
+        : '-';
+    const requiredPendingNames = requiredChecks ? requiredChecks.pending.join(', ') || '-' : '-';
     const reasons = snapshot.gateReasons.join(', ') || 'none';
     return [
         `PR #${snapshot.number}`,
         `state=${snapshot.state}`,
         `merge_state=${snapshot.mergeStateStatus}`,
         `review=${snapshot.reviewDecision}`,
+        `gate_checks=${snapshot.gateChecksSource}`,
         `checks_ok=${snapshot.checks.successCount}/${snapshot.checks.total}`,
         `checks_pending=${snapshot.checks.pending.length}`,
         `checks_failed=${snapshot.checks.failed.length}`,
+        `required_checks_ok=${requiredChecks ? `${requiredChecks.successCount}/${requiredChecks.total}` : 'n/a'}`,
+        `required_checks_pending=${requiredChecks ? requiredChecks.pending.length : 'n/a'}`,
+        `required_checks_failed=${requiredChecks ? requiredChecks.failed.length : 'n/a'}`,
         `unresolved_threads=${snapshot.unresolvedThreadCount}`,
         `quiet_remaining=${formatDuration(quietRemainingMs)}`,
         `blocked_by=${reasons}`,
         `pending=[${pendingNames}]`,
-        `failed=[${failedNames}]`
+        `failed=[${failedNames}]`,
+        `required_pending=[${requiredPendingNames}]`,
+        `required_failed=[${requiredFailedNames}]`
     ].join(' | ');
 }
-async function fetchSnapshot(owner, repo, prNumber) {
+async function fetchRequiredChecks(owner, repo, prNumber) {
+    try {
+        const result = await runGhJson([
+            'pr',
+            'checks',
+            String(prNumber),
+            '--required',
+            '--json',
+            'name,state,link,bucket',
+            '--repo',
+            `${owner}/${repo}`
+        ]);
+        const entries = Array.isArray(result) ? result : [];
+        const summary = summarizeRequiredChecks(entries);
+        return {
+            summary: summary.total > 0 ? summary : null,
+            fetchError: false
+        };
+    }
+    catch {
+        return {
+            summary: null,
+            fetchError: true
+        };
+    }
+}
+async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache = null) {
     const response = await runGhJson([
         'api',
         'graphql',
@@ -391,7 +514,19 @@ async function fetchSnapshot(owner, repo, prNumber) {
         '-F',
         `number=${prNumber}`
     ]);
-    return buildStatusSnapshot(response);
+    const currentHeadOid = response?.data?.repository?.pullRequest?.commits?.nodes?.[0]?.commit?.oid || null;
+    const previousRequiredChecks = resolveCachedRequiredChecksSummary(previousRequiredChecksCache, currentHeadOid);
+    const requiredChecksResult = await fetchRequiredChecks(owner, repo, prNumber);
+    const requiredChecks = resolveRequiredChecksSummary(requiredChecksResult.summary, previousRequiredChecks, requiredChecksResult.fetchError);
+    return {
+        snapshot: buildStatusSnapshot(response, requiredChecks),
+        requiredChecksForNextPoll: requiredChecks
+            ? {
+                headOid: currentHeadOid,
+                summary: requiredChecks
+            }
+            : null
+    };
 }
 async function attemptMerge({ prNumber, mergeMethod, deleteBranch, headOid }) {
     // gh pr merge has no --yes flag; rely on non-interactive stdio + explicit merge method.
@@ -472,10 +607,13 @@ async function runPrWatchMergeOrThrow(argv, options) {
     let quietWindowAnchorUpdatedAt = null;
     let quietWindowAnchorHeadOid = null;
     let lastMergeAttemptHeadOid = null;
+    let requiredChecksForNextPollCache = null;
     while (Date.now() <= deadline) {
         let snapshot;
         try {
-            snapshot = await fetchSnapshot(owner, repo, prNumber);
+            const fetched = await fetchSnapshot(owner, repo, prNumber, requiredChecksForNextPollCache);
+            snapshot = fetched.snapshot;
+            requiredChecksForNextPollCache = fetched.requiredChecksForNextPoll;
         }
         catch (error) {
             log(`Polling error: ${error instanceof Error ? error.message : String(error)} (retrying).`);

package/docs/README.md

@@ -155,6 +155,7 @@ Notes:
 - `/prompts:review-handoff` takes `TASK=<task-id> MANIFEST=<path> NOTES=<goal + summary + risks + optional questions>`, re-exports `MCP_RUNNER_TASK_ID`, and (repo-only) runs `node scripts/delegation-guard.mjs`, `node scripts/spec-guard.mjs --dry-run`, `npm run lint`, `npm run test`, optional `npm run eval:test`, plus `npm run review` (wraps `codex review` against the current diff and includes the latest run manifest path as evidence). It also reminds you to log approvals in `$MANIFEST` and mirror the evidence to the same docs/metrics/state targets.
 - In CI / `--no-interactive` pipelines (or when stdin is not a TTY, or `CODEX_REVIEW_NON_INTERACTIVE=1` / `CODEX_NON_INTERACTIVE=1` / `CODEX_NO_INTERACTIVE=1`), `npm run review` prints the review handoff prompt (including evidence paths) and exits successfully instead of invoking `codex review`. Set `FORCE_CODEX_REVIEW=1` to run `codex review` in those environments.
 - When forcing non-interactive review execution, `npm run review` enforces a timeout (`CODEX_REVIEW_TIMEOUT_SECONDS`, default `900`). Set `CODEX_REVIEW_TIMEOUT_SECONDS=0` to disable the timeout.
+- Forced non-interactive review execution also enforces a no-output stall timeout (`CODEX_REVIEW_STALL_TIMEOUT_SECONDS`, default `600`). Set `CODEX_REVIEW_STALL_TIMEOUT_SECONDS=0` to disable the stall guard.
 - Always trigger diagnostics and review workflows through these prompts whenever you run the orchestrator so contributors consistently execute the required command sequences and capture auditable manifests.
 
 ### Identifier Guardrails

package/package.json

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

package/skills/standalone-review/SKILL.md

@@ -64,6 +64,7 @@ codex review "Focus on correctness, regressions, edge cases; list missing tests.
 - If you need manifest evidence, use the review wrapper:
   `TASK=<task-id> NOTES="Goal: ... | Summary: ... | Risks: ... | Questions (optional): ..." MANIFEST=<path> npm run review -- --manifest <path>`
 - In non-interactive environments, add `FORCE_CODEX_REVIEW=1` as needed.
+- In non-interactive environments, prefer the wrapper over raw `codex review`; it enforces `CODEX_REVIEW_TIMEOUT_SECONDS` and `CODEX_REVIEW_STALL_TIMEOUT_SECONDS` guardrails.
 
 ## Expected outputs
 - A prioritized list of findings.