@kbediako/codex-orchestrator 0.1.18 → 0.1.19

package/README.md

@@ -55,15 +55,16 @@ Use this when you want Codex to drive work inside another repo with the CO defau
    ```bash
    codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
    ```
-3. Optional (collab JSONL parity): set up a CO-managed Codex CLI:
+3. Optional (managed/pinned CLI path): set up a CO-managed Codex CLI:
    ```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.
 4. Optional (fast refresh helper for downstream users):
    ```bash
-   scripts/codex-cli-refresh.sh --repo /path/to/codex
+   scripts/codex-cli-refresh.sh --repo /path/to/codex --align-only
    ```
-   Repo-only helper (not included in npm package). Set `CODEX_REPO` or `CODEX_CLI_SOURCE` to avoid passing `--repo` each time.
+   Repo-only helper (not included in npm package). Add `--no-push` when you only want local alignment and do not want to update `origin/main`. To refresh the CO-managed CLI, run a separate command with `--force-rebuild` (without `--align-only`). Set `CODEX_REPO` or `CODEX_CLI_SOURCE` to avoid passing `--repo` each time.
 
 ## Delegation MCP server
 
@@ -88,7 +89,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 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 when `RLM_SYMBOLIC_COLLAB=1` (requires a collab-enabled Codex CLI via `codex-orchestrator codex setup`). 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).
+Symbolic subcalls can optionally use collab tools when `RLM_SYMBOLIC_COLLAB=1` (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.
 
 ### Delegation flow
 ```mermaid
@@ -164,9 +165,9 @@ 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 init codex --codex-cli --yes --codex-source <path>` — also provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time).
+- `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 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 (for collab JSONL parity; 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).
 - `codex-orchestrator self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
 

package/dist/bin/codex-orchestrator.js

@@ -7,6 +7,7 @@ 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';
 import { resolveEnvironmentPaths } from '../scripts/lib/run-manifests.js';
+import { runPrWatchMerge } from '../scripts/lib/pr-watch-merge.js';
 import { normalizeEnvironmentPaths, sanitizeTaskId } from '../orchestrator/src/cli/run/environment.js';
 import { RunEventEmitter } from '../orchestrator/src/cli/events/runEvents.js';
 import { evaluateInteractiveGate } from '../orchestrator/src/cli/utils/interactive.js';
@@ -77,6 +78,9 @@ async function main() {
             case 'mcp':
                 await handleMcp(args);
                 break;
+            case 'pr':
+                await handlePr(args);
+                break;
             case 'delegate-server':
             case 'delegation-server':
                 await handleDelegationServer(args);
@@ -627,6 +631,20 @@ async function handleMcp(rawArgs) {
     const dryRun = Boolean(flags['dry-run']);
     await serveMcp({ repoRoot, dryRun, extraArgs: positionals });
 }
+async function handlePr(rawArgs) {
+    if (rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h' || rawArgs[0] === 'help') {
+        printPrHelp();
+        return;
+    }
+    const [subcommand, ...subcommandArgs] = rawArgs;
+    if (subcommand !== 'watch-merge') {
+        throw new Error(`Unknown pr subcommand: ${subcommand}`);
+    }
+    const exitCode = await runPrWatchMerge(subcommandArgs, { usage: 'codex-orchestrator pr watch-merge' });
+    if (exitCode !== 0) {
+        process.exitCode = exitCode;
+    }
+}
 async function handleDelegationServer(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     if (isHelpRequest(positionals, flags)) {
@@ -931,6 +949,9 @@ Commands:
     --codex-home <path>   Override the target Codex home directory.
     --format json         Emit machine-readable output.
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
+  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.
   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.
@@ -989,3 +1010,15 @@ Options:
   --help                           Show this message.
 `);
 }
+function printPrHelp() {
+    console.log(`Usage: codex-orchestrator pr <subcommand> [options]
+
+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).
+
+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
+`);
+}

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

@@ -62,6 +62,6 @@ export function formatInitSummary(result, cwd) {
     }
     lines.push('Next steps (recommended):');
     lines.push(`  - codex mcp add delegation -- codex-orchestrator delegate-server --repo ${cwd}`);
