@kbediako/codex-orchestrator 0.1.17 → 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/orchestrator/src/cli/rlm/symbolic.js

@@ -613,6 +613,33 @@ function formatDeliberationReason(reason) {
             return 'cadence';
     }
 }
+function attachDeliberationArtifactPaths(error, artifactPaths) {
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    if (artifactPaths) {
+        normalized.artifactPaths = artifactPaths;
+    }
+    return normalized;
+}
+function extractDeliberationArtifactPaths(error) {
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const rawPaths = error.artifactPaths;
+    if (!rawPaths || typeof rawPaths !== 'object') {
+        return undefined;
+    }
+    const typed = rawPaths;
+    if (typeof typed.prompt !== 'string' ||
+        typeof typed.output !== 'string' ||
+        typeof typed.meta !== 'string') {
+        return undefined;
+    }
+    return {
+        prompt: typed.prompt,
+        output: typed.output,
+        meta: typed.meta
+    };
+}
 function selectDeliberationReason(params) {
     if (params.iteration === 1) {
         return 'bootstrap';
@@ -678,27 +705,58 @@ async function runDeliberationStep(params) {
         maxSummaryBytes: params.options.maxSummaryBytes
     });
     const promptBytes = byteLength(prompt);
-    const deliberationDir = join(params.runDir, 'deliberation');
-    await mkdir(deliberationDir, { recursive: true });
-    const baseName = `iteration-${String(params.iteration).padStart(4, '0')}`;
-    const promptPath = join(deliberationDir, `${baseName}-prompt.txt`);
-    const outputPath = join(deliberationDir, `${baseName}-output.txt`);
-    const metaPath = join(deliberationDir, `${baseName}-meta.json`);
-    await writeFile(promptPath, prompt, 'utf8');
-    const output = await params.options.run(prompt, {
-        iteration: params.iteration,
-        reason: formatDeliberationReason(params.reason)
-    });
+    const shouldLogArtifacts = params.options.logArtifacts === true;
+    let artifactPaths;
+    let outputPath = null;
+    let metaPath = null;
+    if (shouldLogArtifacts) {
+        const deliberationDir = join(params.runDir, 'deliberation');
+        await mkdir(deliberationDir, { recursive: true });
+        const baseName = `iteration-${String(params.iteration).padStart(4, '0')}`;
+        const promptPath = join(deliberationDir, `${baseName}-prompt.txt`);
+        outputPath = join(deliberationDir, `${baseName}-output.txt`);
+        metaPath = join(deliberationDir, `${baseName}-meta.json`);
+        await writeFile(promptPath, prompt, 'utf8');
+        artifactPaths = {
+            prompt: relative(params.repoRoot, promptPath),
+            output: relative(params.repoRoot, outputPath),
+            meta: relative(params.repoRoot, metaPath)
+        };
+    }
+    let output;
+    try {
+        output = await params.options.run(prompt, {
+            iteration: params.iteration,
+            reason: formatDeliberationReason(params.reason)
+        });
+    }
+    catch (error) {
+        if (shouldLogArtifacts && outputPath && metaPath) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await writeFile(outputPath, '', 'utf8');
+            await writeFile(metaPath, JSON.stringify({
+                iteration: params.iteration,
+                reason: formatDeliberationReason(params.reason),
+                strategy: params.options.strategy,
+                prompt_bytes: promptBytes,
+                output_bytes: 0,
+                error: errorMessage
+            }, null, 2), 'utf8');
+        }
+        throw attachDeliberationArtifactPaths(error, artifactPaths);
+    }
     const brief = truncateUtf8ToBytes(output ?? '', params.options.maxSummaryBytes);
     const outputBytes = byteLength(brief);
