@kbediako/codex-orchestrator 0.1.18 → 0.1.20

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.20",
   "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/collab-subagents-first/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: collab-subagents-first
+description: Manage non-trivial tasks via focused collab subagents to save context and improve throughput. Use when work spans multiple files/components, can be split into independent streams, needs separate validation/review, or risks context bloat. Favor direct execution for trivial one-shot tasks.
+---
+
+# Collab Subagents First
+
+## Overview
+
+Delegate as a manager, not as a pass-through. Split work into narrow streams, give each subagent a rich brief, and keep parent context lean by collecting short structured summaries plus evidence paths.
+
+Note: If a global `collab-subagents-first` skill is installed, prefer that and fall back to this bundled skill.
+
+## Delegation gate
+
+Use subagents when any condition is true:
+- Task spans more than one subsystem or more than one file.
+- Work naturally splits into independent streams (for example research + implementation + verification).
+- Work likely exceeds about 5-10 minutes.
+- Separate review/verification is required before handoff.
+- Parent context is growing and summary compression is needed.
+- You are unsure whether the task should be delegated.
+
+Default rule:
+- For any non-trivial task, spawn at least one subagent early (even if work is mostly single-stream) to offload execution and preserve parent context.
+
+Skip subagents when all conditions are true:
+- Single-file or tightly scoped change.
+- No parallelizable stream exists.
+- Execution and verification are straightforward in one pass.
+- Expected duration is under about 5 minutes.
+
+## Workflow
+
+1) Define parent success criteria
+- Write 3-6 acceptance bullets before spawning.
+- Define "done" and required validation upfront.
+
+2) Choose delegation shape
+- Minimum for non-trivial work: 1 subagent (`implement` or `research`).
+- Standard: 2 subagents (`implement` + `review/verify`).
+- Complex/high-risk: 3-4 subagents (`research`, `implement`, `tests`, `review`).
+- If uncertain, spawn a short-lived `scout` subagent first to propose decomposition and risks.
+
+3) Split into narrow streams
+- Prefer 1-4 streams based on the chosen shape.
+- Assign one owner per stream and avoid overlapping file ownership.
+- Good stream labels: `research`, `implement`, `tests`, `review`.
+
+4) Send a rich brief to each subagent
+- Use the required brief template from `references/subagent-brief-template.md`.
+- Include objective, scope, constraints, acceptance criteria, and expected output format.
+- Require concise summaries and evidence paths; avoid long logs in chat.
+
+5) Run streams in parallel when independent
+- Spawn multiple subagents for independent streams.
+- Wait for all subagents to finish before final synthesis.
+
+6) Synthesize with context compression
+- Merge only decisions, findings, and evidence links into parent context.
+- Keep full details in artifacts/files instead of long conversation dumps.
+- Force summary discipline: keep each subagent synthesis to a short block with outcome, files, validation, findings, and open questions only.
+
+7) Verify before handoff
+- Run parent-level validation/tests.
+- Run standalone review on merged changes (see review loop below).
+
+8) Re-check delegation need at checkpoints
+- Re-evaluate delegation after major context growth (for example every 6-8 parent messages, or after crossing about 8 touched files, or when the plan changes materially).
+- If parent context starts bloating, spawn/redirect subagents instead of continuing in parent.
+- Keep the delegation tree shallow. Prefer parent fan-out over subagent-of-subagent chains.
+
+## Spawn payload + labels (current behavior)
+
+- `spawn_agent` accepts exactly one input style:
+  - `message` (plain text), or
+  - `items` (structured input).
+- Do not send both `message` and `items` in one spawn call.
+- Use `items` when you need explicit structured context (for example `mention` paths like `app://...` or selected `skill` entries) instead of flattening everything into one long string.
+- Spawn returns an `agent_id` (thread id). Collab event rendering/picker labels are id-based today; do not depend on custom visible agent names.
+- To keep operator readability high despite id labels, encode the role clearly in your stream labels and first-line task brief (for example `review`, `tests`, `research`).
+
+## Collab lifecycle hygiene (required)
+
+When you use collab tools (`spawn_agent` / `wait` / `close_agent`):
+- Keep a local list of every returned `agent_id`.
+- For every successful `spawn_agent`, run `wait` and then `close_agent` for that same id.
+- Always close agents on error/timeout paths; do a final cleanup pass before finishing so no id is left unclosed.
+- If spawn fails with `agent thread limit reached`, stop spawning immediately, close any known ids, then retry once. If you still cannot spawn, proceed without collab (solo or via delegation) and explicitly note the degraded mode.
+
+## Required subagent contract
+
+Require each subagent response to include:
+- `Outcome`: done / blocked / partial.
+- `Changes`: files touched or "none".
+- `Validation`: commands run and pass/fail results.
+- `Findings`: prioritized defects/risks (or "none found").
+- `Evidence`: artifact paths, manifests, or command outputs summary.
+- `Open questions`: only unresolved items that block correctness.
+
+Reject and rerun when responses are:
+- Missing validation evidence for code changes.
+- Missing ownership/scope boundaries.
+- Excessively verbose with no actionable summary.
+
+## Execution constraints for subagents
+
+- Subagents are spawned with approval policy effectively set to `never`.
+- Design subagent tasks so they can complete without approval/escalation prompts.
+- Keep privileged/high-risk operations in the parent thread when interactive approval is required.
+- Subagents inherit core execution context (for example cwd/sandbox constraints), so include environment assumptions explicitly in each brief.
+
+## Review loop (standalone-review pairing)
+
+Use a two-layer review loop:
+
+1) Subagent self-review (when possible)
+- If `codex review` is available in the working repo, have the subagent run the repo's standalone-review flow (including hardened fallback rules) for:
+  - `--uncommitted`, or
+  - `--base <branch>` when branch comparison is clearer.
+- Capture top findings and fixes in the subagent summary.
+- If self-review cannot run (tool/policy/trust constraints), require a manual checklist summary: correctness, regressions, missing tests.
+
+2) Parent independent review (required)
+- After integrating subagent work, run a standalone review from the parent.
+- Prefer the global `standalone-review` skill workflow for consistent checks.
+
+Do not treat wrapper handoff-only output as a completed review.
+
+## Orchestrator + RLM path (optional, recommended for deep loops)
+
+- Prefer orchestrator RLM/delegation loops for long-horizon, recursive, or high-risk tasks when available.
+- Keep this additive: still perform final parent synthesis and standalone review.
+- If orchestrator is unavailable, continue with local subagent orchestration and standalone review.
+
+## Compatibility guardrail (JSONL/collab drift)
+
+- Symptoms: missing collab/delegate tool-call evidence, framing/parsing errors, or unstable collab behavior after CLI upgrades.
+- Check versions first: `codex --version` and `codex-orchestrator --version`.
+- CO repo refresh path (safe default): `scripts/codex-cli-refresh.sh --repo <codex-repo> --no-push`.
+- Rebuild managed CLI only: `codex-orchestrator codex setup --source <codex-repo> --yes --force`.
+- If local codex is materially behind upstream, sync before diagnosing collab behavior differences.
+- If compatibility remains unstable, continue with non-collab execution path and document the degraded mode.
+
+## Depth-limit guardrail
+
+- Collab spawn depth is bounded. At max depth, `spawn_agent` will fail and the branch must execute directly.
+- Near max depth, collab may be disabled for newly spawned children; plan for leaf execution.
+- When depth errors appear, stop recursive delegation and switch to parent-driven execution.
+
+## Anti-patterns
+
+- Do not delegate one giant stream with vague ownership.
+- Do not spawn subagents before acceptance criteria are defined.
+- Do not merge subagent output without independent validation.
+- Do not copy raw multi-hundred-line logs into parent context.
+- Do not keep long single-agent execution in parent when a focused subagent can own it.
+- 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.
+
+## Completion checklist
+
+- At least one subagent was used for non-trivial work (or explicit reason documented for skipping).
+- Streams defined with clear ownership and acceptance criteria.
+- Subagent briefs include complete context and constraints.
+- All subagents completed or explicitly closed as blocked.
+- Parent synthesis includes concise decisions and evidence paths.
+- Parent-level review completed (standalone review or equivalent).
+- Collab lifecycle closed (`spawn_agent` -> `wait` -> `close_agent` per id) or degraded mode explicitly recorded.

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