-    lines.push('  - codex-orchestrator codex setup  # optional: CO-managed Codex CLI for collab JSONL');
+    lines.push('  - codex-orchestrator codex setup  # optional: managed/pinned Codex CLI (stock CLI works by default)');
     return lines;
 }

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

@@ -0,0 +1,566 @@
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { hasFlag, parseArgs } from './cli-args.js';
+const DEFAULT_INTERVAL_SECONDS = 30;
+const DEFAULT_QUIET_MINUTES = 15;
+const DEFAULT_TIMEOUT_MINUTES = 180;
+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 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 PR_QUERY = `
+query($owner:String!, $repo:String!, $number:Int!) {
+  repository(owner:$owner, name:$repo) {
+    pullRequest(number:$number) {
+      number
+      url
+      state
+      isDraft
+      reviewDecision
+      mergeStateStatus
+      updatedAt
+      mergedAt
+      labels(first:50) {
+        nodes {
+          name
+        }
+      }
+      reviewThreads(first:100) {
+        nodes {
+          isResolved
+          isOutdated
+        }
+      }
+      commits(last:1) {
+        nodes {
+          commit {
+            oid
+            statusCheckRollup {
+              contexts(first:100) {
+                nodes {
+                  __typename
+                  ... on CheckRun {
+                    name
+                    status
+                    conclusion
+                    detailsUrl
+                  }
+                  ... on StatusContext {
+                    context
+                    state
+                    targetUrl
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+`;
+function normalizeEnum(value) {
+    return typeof value === 'string' ? value.trim().toUpperCase() : '';
+}
+function formatDuration(ms) {
+    if (ms <= 0) {
+        return '0s';
+    }
+    const seconds = Math.ceil(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const remainder = seconds % 60;
+    if (minutes === 0) {
+        return `${remainder}s`;
+    }
+    if (remainder === 0) {
+        return `${minutes}m`;
+    }
+    return `${minutes}m${remainder}s`;
+}
+function log(message) {
+    console.log(`[${new Date().toISOString()}] ${message}`);
+}
+function parseNumber(name, rawValue, fallback) {
+    if (rawValue === undefined || rawValue === null || rawValue === '') {
+        return fallback;
+    }
+    if (typeof rawValue === 'boolean') {
+        throw new Error(`--${name} requires a value.`);
+    }
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`--${name} must be a number > 0 (received: ${rawValue})`);
+    }
+    return parsed;
+}
+function parseInteger(name, rawValue, fallback) {
+    if (rawValue === undefined || rawValue === null || rawValue === '') {
+        return fallback;
+    }
+    if (typeof rawValue === 'boolean') {
+        throw new Error(`--${name} requires a value.`);
+    }
+    const parsed = Number(rawValue);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`--${name} must be an integer > 0 (received: ${rawValue})`);
+    }
+    return parsed;
+}
+function envFlagEnabled(rawValue, fallback = false) {
+    if (rawValue === undefined || rawValue === null) {
+        return fallback;
+    }
+    const normalized = String(rawValue).trim().toLowerCase();
+    if (normalized.length === 0) {
+        return fallback;
+    }
+    if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+        return true;
+    }
+    if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+        return false;
+    }
+    return fallback;
+}
+function parseMergeMethod(rawValue) {
+    const normalized = (rawValue || DEFAULT_MERGE_METHOD).trim().toLowerCase();
+    if (normalized !== 'merge' && normalized !== 'squash' && normalized !== 'rebase') {
+        throw new Error(`--merge-method must be merge, squash, or rebase (received: ${rawValue})`);
+    }
+    return normalized;
+}
+export function printPrWatchMergeHelp(options = {}) {
+    const usageCommand = typeof options.usage === 'string' && options.usage.trim().length > 0
+        ? options.usage.trim()
+        : 'codex-orchestrator pr watch-merge';
+    console.log(`Usage: ${usageCommand} [options]
+
+Monitor PR checks/reviews with polling and optionally merge after a quiet window.
+
+Options:
+  --pr <number>             PR number (default: PR for current branch)
+  --owner <name>            Repo owner (default: inferred via gh repo view)
+  --repo <name>             Repo name (default: inferred via gh repo view)
+  --interval-seconds <n>    Poll interval in seconds (default: ${DEFAULT_INTERVAL_SECONDS})
+  --quiet-minutes <n>       Required quiet window after ready state (default: ${DEFAULT_QUIET_MINUTES})
+  --timeout-minutes <n>     Max monitor duration before failing (default: ${DEFAULT_TIMEOUT_MINUTES})
+  --merge-method <method>   merge|squash|rebase (default: ${DEFAULT_MERGE_METHOD})
+  --auto-merge              Merge automatically after quiet window
+  --no-auto-merge           Never merge automatically (monitor only)
+  --delete-branch           Delete remote branch when merging
+  --no-delete-branch        Keep remote branch after merge
+  --dry-run                 Never call gh pr merge (report only)
+  -h, --help                Show this help message
+
+Environment:
+  PR_MONITOR_AUTO_MERGE=1       Default auto-merge on
+  PR_MONITOR_DELETE_BRANCH=1    Default delete branch on merge
+  PR_MONITOR_QUIET_MINUTES=<n>  Override quiet window default
+  PR_MONITOR_INTERVAL_SECONDS=<n>
+  PR_MONITOR_TIMEOUT_MINUTES=<n>
+  PR_MONITOR_MERGE_METHOD=<method>`);
+}
+async function runGh(args, { allowFailure = false } = {}) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn('gh', args, {
+            env: {
+                ...process.env,
+                GH_PAGER: process.env.GH_PAGER || 'cat',
+                // Harden all gh calls against interactive prompts (per `gh help environment`).
+                GH_PROMPT_DISABLED: process.env.GH_PROMPT_DISABLED || '1'
+            },
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.once('error', (error) => {
+            reject(new Error(`Failed to run gh ${args.join(' ')}: ${error.message}`));
+        });
+        child.once('close', (code) => {
+            const exitCode = typeof code === 'number' ? code : 1;
+            const result = {
+                exitCode,
+                stdout: stdout.trim(),
+                stderr: stderr.trim()
+            };
+            if (exitCode === 0 || allowFailure) {
+                resolve(result);
+                return;
+            }
+            const detail = result.stderr || result.stdout || `exit code ${exitCode}`;
+            reject(new Error(`gh ${args.join(' ')} failed: ${detail}`));
+        });
+    });
+}
+async function runGhJson(args) {
+    const result = await runGh(args);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse 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) {
+        throw new Error('GitHub CLI is not authenticated for github.com. Run `gh auth login` and retry.');
+    }
+}
+async function resolveRepo(ownerArg, repoArg) {
+    if (ownerArg && repoArg) {
+        return { owner: ownerArg, repo: repoArg };
+    }
+    if (ownerArg || repoArg) {
+        throw new Error('Provide both --owner and --repo, or neither.');
+    }
+    const response = await runGhJson(['repo', 'view', '--json', 'nameWithOwner']);
+    const nameWithOwner = response?.nameWithOwner;
+    if (typeof nameWithOwner !== 'string' || !nameWithOwner.includes('/')) {
+        throw new Error('Unable to infer repository owner/name from gh repo view.');
+    }
+    const [owner, repo] = nameWithOwner.split('/');
+    return { owner, repo };
+}
+async function resolvePrNumber(prArg) {
+    if (prArg !== undefined) {
+        return parseInteger('pr', prArg, null);
+    }
+    const response = await runGhJson(['pr', 'view', '--json', 'number']);
+    const number = response?.number;
+    if (!Number.isInteger(number) || number <= 0) {
+        throw new Error('Unable to infer PR number from current branch.');
+    }
+    return number;
+}
+function summarizeChecks(nodes) {
+    const summary = {
+        total: 0,
+        successCount: 0,
+        pending: [],
+        failed: []
+    };
+    for (const node of nodes) {
+        if (!node || typeof node !== 'object') {
+            continue;
+        }
+        const typeName = typeof node.__typename === 'string' ? node.__typename : '';
+        if (typeName === 'CheckRun') {
+            summary.total += 1;
+            const name = typeof node.name === 'string' && node.name.trim() ? node.name.trim() : 'check-run';
+            const status = normalizeEnum(node.status);
+            if (status !== 'COMPLETED') {
+                summary.pending.push(name);
+                continue;
+            }
+            const conclusion = normalizeEnum(node.conclusion);
+            if (CHECKRUN_PASS_CONCLUSIONS.has(conclusion)) {
+                summary.successCount += 1;
+            }
+            else {
+                summary.failed.push({
+                    name,
+                    state: conclusion || 'UNKNOWN',
+                    detailsUrl: typeof node.detailsUrl === 'string' ? node.detailsUrl : null
+                });
+            }
+            continue;
+        }
+        if (typeName === 'StatusContext') {
+            summary.total += 1;
+            const name = typeof node.context === 'string' && node.context.trim() ? node.context.trim() : 'status-context';
+            const state = normalizeEnum(node.state);
+            if (STATUS_CONTEXT_PENDING_STATES.has(state)) {
+                summary.pending.push(name);
+                continue;
+            }
+            if (STATUS_CONTEXT_PASS_STATES.has(state)) {
+                summary.successCount += 1;
+            }
+            else {
+                summary.failed.push({
+                    name,
+                    state: state || 'UNKNOWN',
+                    detailsUrl: typeof node.targetUrl === 'string' ? node.targetUrl : null
+                });
+            }
+        }
+    }
+    return summary;
+}
+function buildStatusSnapshot(response) {
+    const pr = response?.data?.repository?.pullRequest;
+    if (!pr) {
+        throw new Error('GraphQL response missing pullRequest payload.');
+    }
+    const labels = Array.isArray(pr.labels?.nodes)
+        ? pr.labels.nodes
+            .map((item) => (item && typeof item.name === 'string' ? item.name.trim() : ''))
+            .filter(Boolean)
+        : [];
+    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 contexts = pr.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts?.nodes;
+    const checkNodes = Array.isArray(contexts) ? contexts : [];
+    const checks = summarizeChecks(checkNodes);
+    const reviewDecision = normalizeEnum(pr.reviewDecision);
+    const mergeStateStatus = normalizeEnum(pr.mergeStateStatus);
+    const state = normalizeEnum(pr.state);
+    const isDraft = Boolean(pr.isDraft);
+    const gateReasons = [];
+    if (state !== 'OPEN') {
+        gateReasons.push(`state=${state || 'UNKNOWN'}`);
+    }
+    if (isDraft) {
+        gateReasons.push('draft');
+    }
+    if (hasDoNotMergeLabel) {
+        gateReasons.push('label:do-not-merge');
+    }
+    if (checks.pending.length > 0) {
+        gateReasons.push(`checks_pending=${checks.pending.length}`);
+    }
+    if (!MERGEABLE_STATES.has(mergeStateStatus)) {
+        gateReasons.push(`merge_state=${mergeStateStatus || 'UNKNOWN'}`);
+    }
+    if (BLOCKED_REVIEW_DECISIONS.has(reviewDecision)) {
+        gateReasons.push(`review=${reviewDecision}`);
+    }
+    if (unresolvedThreadCount > 0) {
+        gateReasons.push(`unresolved_threads=${unresolvedThreadCount}`);
+    }
+    return {
+        number: Number(pr.number),
+        url: typeof pr.url === 'string' ? pr.url : null,
+        state,
+        isDraft,
+        reviewDecision: reviewDecision || 'NONE',
+        mergeStateStatus: mergeStateStatus || 'UNKNOWN',
+        updatedAt: typeof pr.updatedAt === 'string' ? pr.updatedAt : null,
+        mergedAt: typeof pr.mergedAt === 'string' ? pr.mergedAt : null,
+        labels,
+        hasDoNotMergeLabel,
+        unresolvedThreadCount,
+        checks,
+        gateReasons,
+        readyToMerge: gateReasons.length === 0,
+        headOid: pr.commits?.nodes?.[0]?.commit?.oid || null
+    };
+}
+function formatStatusLine(snapshot, quietRemainingMs) {
+    const failedNames = snapshot.checks.failed.map((item) => `${item.name}:${item.state}`).join(', ') || '-';
+    const pendingNames = snapshot.checks.pending.join(', ') || '-';
+    const reasons = snapshot.gateReasons.join(', ') || 'none';
+    return [
+        `PR #${snapshot.number}`,
+        `state=${snapshot.state}`,
+        `merge_state=${snapshot.mergeStateStatus}`,
+        `review=${snapshot.reviewDecision}`,
+        `checks_ok=${snapshot.checks.successCount}/${snapshot.checks.total}`,
+        `checks_pending=${snapshot.checks.pending.length}`,
+        `checks_failed=${snapshot.checks.failed.length}`,
+        `unresolved_threads=${snapshot.unresolvedThreadCount}`,
+        `quiet_remaining=${formatDuration(quietRemainingMs)}`,
+        `blocked_by=${reasons}`,
+        `pending=[${pendingNames}]`,
+        `failed=[${failedNames}]`
+    ].join(' | ');
+}
+async function fetchSnapshot(owner, repo, prNumber) {
+    const response = await runGhJson([
+        'api',
+        'graphql',
+        '-f',
+        `query=${PR_QUERY}`,
+        '-f',
+        `owner=${owner}`,
+        '-f',
+        `repo=${repo}`,
+        '-F',
+        `number=${prNumber}`
+    ]);
+    return buildStatusSnapshot(response);
+}
+async function attemptMerge({ prNumber, mergeMethod, deleteBranch, headOid }) {
+    // gh pr merge has no --yes flag; rely on non-interactive stdio + explicit merge method.
+    const args = ['pr', 'merge', String(prNumber), `--${mergeMethod}`];
+    if (deleteBranch) {
+        args.push('--delete-branch');
+    }
+    if (headOid) {
+        args.push('--match-head-commit', headOid);
+    }
+    return await runGh(args, { allowFailure: true });
+}
+async function runPrWatchMergeOrThrow(argv, options) {
+    const { args, positionals } = parseArgs(argv);
+    if (hasFlag(args, 'h') || hasFlag(args, 'help')) {
+        printPrWatchMergeHelp(options);
+        return;
+    }
+    const knownFlags = new Set([
+        'pr',
+        'owner',
+        'repo',
+        'interval-seconds',
+        'quiet-minutes',
+        'timeout-minutes',
+        'merge-method',
+        'auto-merge',
+        'no-auto-merge',
+        'delete-branch',
+        'no-delete-branch',
+        'dry-run',
+        'h',
+        'help'
+    ]);
+    const unknownFlags = Object.keys(args).filter((key) => !knownFlags.has(key));
+    if (unknownFlags.length > 0 || positionals.length > 0) {
+        const label = unknownFlags[0] ? `--${unknownFlags[0]}` : positionals[0];
+        throw new Error(`Unknown option: ${label}`);
+    }
+    const intervalSeconds = parseNumber('interval-seconds', typeof args['interval-seconds'] === 'string'
+        ? args['interval-seconds']
+        : process.env.PR_MONITOR_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS);
+    const quietMinutes = parseNumber('quiet-minutes', typeof args['quiet-minutes'] === 'string'
+        ? args['quiet-minutes']
+        : process.env.PR_MONITOR_QUIET_MINUTES, DEFAULT_QUIET_MINUTES);
+    const timeoutMinutes = parseNumber('timeout-minutes', typeof args['timeout-minutes'] === 'string'
+        ? args['timeout-minutes']
+        : process.env.PR_MONITOR_TIMEOUT_MINUTES, DEFAULT_TIMEOUT_MINUTES);
+    const mergeMethod = parseMergeMethod(typeof args['merge-method'] === 'string'
+        ? args['merge-method']
+        : process.env.PR_MONITOR_MERGE_METHOD || DEFAULT_MERGE_METHOD);
+    const defaultAutoMerge = envFlagEnabled(process.env.PR_MONITOR_AUTO_MERGE, false);
+    const defaultDeleteBranch = envFlagEnabled(process.env.PR_MONITOR_DELETE_BRANCH, true);
+    let autoMerge = defaultAutoMerge;
+    if (hasFlag(args, 'auto-merge')) {
+        autoMerge = true;
+    }
+    if (hasFlag(args, 'no-auto-merge')) {
+        autoMerge = false;
+    }
+    let deleteBranch = defaultDeleteBranch;
+    if (hasFlag(args, 'delete-branch')) {
+        deleteBranch = true;
+    }
+    if (hasFlag(args, 'no-delete-branch')) {
+        deleteBranch = false;
+    }
+    const dryRun = hasFlag(args, 'dry-run');
+    await ensureGhAuth();
+    const { owner, repo } = await resolveRepo(typeof args.owner === 'string' ? args.owner : undefined, typeof args.repo === 'string' ? args.repo : undefined);
+    const prNumber = await resolvePrNumber(args.pr);
+    const intervalMs = Math.round(intervalSeconds * 1000);
+    const quietMs = Math.round(quietMinutes * 60 * 1000);
+    const timeoutMs = Math.round(timeoutMinutes * 60 * 1000);
+    const deadline = Date.now() + timeoutMs;
+    log(`Monitoring ${owner}/${repo}#${prNumber} every ${intervalSeconds}s (quiet window ${quietMinutes}m, timeout ${timeoutMinutes}m, auto_merge=${autoMerge ? 'on' : 'off'}, dry_run=${dryRun ? 'on' : 'off'}).`);
+    let quietWindowStartedAt = null;
+    let quietWindowAnchorUpdatedAt = null;
+    let quietWindowAnchorHeadOid = null;
+    let lastMergeAttemptHeadOid = null;
+    while (Date.now() <= deadline) {
+        let snapshot;
+        try {
+            snapshot = await fetchSnapshot(owner, repo, prNumber);
+        }
+        catch (error) {
+            log(`Polling error: ${error instanceof Error ? error.message : String(error)} (retrying).`);
+            await sleep(intervalMs);
+            continue;
+        }
+        if (snapshot.state === 'MERGED' || snapshot.mergedAt) {
+            log(`PR #${prNumber} is merged.`);
+            if (snapshot.url) {
+                log(`URL: ${snapshot.url}`);
+            }
+            return;
+        }
+        if (snapshot.state === 'CLOSED') {
+            throw new Error(`PR #${prNumber} was closed without merge.`);
+        }
+        if (snapshot.readyToMerge) {
+            const readyAnchorChanged = quietWindowStartedAt !== null &&
+                (snapshot.updatedAt !== quietWindowAnchorUpdatedAt || snapshot.headOid !== quietWindowAnchorHeadOid);
+            if (quietWindowStartedAt === null || readyAnchorChanged) {
+                quietWindowStartedAt = Date.now();
+                quietWindowAnchorUpdatedAt = snapshot.updatedAt;
+                quietWindowAnchorHeadOid = snapshot.headOid;
+                lastMergeAttemptHeadOid = null;
+                log(readyAnchorChanged
+                    ? 'Ready state changed; quiet window reset.'
+                    : `Ready state reached; quiet window started (${quietMinutes}m).`);
+            }
+        }
+        else if (quietWindowStartedAt !== null) {
+            quietWindowStartedAt = null;
+            quietWindowAnchorUpdatedAt = null;
+            quietWindowAnchorHeadOid = null;
+            lastMergeAttemptHeadOid = null;
+            log('Ready state lost; quiet window cleared.');
+        }
+        const quietElapsedMs = quietWindowStartedAt ? Date.now() - quietWindowStartedAt : 0;
+        const quietRemainingMs = quietWindowStartedAt ? Math.max(quietMs - quietElapsedMs, 0) : quietMs;
+        log(formatStatusLine(snapshot, quietRemainingMs));
+        if (snapshot.readyToMerge && quietWindowStartedAt !== null && quietElapsedMs >= quietMs) {
+            if (!autoMerge || dryRun) {
+                log(dryRun
+                    ? 'Dry run: merge conditions satisfied and quiet window elapsed.'
+                    : 'Merge conditions satisfied and quiet window elapsed.');
+                if (snapshot.url) {
+                    log(`Ready to merge: ${snapshot.url}`);
+                }
+                return;
+            }
+            if (snapshot.headOid && snapshot.headOid === lastMergeAttemptHeadOid) {
+                log(`Merge already attempted for head ${snapshot.headOid}; waiting for PR state refresh.`);
+            }
+            else {
+                lastMergeAttemptHeadOid = snapshot.headOid;
+                log(`Attempting merge via gh pr merge --${mergeMethod}${deleteBranch ? ' --delete-branch' : ''}.`);
+                const mergeResult = await attemptMerge({
+                    prNumber,
+                    mergeMethod,
+                    deleteBranch,
+                    headOid: snapshot.headOid
+                });
+                if (mergeResult.exitCode === 0) {
+                    log(`Merge command succeeded for PR #${prNumber}.`);
+                    return;
+                }
+                const details = mergeResult.stderr || mergeResult.stdout || `exit code ${mergeResult.exitCode}`;
+                log(`Merge attempt failed: ${details}`);
+            }
+        }
+        const remainingTimeMs = deadline - Date.now();
+        if (remainingTimeMs <= 0) {
+            break;
+        }
+        await sleep(Math.min(intervalMs, remainingTimeMs));
+    }
+    throw new Error(`Timed out after ${timeoutMinutes} minute(s) while monitoring PR #${prNumber}.`);
+}
+export async function runPrWatchMerge(argv, options = {}) {
+    try {
+        await runPrWatchMergeOrThrow(argv, options);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return 1;
+    }
+}