-    await writeFile(outputPath, brief, 'utf8');
-    await writeFile(metaPath, JSON.stringify({
-        iteration: params.iteration,
-        reason: formatDeliberationReason(params.reason),
-        strategy: params.options.strategy,
-        prompt_bytes: promptBytes,
-        output_bytes: outputBytes
-    }, null, 2), 'utf8');
+    if (shouldLogArtifacts && outputPath && metaPath) {
+        await writeFile(outputPath, brief, 'utf8');
+        await writeFile(metaPath, JSON.stringify({
+            iteration: params.iteration,
+            reason: formatDeliberationReason(params.reason),
+            strategy: params.options.strategy,
+            prompt_bytes: promptBytes,
+            output_bytes: outputBytes
+        }, null, 2), 'utf8');
+    }
     return {
         record: {
             status: 'ran',
@@ -706,11 +764,7 @@ async function runDeliberationStep(params) {
             strategy: params.options.strategy,
             prompt_bytes: promptBytes,
             output_bytes: outputBytes,
-            artifact_paths: {
-                prompt: relative(params.repoRoot, promptPath),
-                output: relative(params.repoRoot, outputPath),
-                meta: relative(params.repoRoot, metaPath)
-            }
+            artifact_paths: artifactPaths
         },
         brief
     };
@@ -814,6 +868,7 @@ export async function runSymbolicLoop(options) {
                             status: 'error',
                             reason: formatDeliberationReason(reason),
                             strategy: deliberationOptions.strategy,
+                            artifact_paths: extractDeliberationArtifactPaths(error),
                             error: error instanceof Error ? error.message : String(error)
                         };
                         log(`Deliberation ${formatDeliberationReason(reason)} failed for iteration ${iteration}: ${deliberation.error}`);

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

@@ -235,11 +235,11 @@ async function resolveContextSource(env, fallbackText) {
 async function promptForValidator(candidates) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
-        console.log('Validator auto-detect found multiple candidates:');
+        logger.info('Validator auto-detect found multiple candidates:');
         candidates.forEach((candidate, index) => {
-            console.log(`  ${index + 1}) ${candidate.command} (${candidate.reason})`);
+            logger.info(`  ${index + 1}) ${candidate.command} (${candidate.reason})`);
         });
-        console.log('  n) none');
+        logger.info('  n) none');
         const answer = (await rl.question('Select validator [1-n or n for none]: ')).trim().toLowerCase();
         if (!answer || answer === 'n' || answer === 'none') {
             return null;
@@ -576,7 +576,7 @@ async function main() {
         state.final = { status, exitCode };
         await writeTerminalState(runDir, state);
         if (message) {
-            console.error(message);
+            logger.error(message);
         }
         process.exitCode = exitCode;
     };
@@ -725,7 +725,7 @@ async function main() {
             const detection = await detectValidator(repoRoot);
             if (detection.status === 'selected' && detection.command) {
                 validatorCommand = detection.command;
-                console.log(`Validator: ${detection.command} (${detection.reason ?? 'auto-detect'})`);
+                logger.info(`Validator: ${detection.command} (${detection.reason ?? 'auto-detect'})`);
             }
             else if (detection.status === 'ambiguous') {
                 if (isInteractive) {
@@ -743,7 +743,7 @@ async function main() {
                         mode,
                         context: contextInfo
                     });
-                    console.error(candidates);
+                    logger.error(candidates);
                     return;
                 }
             }
@@ -766,10 +766,10 @@ async function main() {
         }
     }
     if (validatorCommand === null) {
-        console.log('Validator: none');
+        logger.info('Validator: none');
     }
     else {
-        console.log(`Validator: ${validatorCommand}`);
+        logger.info(`Validator: ${validatorCommand}`);
     }
     const subagentsEnabled = envFlagEnabled(env.CODEX_SUBAGENTS) || envFlagEnabled(env.RLM_SUBAGENTS);
     const symbolicCollabEnabled = envFlagEnabled(env.RLM_SYMBOLIC_COLLAB);
@@ -779,6 +779,7 @@ async function main() {
     const symbolicDeliberationIncludeInPlanner = env.RLM_SYMBOLIC_DELIBERATION_INCLUDE_IN_PLANNER === undefined
         ? true
         : envFlagEnabled(env.RLM_SYMBOLIC_DELIBERATION_INCLUDE_IN_PLANNER);
+    const symbolicDeliberationLogArtifacts = envFlagEnabled(env.RLM_SYMBOLIC_DELIBERATION_LOG);
     const nonInteractive = shouldForceNonInteractive(env);
     if (mode === 'symbolic') {
         const budgets = {
@@ -894,6 +895,7 @@ async function main() {
                 maxRuns: deliberationMaxRuns,
                 maxSummaryBytes: deliberationMaxSummaryBytes,
                 includeInPlannerPrompt: symbolicDeliberationIncludeInPlanner,
+                logArtifacts: symbolicDeliberationLogArtifacts,
                 run: (prompt, _meta) => {
                     void _meta;
                     if (!symbolicCollabEnabled) {
@@ -914,7 +916,7 @@ async function main() {
         });
         const finalStatus = result.state.final?.status ?? 'unknown';
         const iterationCount = result.state.symbolic_iterations.length;
-        console.log(`RLM completed: status=${finalStatus} symbolic_iterations=${iterationCount} exit=${result.exitCode}`);
+        logger.info(`RLM completed: status=${finalStatus} symbolic_iterations=${iterationCount} exit=${result.exitCode}`);
         process.exitCode = result.exitCode;
         return;
     }
@@ -935,11 +937,11 @@ async function main() {
     });
     const finalStatus = result.state.final?.status ?? 'unknown';
     const iterationCount = result.state.iterations.length;
-    console.log(`RLM completed: status=${finalStatus} iterations=${iterationCount} exit=${result.exitCode}`);
+    logger.info(`RLM completed: status=${finalStatus} iterations=${iterationCount} exit=${result.exitCode}`);
     const hasTimeCap = resolvedMaxMinutes !== null && resolvedMaxMinutes > 0;
     const unboundedBudgetInvalid = validatorCommand === null && maxIterations === 0 && !hasTimeCap;
     if (finalStatus === 'invalid_config' && unboundedBudgetInvalid) {
-        console.error('Invalid configuration: --validator none with unbounded iterations and --max-minutes 0 would run forever. Fix: set --max-minutes / RLM_MAX_MINUTES to a positive value (default 2880), set --max-iterations to a positive value, or provide a validator.');
+        logger.error('Invalid configuration: --validator none with unbounded iterations and --max-minutes 0 would run forever. Fix: set --max-minutes / RLM_MAX_MINUTES to a positive value (default 2880), set --max-iterations to a positive value, or provide a validator.');
     }
     process.exitCode = result.exitCode;
 }

package/dist/orchestrator/src/cloud/CodexCloudTaskExecutor.js

@@ -5,7 +5,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { isoTimestamp } from '../cli/utils/time.js';
 const TASK_ID_PATTERN = /\btask_[a-z]_[a-f0-9]+\b/i;
 const MAX_LOG_CHARS = 32 * 1024;
-const STATUS_RETRY_LIMIT = 3;
+const STATUS_RETRY_LIMIT = 12;
 const STATUS_RETRY_BACKOFF_MS = 1500;
 const DEFAULT_LIST_LIMIT = 20;
 export function extractCloudTaskId(text) {
@@ -129,6 +129,8 @@ export class CodexCloudTaskExecutor {
             }
             const timeoutAt = Date.now() + cloudExecution.timeout_seconds * 1000;
             let statusRetries = 0;
+            let lastKnownStatus = cloudExecution.status;
+            let loggedNonZeroStatus = false;
             while (Date.now() < timeoutAt) {
                 const statusResult = await runCloudCommand(['cloud', 'status', taskId]);
                 cloudExecution.last_polled_at = this.now();
@@ -145,9 +147,14 @@ export class CodexCloudTaskExecutor {
                     await this.sleepFn(STATUS_RETRY_BACKOFF_MS * statusRetries);
                     continue;
                 }
+                if (statusResult.exitCode !== 0 && mapped !== 'unknown' && !loggedNonZeroStatus) {
+                    notes.push(`Cloud status returned exit ${statusResult.exitCode} with remote status ${mapped}; continuing to poll.`);
+                    loggedNonZeroStatus = true;
+                }
                 statusRetries = 0;
                 if (mapped !== 'unknown') {
                     cloudExecution.status = mapped;
+                    lastKnownStatus = mapped;
                 }
                 if (mapped === 'ready') {
                     notes.push(`Cloud task completed: ${taskId}`);
@@ -161,7 +168,7 @@ export class CodexCloudTaskExecutor {
             }
             if (cloudExecution.status === 'running' || cloudExecution.status === 'queued') {
                 cloudExecution.status = 'failed';
-                cloudExecution.error = `Timed out waiting for cloud task completion after ${cloudExecution.timeout_seconds}s.`;
+                cloudExecution.error = `Timed out waiting for cloud task completion after ${cloudExecution.timeout_seconds}s (last remote status: ${lastKnownStatus}, polls: ${cloudExecution.poll_count}).`;
             }
             if (cloudExecution.status === 'ready') {
                 const diffResult = await runCloudCommand(['cloud', 'diff', taskId]);

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.17",
+  "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

@@ -81,6 +81,16 @@ delegate.spawn({
 })
 ```
 
+## Collab lifecycle hygiene (required)
+
+When using collab tools (`spawn_agent` / `wait` / `close_agent`):
+
+- Treat each spawned `agent_id` as a resource that must be closed.
+- For every successful spawn, run `wait` then `close_agent` for the same id.
+- Keep a local list of spawned ids and run a final cleanup pass before returning.
+- On timeout/error paths, still close known ids before reporting failure.
+- If you see `agent thread limit reached`, stop spawning immediately, close known ids, and retry only after cleanup.
+
 ## RLM budget overrides (recommended defaults)
 
 If you want deeper recursion or longer wall-clock time for delegated runs, set RLM budgets on the delegation server:
@@ -112,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
 
@@ -123,3 +137,4 @@ Delegation MCP expects JSONL. Keep `codex-orchestrator` aligned with the current
 - **Run identifiers**: status/pause/cancel require `manifest_path`; question queue requires `parent_manifest_path`.
 - **Collab payload mismatch**: `spawn_agent` calls fail if they include both `message` and `items`.
 - **Collab depth limits**: recursive collab fan-out can fail near max depth; prefer shallow parent fan-out.
+- **Collab lifecycle leaks**: missing `close_agent` calls can exhaust thread slots and block future spawns (`agent thread limit reached`).

package/skills/delegation-usage/SKILL.md

@@ -20,6 +20,9 @@ Collab multi-agent mode is separate from delegation. For symbolic RLM subcalls t
 - Spawn returns an `agent_id` (thread id). Current TUI collab rendering is id-based; do not depend on custom visible agent names.
 - Subagents spawned through collab run with approval effectively set to `never`; design child tasks to avoid approval/escalation requirements.
 - Collab spawn depth is bounded. Near/at max depth, recursive delegation can fail or collab can be disabled in children; prefer shallow parent fan-out.
+- **Lifecycle is mandatory:** for every successful `spawn_agent`, run `wait` and then `close_agent` for that same id before task completion.
+- Keep a local list of spawned ids and run a final cleanup pass so no agent id is left unclosed on timeout/error paths.
+- If spawn fails with `agent thread limit reached`, stop spawning, close any known ids first, then surface a concise recovery note.
 
 ## Quick-start workflow (canned)
 
@@ -78,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)
 
@@ -174,3 +181,4 @@ repeat:
 - **Missing control files:** delegate tools rely on `control_endpoint.json` in the run directory; older runs may not have it.
 - **Collab payload mismatch:** `spawn_agent` rejects calls that include both `message` and `items`.
 - **Collab UI assumptions:** agent rows/records are id-based today; use explicit stream role text in prompts/artifacts for operator clarity.
+- **Collab lifecycle leaks:** missing `close_agent` calls accumulate open threads and can trigger `agent thread limit reached`; always finish `spawn -> wait -> close_agent` per id.

package/skills/docs-first/SKILL.md

@@ -16,6 +16,7 @@ Use this skill when a task needs a spec-driven workflow. The objective is to cre
 - TECH_SPEC: capture technical requirements (use `.agent/task/templates/tech-spec-template.md`; stored under `tasks/specs/<id>-<slug>.md`).
 - ACTION_PLAN: capture sequencing/milestones (use `.agent/task/templates/action-plan-template.md`).
 - Depth scales with scope, but all three docs are required.
+- For low-risk tiny edits, follow the bounded shortcut in `docs/micro-task-path.md` instead of long-form rewrites (still requires task/spec evidence).
 
 2) Register the TECH_SPEC and task
 - Add the TECH_SPEC to `tasks/index.json` (including `last_review`).

package/skills/standalone-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: standalone-review
-description: Use for ad-hoc/standalone reviews outside pipelines (fast checks during implementation or before handoff) using `codex review`.
+description: Use for required periodic cross-check reviews during implementation and before handoff using `codex review`.
 ---
 
 # Standalone Review
@@ -10,6 +10,17 @@ description: Use for ad-hoc/standalone reviews outside pipelines (fast checks du
 Use this skill when you need a fast, ad-hoc review without running a pipeline or collecting a manifest. It is ideal during implementation or for quick pre-flight checks.
 Before implementation, use it to review the task/spec against the user’s intent and record the approval in the PRD/TECH_SPEC or task notes.
 
+## Auto-trigger policy (required)
+
+Run this skill automatically whenever any condition is true:
+- You made code/config/script/test edits since the last standalone review.
+- You finished a meaningful chunk of work (default: behavior change or about 2+ files touched).
+- You are about to report completion, propose merge, or answer "what's next?" with recommendations.
+- You addressed external feedback (PR reviews, bot comments, or CI-fix patches).
+- 45 minutes of active implementation elapsed without a standalone review.
+
+If review execution is blocked, record why in task notes, then do manual diff review plus targeted tests before proceeding.
+
 ## Quick start
 
 Uncommitted diff:
@@ -39,6 +50,7 @@ codex review "Focus on correctness, regressions, edge cases; list missing tests.
 - Keep prompts short, specific, and test-oriented.
 
 2) Run the review often
+- Follow the auto-trigger policy above (not optional).
 - Run after each meaningful chunk of work.
 - Prefer targeted focus prompts for WIP reviews.