@@ -0,0 +1,90 @@
+# Subagent Brief Template
+
+Use this template when spawning or re-scoping a subagent. Fill every field.
+
+## Template
+
+```text
+You are assigned a focused subtask. You are not alone in the codebase; other agents may edit unrelated files. Ignore unrelated edits and do not revert work you do not own.
+
+Task label:
+Objective:
+Timebox:
+Working repo/path:
+Base branch / comparison scope:
+
+Why this matters:
+- <1-3 bullets of product/technical context>
+
+Known context digest:
+- <current branch / relevant files / recent decisions>
+- <known runtime/tooling quirks in this repo>
+- <links/paths to specs, tasks, notes, or manifests>
+
+In scope:
+- <exact responsibilities>
+
+Out of scope:
+- <explicit exclusions>
+
+Ownership:
+- Files/paths you may edit: <paths>
+- Files/paths you must not edit: <paths>
+
+Acceptance criteria:
+- <bullet 1>
+- <bullet 2>
+- <bullet 3>
+
+Validation required:
+- Commands to run: <commands>
+- Minimum checks: <tests/lint/build/review expectations>
+
+Review:
+- If available, run the repo's standalone-review flow on your changes before final response (`--uncommitted` or `--base <branch>` as appropriate).
+- If review cannot run, provide a manual self-review for correctness, regressions, and missing tests.
+
+Output format (required):
+1. Outcome: done | partial | blocked
+2. Changes: <file list + short summary>
+3. Validation: <command> -> <pass/fail>
+4. Findings: <prioritized issues/risks, or "none found">
+5. Evidence: <paths/log references>
+6. Open questions: <only blockers>
+
+Keep the response concise. Put detailed notes in a file and return the path.
+```
+
+## Brief quality bar (required)
+
+- Include enough context so the subagent can act without back-and-forth.
+- Include explicit file ownership boundaries.
+- 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.
+
+## Fast variants
+
+### Research stream
+
+```text
+Objective: answer <question> with evidence.
+Deliverable: 3-7 bullets + key risks + recommendation.
+No code edits unless explicitly requested.
+```
+
+### Implementation stream
+
+```text
+Objective: implement <specific change>.
+Deliverable: patch + validation output + self-review notes.
+```
+
+### Verification stream
+
+```text
+Objective: validate <existing change>.
+Deliverable: failing/passing checks, defect list by severity, and minimal fix suggestions.
+No broad refactors.
+```
+

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)
 