package/package.json

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

package/skills/collab-deliberation/SKILL.md

@@ -50,6 +50,7 @@ Use this skill when the user asks for brainstorming, tradeoffs, option compariso
 2) Close critical context gaps.
 - Ask up to 3 targeted questions only if answers could change the recommendation.
 - If delegation is available, prefer a subagent for context gathering before asking the user.
+- If collab spawning fails (for example `agent thread limit reached`), proceed solo and explicitly note the limitation; do not block on spawning.
 
 3) Generate distinct options.
 - Produce 3-5 materially different options.
@@ -83,3 +84,4 @@ Use this skill when the user asks for brainstorming, tradeoffs, option compariso
 - Do not present uncertainty as certainty.
 - Keep outputs concise and action-oriented.
 - If collab subagents are used, close lifecycle loops per id (`spawn_agent` -> `wait` -> `close_agent`) before finishing.
+- If you cannot close collab agents (missing ids) and spawn keeps failing, restart the session and re-run deliberation; keep work moving by doing solo deliberation meanwhile.

package/skills/delegation-usage/DELEGATION_GUIDE.md

@@ -122,7 +122,11 @@ Delegation MCP expects JSONL. Keep `codex-orchestrator` aligned with the current
 - Check: `codex-orchestrator --version`
 - Update global: `npm i -g @kbediako/codex-orchestrator@latest`
 - Or pin via npx: `npx -y @kbediako/codex-orchestrator@<version> delegate-server`