package/skills/release/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: release
+description: Ship a signed tag + GitHub Release + npm publish for @kbediako/codex-orchestrator with low-friction, agent-first steps (PR -> watch-merge -> tag -> watch publish -> downstream smoke).
+---
+
+# Release (CO Maintainer)
+
+Use this skill when the user asks to ship a new CO version to npm/downstream users.
+If a global `release` skill is installed, prefer that and fall back to this bundled skill.
+
+## Guardrails (required)
+
+- Never publish from an unmerged branch: release tags must point at `main`.
+- Release tags must be **signed annotated tags** (`git tag -s vX.Y.Z -m "vX.Y.Z"`).
+- Confirm `gh auth status` is OK before any PR/release steps.
+- Prefer non-interactive commands; avoid anything that can hang on prompts.
+- If any check fails (Core Lane, Cloud Canary, CodeRabbit, release workflow), stop and fix before proceeding.
+
+## Workflow
+
+### 1) Preflight
+
+```bash
+gh auth status -h github.com
+git status -sb
+git checkout main
+git pull --ff-only
+```
+
+### 2) Version bump PR
+
+Pick a version (usually patch): `0.1.N+1`.
+
+```bash
+VERSION="0.1.20"
+BRANCH="task/release-${VERSION}"
+
+git checkout -b "$BRANCH"
+npm version "$VERSION" --no-git-tag-version
+git add package.json package-lock.json
+git commit -m "chore(release): bump version to ${VERSION}"
+git push -u origin "$BRANCH"
+```
+
+Open PR (use `--body-file` to avoid literal `\\n` rendering):
+
+```bash
+cat <<EOF > /tmp/pr-body.md
+## What
+- Bump version to ${VERSION}.
+
+## Why
+- Ship latest main to npm/downstream users.
+
+## How Tested
+- CI on this PR (Core Lane / Cloud Canary / CodeRabbit).
+EOF
+
+gh pr create --title "chore(release): bump version to ${VERSION}" --body-file /tmp/pr-body.md
+```
+
+Monitor + auto-merge once green:
+
+```bash
+PR_NUMBER="$(gh pr view --json number --jq .number)"
+codex-orchestrator pr watch-merge --pr "$PR_NUMBER" --auto-merge --delete-branch --quiet-minutes 1 --interval-seconds 20
+```
+
+### 3) Create signed tag + push
+
+```bash
+git checkout main
+git pull --ff-only
+
+TAG="v${VERSION}"
+git tag -s "$TAG" -m "$TAG"
+git tag -v "$TAG"
+git push origin "$TAG"
+```
+
+### 4) Watch the release workflow + confirm npm publish
+
+```bash
+TAG_SHA="$(git rev-list -n 1 "$TAG")"
+RUN_ID=""
+for i in {1..30}; do
+  RUN_ID="$(
+    gh run list \
+      --workflow release.yml \
+      --limit 20 \
+      --json databaseId,headBranch,headSha \
+      --jq ".[] | select((.headBranch==\"${TAG}\") or (.headSha==\"${TAG_SHA}\")) | .databaseId" \
+      | head -n 1 \
+      || true
+  )"
+  if [[ -n "$RUN_ID" && "$RUN_ID" != "null" ]]; then
+    break
+  fi
+  sleep 2
+done
+if [[ -z "$RUN_ID" || "$RUN_ID" == "null" ]]; then
+  echo "::error::No release workflow run found for ${TAG}."
+  exit 1
+fi
+gh run watch "$RUN_ID" --exit-status
+
+npm view @kbediako/codex-orchestrator version
+gh release view "v${VERSION}" --json url,assets --jq '{url: .url, assets: (.assets|map(.name))}'
+```
+
+### 5) Update global + downstream smoke
+
+```bash
+npm i -g @kbediako/codex-orchestrator@"${VERSION}"
+codex-orchestrator --version
+
+TMPDIR="$(mktemp -d)"
+cd "$TMPDIR"
+npx -y @kbediako/codex-orchestrator@"${VERSION}" --version
+npx -y @kbediako/codex-orchestrator@"${VERSION}" pr watch-merge --help | head -n 10
+```
+
+If the release included bundled skill changes, refresh local skills:
+
+```bash
+codex-orchestrator skills install --force
+```