-- If using a custom Codex fork, fast-forward from `upstream/main` regularly and rebuild to avoid protocol drift.
+- Stock `codex` is the default path. If using a custom Codex fork, fast-forward from `upstream/main` regularly.
+- CO repo checkout only (helper is not shipped in npm): `scripts/codex-cli-refresh.sh --repo /path/to/codex --align-only`
+- CO repo checkout only (managed rebuild helper): `scripts/codex-cli-refresh.sh --repo /path/to/codex --force-rebuild`
+- Add `--no-push` only when you intentionally want local-only alignment without updating `origin/main`.
+- npm-safe alternative (no repo helper): `codex-orchestrator codex setup --source /path/to/codex --yes --force`
 
 ## Common failures
 

package/skills/delegation-usage/SKILL.md

@@ -81,7 +81,11 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
   - Check installed version: `codex-orchestrator --version`
   - Preferred update path: `npm i -g @kbediako/codex-orchestrator@latest`
   - Deterministic pin path (for reproducible environments): `npx -y @kbediako/codex-orchestrator@<version> delegate-server`
-- If using a custom Codex fork, fast-forward it regularly from `upstream/main` and rebuild the managed CLI to avoid delegation/collab protocol drift.
+- Stock `codex` is the default path. If you use a custom Codex fork, fast-forward it regularly from `upstream/main`.
+- CO repo checkout only (helper is not shipped in npm): `scripts/codex-cli-refresh.sh --repo /path/to/codex --align-only`
+- CO repo checkout only (managed rebuild helper): `scripts/codex-cli-refresh.sh --repo /path/to/codex --force-rebuild`
+- Add `--no-push` only when you intentionally want local-only alignment without updating `origin/main`.
+- npm-safe alternative (no repo helper): `codex-orchestrator codex setup --source /path/to/codex --yes --force`
 
 ### 0b) Background terminal bootstrap (required when MCP is disabled)