@kbediako/codex-orchestrator 0.1.37 → 0.2.0

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

@@ -14,7 +14,9 @@ const REQUIRED_BUCKET_PENDING = new Set(['pending']);
 const REQUIRED_BUCKET_FAILED = new Set(['fail', 'cancel', 'skipping']);
 const MERGEABLE_STATES = new Set(['CLEAN', 'HAS_HOOKS', 'UNSTABLE']);
 const ACTION_REQUIRED_MERGE_STATES = new Set(['BEHIND', 'DIRTY']);
-const BLOCKED_REVIEW_DECISIONS = new Set(['CHANGES_REQUESTED', 'REVIEW_REQUIRED']);
+const AUTOMATIC_BRANCH_RECOVERY_REASONS = new Set(['merge_state=BEHIND', 'merge_state=DIRTY']);
+const MERGE_BLOCKED_REVIEW_DECISIONS = new Set(['CHANGES_REQUESTED', 'REVIEW_REQUIRED']);
+const REVIEW_HANDOFF_BLOCKED_REVIEW_DECISIONS = new Set(['CHANGES_REQUESTED']);
 const DO_NOT_MERGE_LABEL = /do[\s_-]*not[\s_-]*merge/i;
 const ACTIONABLE_BOT_LOGINS = new Set([
     'chatgpt-codex-connector',
@@ -32,6 +34,31 @@ const BOT_MENTION_PATTERNS = {
 };
 const BOT_IN_PROGRESS_REACTION_CONTENT = new Set(['eyes']);
 const BOT_COMPLETE_REACTION_CONTENT = new Set(['+1', 'hooray', 'heart', 'rocket', 'laugh', 'confused']);
+const CODERABBIT_ISSUE_COMMENT_COMPLETION_PATTERNS = [
+    /No actionable comments were generated in the recent review/iu,
+    /Everything is clean\b/iu,
+    /PR is ready to merge\b/iu
+];
+const CODERABBIT_STATUS_NAMES = new Set(['coderabbit', 'coderabbitai', 'code rabbit', 'code rabbit ai']);
+function normalizeReadinessMode(rawValue) {
+    return typeof rawValue === 'string' && rawValue.trim().toLowerCase() === 'review' ? 'review' : 'merge';
+}
+function resolveBlockedReviewDecisions(readinessMode) {
+    return readinessMode === 'review'
+        ? REVIEW_HANDOFF_BLOCKED_REVIEW_DECISIONS
+        : MERGE_BLOCKED_REVIEW_DECISIONS;
+}
+function isReviewDecisionBlocked(reviewDecision, readinessMode) {
+    return resolveBlockedReviewDecisions(readinessMode).has(reviewDecision);
+}
+function doesMergeStateBlockReady(mergeStateStatus, readinessMode) {
+    return readinessMode === 'review'
+        ? ACTION_REQUIRED_MERGE_STATES.has(mergeStateStatus)
+        : !MERGEABLE_STATES.has(mergeStateStatus);
+}
+function doesMergeStateRequireAuthorAction(mergeStateStatus) {
+    return ACTION_REQUIRED_MERGE_STATES.has(mergeStateStatus);
+}
 class PrWatchMergeExitError extends Error {
     constructor(message, exitCode = 1) {
         super(message);
@@ -39,6 +66,24 @@ class PrWatchMergeExitError extends Error {
         this.exitCode = exitCode;
     }
 }
+class GhCommandError extends Error {
+    constructor(args, result) {
+        const detail = result.stderr || result.stdout || `exit code ${result.exitCode}`;
+        super(`gh ${args.join(' ')} failed: ${detail}`);
+        this.name = 'GhCommandError';
+        this.args = [...args];
+        this.exitCode = result.exitCode;
+        this.stdout = result.stdout;
+        this.stderr = result.stderr;
+    }
+}
+class GitHubRateLimitError extends Error {
+    constructor(rateLimit, message = null) {
+        super(message || formatGitHubRateLimitStatus(rateLimit));
+        this.name = 'GitHubRateLimitError';
+        this.githubRateLimit = rateLimit;
+    }
+}
 const PR_QUERY = `
 query($owner:String!, $repo:String!, $number:Int!) {
   repository(owner:$owner, name:$repo) {
@@ -74,11 +119,14 @@ query($owner:String!, $repo:String!, $number:Int!) {
                     name
                     status
                     conclusion
+                    startedAt
+                    completedAt
                     detailsUrl
                   }
                   ... on StatusContext {
                     context
                     state
+                    createdAt
                     targetUrl
                   }
                 }
@@ -141,6 +189,255 @@ function formatDuration(ms) {
 function log(message) {
     console.log(`[${new Date().toISOString()}] ${message}`);
 }
+function sanitizeRateLimitMessage(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.replace(/\s+/gu, ' ').trim();
+    return normalized.length > 0 ? normalized.slice(0, 500) : null;
+}
+function inferGitHubApiSurfaceFromArgs(args) {
+    if (!Array.isArray(args)) {
+        return 'unknown';
+    }
+    if (args[0] === 'api' && args.includes('graphql')) {
+        return 'graphql';
+    }
+    if (args[0] === 'api' || (args[0] === 'pr' && args[1] === 'checks')) {
+        return 'rest';
+    }
+    return 'unknown';
+}
+function extractTextFromRateLimitInput(input) {
+    if (input instanceof Error) {
+        const pieces = [input.message];
+        if (typeof input.stderr === 'string') {
+            pieces.push(input.stderr);
+        }
+        if (typeof input.stdout === 'string') {
+            pieces.push(input.stdout);
+        }
+        return pieces.filter(Boolean).join('\n');
+    }
+    if (typeof input === 'string') {
+        return input;
+    }
+    if (input && typeof input === 'object') {
+        const pieces = [];
+        if (typeof input.message === 'string') {
+            pieces.push(input.message);
+        }
+        if (typeof input.stderr === 'string') {
+            pieces.push(input.stderr);
+        }
+        if (typeof input.stdout === 'string') {
+            pieces.push(input.stdout);
+        }
+        if (Array.isArray(input.errors)) {
+            for (const error of input.errors) {
+                if (typeof error?.message === 'string') {
+                    pieces.push(error.message);
+                }
+                if (typeof error?.type === 'string') {
+                    pieces.push(error.type);
+                }
+            }
+        }
+        return pieces.filter(Boolean).join('\n');
+    }
+    return '';
+}
+function parseHttpStatusFromText(text) {
+    const match = text.match(/\bHTTP\s+(?<status>403|429)\b/iu) ||
+        text.match(/\bstatus(?:\s+code)?["':=\s]+(?<status>403|429)\b/iu) ||
+        text.match(/"status"\s*:\s*(?<status>403|429)\b/iu);
+    const parsed = match?.groups?.status ? Number.parseInt(match.groups.status, 10) : null;
+    return Number.isInteger(parsed) ? parsed : null;
+}
+function parseHeaderSeconds(text, headerName) {
+    const escapedHeaderName = headerName.replace(/[\\^$*+?.()|[\]{}]/gu, '\\$&');
+    const pattern = new RegExp(`${escapedHeaderName}["'\\s:=]+(?<value>\\d+)`, 'iu');
+    const match = text.match(pattern);
+    if (!match?.groups?.value) {
+        return null;
+    }
+    const parsed = Number.parseInt(match.groups.value, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+function parseIsoTimestampFromText(text) {
+    const match = text.match(/\b(?<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)\b/u);
+    return match?.groups?.timestamp ?? null;
+}
+function isoFromEpochSeconds(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return null;
+    }
+    const millis = value * 1000;
+    return isoFromMillis(millis);
+}
+function isoFromMillis(value) {
+    if (!Number.isFinite(value)) {
+        return null;
+    }
+    try {
+        return new Date(value).toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+function futureDelayMsFromSeconds(nowMs, seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds)) {
+        return null;
+    }
+    const delayMs = seconds * 1000;
+    if (!Number.isFinite(delayMs) || delayMs <= 0) {
+        return null;
+    }
+    const targetMs = nowMs + delayMs;
+    return isoFromMillis(targetMs) ? delayMs : null;
+}
+function computeRetryAt(nowMs, retryAfterSeconds, resetAt) {
+    const retryDelayMs = futureDelayMsFromSeconds(nowMs, retryAfterSeconds);
+    if (retryDelayMs !== null) {
+        return isoFromMillis(nowMs + retryDelayMs);
+    }
+    if (typeof resetAt === 'string' && resetAt.trim().length > 0) {
+        return resetAt;
+    }
+    return null;
+}
+function hasRateLimitSignal(text) {
+    return (/\b(api\s+rate\s+limit\s+exceeded|rate\s+limit\s+exceeded|secondary\s+(?:rate\s+)?limit|RATE_LIMITED)\b/iu.test(text)
+        || /\b(?:retry-after|x-ratelimit-reset)\b/iu.test(text)
+        || /\bHTTP\s+429\b/iu.test(text));
+}
+export function resolveGitHubRateLimitStatus(input, options = {}) {
+    if (input instanceof GitHubRateLimitError && input.githubRateLimit) {
+        return input.githubRateLimit;
+    }
+    if (input && typeof input === 'object' && input.kind === 'github_rate_limited') {
+        return input;
+    }
+    const text = extractTextFromRateLimitInput(input);
+    const isCommandOrRawTextInput = typeof input === 'string'
+        || input instanceof Error
+        || (input
+            && typeof input === 'object'
+            && (Array.isArray(input.args)
+                || typeof input.exitCode === 'number'
+                || typeof input.stderr === 'string'
+                || typeof input.stdout === 'string'));
+    const structuredStatus = input && typeof input === 'object' && Number.isInteger(input.status)
+        ? Number(input.status)
+        : null;
+    const status = structuredStatus === 403 || structuredStatus === 429
+        ? structuredStatus
+        : isCommandOrRawTextInput ? parseHttpStatusFromText(text) : null;
+    const retryAfterSeconds = isCommandOrRawTextInput ? parseHeaderSeconds(text, 'retry-after') : null;
+    const resetEpochSeconds = isCommandOrRawTextInput ? parseHeaderSeconds(text, 'x-ratelimit-reset') : null;
+    const remainingRequests = isCommandOrRawTextInput ? parseHeaderSeconds(text, 'x-ratelimit-remaining') : null;
+    const hasRateLimitText = /\b(api\s+rate\s+limit\s+exceeded|secondary\s+(?:rate\s+)?limit|RATE_LIMITED)\b/iu.test(text);
+    const hasGraphqlRateLimitPayload = Array.isArray(input?.errors) &&
+        input.errors.some((error) => typeof error?.type === 'string' && error.type.trim().toUpperCase() === 'RATE_LIMITED');
+    const hasProtocolRateLimitEvidence = hasGraphqlRateLimitPayload
+        || status === 429
+        || retryAfterSeconds !== null
+        || (resetEpochSeconds !== null && remainingRequests === 0)
+        || (isCommandOrRawTextInput && hasRateLimitText);
+    if (!hasProtocolRateLimitEvidence ||
+        (!hasRateLimitSignal(text) && status !== 429)) {
+        return null;
+    }
+    const args = Array.isArray(input?.args) ? input.args : [];
+    const surface = options.surface ??
+        (/\bgraphql\b/iu.test(text) ? 'graphql' : inferGitHubApiSurfaceFromArgs(args));
+    const resetAt = isoFromEpochSeconds(resetEpochSeconds) ?? parseIsoTimestampFromText(text);
+    const nowMs = typeof options.nowMs === 'number' && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const limitType = /\bsecondary\b/iu.test(text) ? 'secondary' : 'primary';
+    return {
+        kind: 'github_rate_limited',
+        surface,
+        limit_type: limitType,
+        status,
+        reset_at: resetAt,
+        retry_after_seconds: retryAfterSeconds,
+        retry_at: computeRetryAt(nowMs, retryAfterSeconds, resetAt),
+        message: sanitizeRateLimitMessage(text)
+    };
+}
+export function formatGitHubRateLimitStatus(rateLimit) {
+    if (!rateLimit || typeof rateLimit !== 'object') {
+        return 'GitHub API rate limit is active.';
+    }
+    const parts = [
+        'GitHub API rate limit',
+        `surface=${rateLimit.surface ?? 'unknown'}`,
+        `type=${rateLimit.limit_type ?? 'unknown'}`
+    ];
+    if (rateLimit.status) {
+        parts.push(`status=${rateLimit.status}`);
+    }
+    if (rateLimit.retry_at) {
+        parts.push(`retry_at=${rateLimit.retry_at}`);
+    }
+    else if (rateLimit.reset_at) {
+        parts.push(`reset_at=${rateLimit.reset_at}`);
+    }
+    return parts.join(' | ');
+}
+function throwIfGitHubRateLimited(input, options = {}) {
+    const rateLimit = resolveGitHubRateLimitStatus(input, options);
+    if (rateLimit) {
+        throw new GitHubRateLimitError(rateLimit);
+    }
+}
+function stableJitterMs(seed, maxJitterMs) {
+    if (!maxJitterMs || maxJitterMs <= 0) {
+        return 0;
+    }
+    const text = String(seed ?? 'github-rate-limit');
+    let hash = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        hash = (hash * 31 + text.charCodeAt(index)) >>> 0;
+    }
+    return hash % (maxJitterMs + 1);
+}
+export function planGitHubRateLimitBackoff(rateLimit, options = {}) {
+    const nowMs = typeof options.nowMs === 'number' && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const fallbackMs = typeof options.fallbackMs === 'number' && Number.isFinite(options.fallbackMs) && options.fallbackMs > 0
+        ? options.fallbackMs
+        : DEFAULT_INTERVAL_SECONDS * 1000;
+    const maxJitterMs = typeof options.maxJitterMs === 'number' && Number.isFinite(options.maxJitterMs) && options.maxJitterMs >= 0
+        ? Math.round(options.maxJitterMs)
+        : 5000;
+    const candidates = [];
+    const retryAfterMs = futureDelayMsFromSeconds(nowMs, rateLimit?.retry_after_seconds);
+    if (retryAfterMs !== null) {
+        candidates.push(retryAfterMs);
+    }
+    const retryAtMs = parseTimestampMs(rateLimit?.retry_at);
+    if (retryAtMs !== null) {
+        const retryDelayMs = retryAtMs - nowMs;
+        if (retryDelayMs > 0) {
+            candidates.push(retryDelayMs);
+        }
+    }
+    const resetAtMs = parseTimestampMs(rateLimit?.reset_at);
+    if (resetAtMs !== null) {
+        const resetDelayMs = resetAtMs - nowMs;
+        if (resetDelayMs > 0) {
+            candidates.push(resetDelayMs);
+        }
+    }
+    const baseMs = candidates.length > 0 ? Math.max(...candidates) : fallbackMs;
+    const jitterMs = stableJitterMs(options.jitterSeed, maxJitterMs);
+    const plannedMs = Math.max(1000, baseMs + jitterMs);
+    const remainingMs = typeof options.remainingMs === 'number' && Number.isFinite(options.remainingMs)
+        ? Math.max(0, options.remainingMs)
+        : null;
+    return remainingMs === null ? plannedMs : Math.min(plannedMs, remainingMs);
+}
 function parseTimestampMs(value) {
     if (typeof value !== 'string' || value.trim().length === 0) {
         return null;
@@ -148,6 +445,12 @@ function parseTimestampMs(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? parsed : null;
 }
+export function isNoRequiredChecksReportedErrorMessage(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return false;
+    }
+    return /no required checks reported\b/iu.test(value);
+}
 function maxTimestamp(values) {
     let max = null;
     for (const value of values) {
@@ -160,6 +463,12 @@ function maxTimestamp(values) {
     }
     return max;
 }
+function isCoderabbitStatusName(value) {
+    const normalized = typeof value === 'string'
+        ? value.trim().toLowerCase().replace(/\s+/gu, ' ')
+        : '';
+    return CODERABBIT_STATUS_NAMES.has(normalized);
+}
 function resolveBotKindFromLogin(login) {
     const normalized = normalizeLogin(login);
     if (!normalized) {
@@ -243,16 +552,22 @@ function parseMergeMethod(rawValue) {
     return normalized;
 }
 export function printPrWatchMergeHelp(options = {}) {
+    const readinessMode = normalizeReadinessMode(options.readinessMode);
+    const isReviewMode = readinessMode === 'review';
     const usageCommand = typeof options.usage === 'string' && options.usage.trim().length > 0
         ? options.usage.trim()
-        : 'codex-orchestrator pr watch-merge';
+        : isReviewMode
+            ? 'codex-orchestrator pr ready-review'
+            : 'codex-orchestrator pr watch-merge';
     const defaultAutoMerge = typeof options.defaultAutoMerge === 'boolean'
         ? options.defaultAutoMerge
         : envFlagEnabled(process.env.PR_MONITOR_AUTO_MERGE, false);
     const defaultExitOnActionRequired = Boolean(options.defaultExitOnActionRequired);
     console.log(`Usage: ${usageCommand} [options]
 
-Monitor PR checks/reviews with polling and optionally merge after a quiet window.
+${isReviewMode
+        ? 'Monitor PR checks/reviews with polling and report when review handoff is safe after a bounded automated-feedback drain.'
+        : 'Monitor PR checks/reviews with polling and optionally merge after a quiet window.'}
 
 Options:
   --pr <number>             PR number (default: PR for current branch)
@@ -261,25 +576,29 @@ Options:
   --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})
+${isReviewMode ? '' : `  --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
+`}
   --exit-on-action-required Exit non-zero when author action is required
   --no-exit-on-action-required Keep monitoring even when author action is required
-  --dry-run                 Never call gh pr merge (report only)
+  --dry-run                 Never call gh pr merge/update-branch (report only)
   -h, --help                Show this help message
 
 Environment:
-  PR_MONITOR_AUTO_MERGE=1       Default auto-merge on (current default: ${defaultAutoMerge ? 'on' : 'off'})
-  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>`);
+  PR_MONITOR_TIMEOUT_MINUTES=<n>${isReviewMode ? '' : `
+  PR_MONITOR_AUTO_MERGE=1       Default auto-merge on (current default: ${defaultAutoMerge ? 'on' : 'off'})
+  PR_MONITOR_DELETE_BRANCH=1    Default delete branch on merge
+  PR_MONITOR_MERGE_METHOD=<method>`}`);
     if (defaultExitOnActionRequired) {
-        console.log('  resolve-merge default: exit-on-action-required is on');
+        console.log(`  ${isReviewMode ? 'ready-review' : 'resolve-merge'} default: exit-on-action-required is on`);
+    }
+    if (isReviewMode) {
+        console.log('  ready-review treats REVIEW_REQUIRED as informational; CHANGES_REQUESTED and actionable machine feedback still block handoff.');
     }
 }
 async function runGh(args, { allowFailure = false } = {}) {
@@ -315,8 +634,7 @@ async function runGh(args, { allowFailure = false } = {}) {
                 resolve(result);
                 return;
             }
-            const detail = result.stderr || result.stdout || `exit code ${exitCode}`;
-            reject(new Error(`gh ${args.join(' ')} failed: ${detail}`));
+            reject(new GhCommandError(args, result));
         });
     });
 }
@@ -354,20 +672,49 @@ async function runGit(args, { allowFailure = false } = {}) {
     });
 }
 async function runGhJson(args) {
-    const result = await runGh(args);
+    let result;
+    const surface = inferGitHubApiSurfaceFromArgs(args);
+    try {
+        result = await runGh(args);
+    }
+    catch (error) {
+        throwIfGitHubRateLimited(error, { surface });
+        throw error;
+    }
     try {
-        return JSON.parse(result.stdout);
+        const parsed = JSON.parse(result.stdout);
+        throwIfGitHubRateLimited(parsed, { surface });
+        return parsed;
     }
     catch (error) {
+        if (error instanceof GitHubRateLimitError) {
+            throw error;
+        }
+        throwIfGitHubRateLimited(result.stdout, { surface });
         throw new Error(`Failed to parse JSON from gh ${args.join(' ')}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 async function runGhJsonSlurped(args) {
-    const result = await runGh([...args, '--paginate', '--slurp']);
+    const ghArgs = [...args, '--paginate', '--slurp'];
+    let result;
+    const surface = inferGitHubApiSurfaceFromArgs(ghArgs);
     try {
-        return JSON.parse(result.stdout);
+        result = await runGh(ghArgs);
     }
     catch (error) {
+        throwIfGitHubRateLimited(error, { surface });
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        throwIfGitHubRateLimited(parsed, { surface });
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof GitHubRateLimitError) {
+            throw error;
+        }
+        throwIfGitHubRateLimited(result.stdout, { surface });
         throw new Error(`Failed to parse paginated JSON from gh ${args.join(' ')}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
@@ -436,6 +783,9 @@ export function buildPrNumberViewArgs(owner, repo) {
     }
     return args;
 }
+export function buildPrUpdateBranchArgs({ owner, repo, prNumber }) {
+    return ['pr', 'update-branch', String(prNumber), '--repo', `${owner}/${repo}`];
+}
 async function resolvePrNumber(prArg, owner, repo) {
     if (prArg !== undefined) {
         return parseInteger('pr', prArg, null);
@@ -502,6 +852,189 @@ function summarizeChecks(nodes) {
     }
     return summary;
 }
+function normalizeRollupCheckState(node) {
+    if (!node || typeof node !== 'object') {
+        return null;
+    }
+    const typeName = typeof node.__typename === 'string' ? node.__typename : '';
+    if (typeName === 'CheckRun') {
+        const name = typeof node.name === 'string' && node.name.trim() ? node.name.trim() : 'check-run';
+        const status = normalizeEnum(node.status);
+        const startedAt = typeof node.startedAt === 'string' ? node.startedAt : null;
+        const completedAt = typeof node.completedAt === 'string' ? node.completedAt : null;
+        const observedAt = status === 'COMPLETED' ? completedAt ?? startedAt : startedAt;
+        const observedAtMs = parseTimestampMs(observedAt);
+        if (status !== 'COMPLETED') {
+            return {
+                name,
+                state: 'pending',
+                signal: status || 'PENDING',
+                observedAt,
+                observedAtMs,
+                detailsUrl: typeof node.detailsUrl === 'string' ? node.detailsUrl : null
+            };
+        }
+        const conclusion = normalizeEnum(node.conclusion);
+        if (conclusion === 'SUCCESS') {
+            return {
+                name,
+                state: 'success',
+                signal: conclusion || 'SUCCESS',
+                observedAt,
+                observedAtMs,
+                detailsUrl: typeof node.detailsUrl === 'string' ? node.detailsUrl : null
+            };
+        }
+        return {
+            name,
+            state: 'failed',
+            signal: conclusion || 'UNKNOWN',
+            observedAt,
+            observedAtMs,
+            detailsUrl: typeof node.detailsUrl === 'string' ? node.detailsUrl : null
+        };
+    }
+    if (typeName === 'StatusContext') {
+        const name = typeof node.context === 'string' && node.context.trim() ? node.context.trim() : 'status-context';
+        const state = normalizeEnum(node.state);
+        const observedAt = typeof node.createdAt === 'string' ? node.createdAt : null;
+        const observedAtMs = parseTimestampMs(observedAt);
+        if (STATUS_CONTEXT_PENDING_STATES.has(state)) {
+            return {
+                name,
+                state: 'pending',
+                signal: state || 'PENDING',
+                observedAt,
+                observedAtMs,
+                detailsUrl: typeof node.targetUrl === 'string' ? node.targetUrl : null
+            };
+        }
+        if (STATUS_CONTEXT_PASS_STATES.has(state)) {
+            return {
+                name,
+                state: 'success',
+                signal: state || 'SUCCESS',
+                observedAt,
+                observedAtMs,
+                detailsUrl: typeof node.targetUrl === 'string' ? node.targetUrl : null
+            };
+        }
+        return {
+            name,
+            state: 'failed',
+            signal: state || 'UNKNOWN',
+            observedAt,
+            observedAtMs,
+            detailsUrl: typeof node.targetUrl === 'string' ? node.targetUrl : null
+        };
+    }
+    return null;
+}
+function summarizeCoderabbitStatusCheckRollup(nodes) {
+    const contexts = [];
+    if (Array.isArray(nodes)) {
+        for (const node of nodes) {
+            const context = normalizeRollupCheckState(node);
+            if (!context || !isCoderabbitStatusName(context.name)) {
+                continue;
+            }
+            contexts.push(context);
+        }
+    }
+    let state = 'missing';
+    if (contexts.some((context) => context.state === 'pending')) {
+        state = 'pending';
+    }
+    else if (contexts.some((context) => context.state === 'failed')) {
+        state = 'failed';
+    }
+    else if (contexts.some((context) => context.state === 'success')) {
+        state = 'success';
+    }
+    const latestSuccessAtMs = maxTimestamp(contexts
+        .filter((context) => context.state === 'success')
+        .map((context) => context.observedAtMs));
+    return {
+        state,
+        contexts,
+        latestSuccessAtMs
+    };
+}
+function resolveCoderabbitPendingBlockerSignal(coderabbitStatusCheckRollup, requestAtMs = null) {
+    if (!coderabbitStatusCheckRollup || typeof coderabbitStatusCheckRollup !== 'object') {
+        return 'status_check_rollup=unknown';
+    }
+    const names = Array.isArray(coderabbitStatusCheckRollup.contexts)
+        ? coderabbitStatusCheckRollup.contexts.map((context) => context.name).filter(Boolean)
+        : [];
+    const suffix = names.length > 0 ? `:${names.join('+')}` : '';
+    const baseSignal = `status_check_rollup=${coderabbitStatusCheckRollup.state || 'unknown'}${suffix}`;
+    if (coderabbitStatusCheckRollup.state !== 'success') {
+        return baseSignal;
+    }
+    if (typeof requestAtMs !== 'number' || !Number.isFinite(requestAtMs)) {
+        return `${baseSignal};request_time=unknown`;
+    }
+    const latestSuccessAtMs = coderabbitStatusCheckRollup.latestSuccessAtMs;
+    if (typeof latestSuccessAtMs !== 'number' || !Number.isFinite(latestSuccessAtMs)) {
+        return `${baseSignal};success_time=unknown`;
+    }
+    if (latestSuccessAtMs <= requestAtMs) {
+        return `${baseSignal};success_before_request`;
+    }
+    return baseSignal;
+}
+function resolveEffectiveBotRereviewSignals({ pendingBots, coderabbitStatusCheckRollup, requestTimesByBot, hasUnresolvedThread, unacknowledgedBotFeedbackCount, botFeedbackFetchError }) {
+    const rawPendingBots = Array.isArray(pendingBots) ? pendingBots : [];
+    const effectivePendingBots = [];
+    const clearedPendingBots = [];
+    const canTrustResolvedFeedbackTruth = !hasUnresolvedThread && unacknowledgedBotFeedbackCount === 0 && botFeedbackFetchError !== true;
+    const requestTimes = requestTimesByBot && typeof requestTimesByBot === 'object' ? requestTimesByBot : {};
+    const coderabbitRequestAtMs = typeof requestTimes[BOT_KIND_LABELS.coderabbit] === 'number' &&
+        Number.isFinite(requestTimes[BOT_KIND_LABELS.coderabbit])
+        ? requestTimes[BOT_KIND_LABELS.coderabbit]
+        : null;
+    const coderabbitSuccessAtMs = typeof coderabbitStatusCheckRollup?.latestSuccessAtMs === 'number' &&
+        Number.isFinite(coderabbitStatusCheckRollup.latestSuccessAtMs)
+        ? coderabbitStatusCheckRollup.latestSuccessAtMs
+        : null;
+    const coderabbitSuccessAfterRequest = coderabbitStatusCheckRollup?.state === 'success' &&
+        coderabbitRequestAtMs !== null &&
+        coderabbitSuccessAtMs !== null &&
+        coderabbitSuccessAtMs > coderabbitRequestAtMs;
+    for (const bot of rawPendingBots) {
+        const isCoderabbit = bot === BOT_KIND_LABELS.coderabbit;
+        if (isCoderabbit &&
+            coderabbitSuccessAfterRequest &&
+            canTrustResolvedFeedbackTruth) {
+            clearedPendingBots.push(bot);
+            continue;
+        }
+        effectivePendingBots.push(bot);
+    }
+    return {
+        rawPendingBots,
+        effectivePendingBots,
+        clearedPendingBots,
+        coderabbit: {
+            statusCheckRollup: coderabbitStatusCheckRollup,
+            stalePendingCleared: clearedPendingBots.includes(BOT_KIND_LABELS.coderabbit),
+            latestRequestAtMs: coderabbitRequestAtMs,
+            latestSuccessAtMs: coderabbitSuccessAtMs,
+            successAfterRequest: coderabbitSuccessAfterRequest,
+            pendingBlockerSignal: resolveCoderabbitPendingBlockerSignal(coderabbitStatusCheckRollup, coderabbitRequestAtMs)
+        }
+    };
+}
+function formatBotRereviewPendingGateReason(pendingBots, diagnostics) {
+    const parts = pendingBots.map((bot) => {
+        if (bot === BOT_KIND_LABELS.coderabbit) {
+            return `${bot}(${diagnostics?.coderabbit?.pendingBlockerSignal ?? 'status_check_rollup=unknown'})`;
+        }
+        return bot;
+    });
+    return `bot_rereview_pending=${parts.join(',')}`;
+}
 export function summarizeRequiredChecks(entries) {
     const summary = {
         total: 0,
@@ -569,17 +1102,90 @@ export function resolveCachedRequiredChecksSummary(previousCache, currentHeadOid
     if (!previousCache || typeof previousCache !== 'object') {
         return null;
     }
-    const cachedHeadOid = typeof previousCache.headOid === 'string' ? previousCache.headOid : null;
+    const requiredChecksCache = previousCache.requiredChecksForNextPoll && typeof previousCache.requiredChecksForNextPoll === 'object'
+        ? previousCache.requiredChecksForNextPoll
+        : previousCache;
+    const cachedHeadOid = typeof requiredChecksCache.headOid === 'string' ? requiredChecksCache.headOid : null;
     if (!cachedHeadOid || !currentHeadOid || cachedHeadOid !== currentHeadOid) {
         return null;
     }
-    return hasRequiredChecksSummary(previousCache.summary) ? previousCache.summary : null;
+    return hasRequiredChecksSummary(requiredChecksCache.summary) ? requiredChecksCache.summary : null;
 }
-export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFeedback = null) {
+function resolveReusableFanoutCache(previousCache, currentHeadOid, currentUpdatedAt) {
+    if (!previousCache || typeof previousCache !== 'object') {
+        return null;
+    }
+    const cachedHeadOid = typeof previousCache.headOid === 'string' ? previousCache.headOid : null;
+    const cachedUpdatedAt = typeof previousCache.updatedAt === 'string' ? previousCache.updatedAt : null;
+    if (!cachedHeadOid || !cachedUpdatedAt || !currentHeadOid || !currentUpdatedAt) {
+        return null;
+    }
+    if (cachedHeadOid !== currentHeadOid || cachedUpdatedAt !== currentUpdatedAt) {
+        return null;
+    }
+    if (previousCache.requiredChecksFetchError === true
+        || previousCache.inlineBotFeedback?.fetchError === true
+        || previousCache.botRereviewSignals?.fetchError === true) {
+        return null;
+    }
+    if (!isReusableBotFanoutClean(previousCache.inlineBotFeedback, previousCache.botRereviewSignals)) {
+        return null;
+    }
+    return previousCache;
+}
+function isReusableBotFanoutClean(inlineBotFeedback, botRereviewSignals) {
+    if (!inlineBotFeedback || typeof inlineBotFeedback !== 'object') {
+        return false;
+    }
+    if (!botRereviewSignals || typeof botRereviewSignals !== 'object') {
+        return false;
+    }
+    if (inlineBotFeedback.fetchError === true || botRereviewSignals.fetchError === true) {
+        return false;
+    }
+    if (inlineBotFeedback.unacknowledgedCount !== 0) {
+        return false;
+    }
+    if (Array.isArray(botRereviewSignals.pendingBots) &&
+        botRereviewSignals.pendingBots.length > 0) {
+        return false;
+    }
+    if (Array.isArray(botRereviewSignals.inProgressBots) &&
+        botRereviewSignals.inProgressBots.length > 0) {
+        return false;
+    }
+    return true;
+}
+function buildReusableFanoutCache(input) {
+    const requiredChecksForNextPoll = input.requiredChecks
+        ? {
+            headOid: input.headOid,
+            summary: input.requiredChecks
+        }
+        : null;
+    if (input.requiredChecksResult?.fetchError === true
+        || input.inlineBotFeedback?.fetchError === true
+        || input.botRereviewSignals?.fetchError === true) {
+        return requiredChecksForNextPoll;
+    }
+    if (!isReusableBotFanoutClean(input.inlineBotFeedback, input.botRereviewSignals)) {
+        return requiredChecksForNextPoll;
+    }
+    return {
+        headOid: input.headOid,
+        updatedAt: input.updatedAt,
+        requiredChecksFetchError: false,
+        requiredChecksForNextPoll,
+        inlineBotFeedback: input.inlineBotFeedback,
+        botRereviewSignals: input.botRereviewSignals
+    };
+}
+export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFeedback = null, options = {}) {
     const pr = response?.data?.repository?.pullRequest;
     if (!pr) {
         throw new Error('GraphQL response missing pullRequest payload.');
     }
+    const readinessMode = normalizeReadinessMode(options.readinessMode);
     const labels = Array.isArray(pr.labels?.nodes)
         ? pr.labels.nodes
             .map((item) => (item && typeof item.name === 'string' ? item.name.trim() : ''))
@@ -592,6 +1198,7 @@ export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFe
     const contexts = pr.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts?.nodes;
     const checkNodes = Array.isArray(contexts) ? contexts : [];
     const checks = summarizeChecks(checkNodes);
+    const coderabbitStatusCheckRollup = summarizeCoderabbitStatusCheckRollup(checkNodes);
     const requiredCheckSummary = requiredChecks && typeof requiredChecks === 'object' && requiredChecks.total > 0 ? requiredChecks : null;
     const unacknowledgedBotFeedbackCount = inlineBotFeedback && typeof inlineBotFeedback.unacknowledgedCount === 'number'
         ? inlineBotFeedback.unacknowledgedCount
@@ -601,8 +1208,13 @@ export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFe
         ? inlineBotFeedback.rereview
         : null;
     const botRereviewFetchError = botRereview?.fetchError === true;
-    const botRereviewPending = Array.isArray(botRereview?.pendingBots) ? botRereview.pendingBots : [];
+    const rawBotRereviewPending = Array.isArray(botRereview?.pendingBots) ? botRereview.pendingBots : [];
     const botRereviewInProgress = Array.isArray(botRereview?.inProgressBots) ? botRereview.inProgressBots : [];
+    const requiredChecksQueryFailed = options.requiredChecksQueryFailed === true;
+    const githubRateLimits = Array.isArray(options.githubRateLimits)
+        ? options.githubRateLimits.map((entry) => resolveGitHubRateLimitStatus(entry)).filter(Boolean)
+        : [];
+    const githubRateLimit = githubRateLimits[0] ?? null;
     const coderabbitReviewMeta = botRereview?.coderabbit && typeof botRereview.coderabbit === 'object'
         ? botRereview.coderabbit
         : { actionableCount: 0, outsideDiffCount: 0, nitpickCount: 0 };
@@ -612,6 +1224,15 @@ export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFe
     const mergeStateStatus = normalizeEnum(pr.mergeStateStatus);
     const state = normalizeEnum(pr.state);
     const isDraft = Boolean(pr.isDraft);
+    const botRereviewDiagnostics = resolveEffectiveBotRereviewSignals({
+        pendingBots: rawBotRereviewPending,
+        coderabbitStatusCheckRollup,
+        requestTimesByBot: botRereview?.requestTimesByBot,
+        hasUnresolvedThread,
+        unacknowledgedBotFeedbackCount,
+        botFeedbackFetchError
+    });
+    const botRereviewPending = botRereviewDiagnostics.effectivePendingBots;
     const gateReasons = [];
     if (state !== 'OPEN') {
         gateReasons.push(`state=${state || 'UNKNOWN'}`);
@@ -627,10 +1248,17 @@ export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFe
             ? `required_checks_pending=${gateChecks.pending.length}`
             : `checks_pending=${gateChecks.pending.length}`);
     }
-    if (!MERGEABLE_STATES.has(mergeStateStatus)) {
+    if (gateChecksSource === 'required' && gateChecks.failed.length > 0) {
+        gateReasons.push(`required_checks_failed=${gateChecks.failed.length}`);
+    }
+    if (requiredChecksQueryFailed) {
+        gateReasons.push('required_checks_query_failed');
+    }
+    const mergeStateBlocksReady = doesMergeStateBlockReady(mergeStateStatus, readinessMode);
+    if (mergeStateBlocksReady) {
         gateReasons.push(`merge_state=${mergeStateStatus || 'UNKNOWN'}`);
     }
-    if (BLOCKED_REVIEW_DECISIONS.has(reviewDecision)) {
+    if (isReviewDecisionBlocked(reviewDecision, readinessMode)) {
         gateReasons.push(`review=${reviewDecision}`);
     }
     if (hasUnresolvedThread) {
@@ -646,7 +1274,7 @@ export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFe
         gateReasons.push('bot_rereview=unknown');
     }
     else if (botRereviewPending.length > 0) {
-        gateReasons.push(`bot_rereview_pending=${botRereviewPending.join(',')}`);
+        gateReasons.push(formatBotRereviewPendingGateReason(botRereviewPending, botRereviewDiagnostics));
     }
     return {
         number: Number(pr.number),
@@ -665,32 +1293,40 @@ export function buildStatusSnapshot(response, requiredChecks = null, inlineBotFe
         botRereviewFetchError,
         botRereviewPending,
         botRereviewInProgress,
+        botRereviewDiagnostics,
         coderabbitReviewMeta,
         checks,
         requiredChecks: requiredCheckSummary,
+        requiredChecksQueryFailed,
         gateChecksSource,
         gateReasons,
+        readinessMode,
         readyToMerge: gateReasons.length === 0,
-        headOid: pr.commits?.nodes?.[0]?.commit?.oid || null
+        headOid: pr.commits?.nodes?.[0]?.commit?.oid || null,
+        fanoutCacheHit: options.fanoutCacheHit === true,
+        githubRateLimit,
+        githubRateLimits
     };
 }
-export function resolveActionRequiredReasons(snapshot) {
+export function resolveActionRequiredReasons(snapshot, options = {}) {
     if (!snapshot || typeof snapshot !== 'object') {
         return ['snapshot=unknown'];
     }
+    const readinessMode = normalizeReadinessMode(options.readinessMode ?? snapshot.readinessMode);
     const reasons = [];
     const reviewDecision = normalizeEnum(snapshot.reviewDecision);
     const mergeStateStatus = normalizeEnum(snapshot.mergeStateStatus);
+    const mergeStateRequiresAuthorAction = doesMergeStateRequireAuthorAction(mergeStateStatus);
     if (Boolean(snapshot.isDraft)) {
         reasons.push('draft');
     }
     if (Boolean(snapshot.hasDoNotMergeLabel)) {
         reasons.push('label:do-not-merge');
     }
-    if (BLOCKED_REVIEW_DECISIONS.has(reviewDecision)) {
+    if (isReviewDecisionBlocked(reviewDecision, readinessMode)) {
         reasons.push(`review=${reviewDecision}`);
     }
-    if (ACTION_REQUIRED_MERGE_STATES.has(mergeStateStatus)) {
+    if (mergeStateRequiresAuthorAction) {
         reasons.push(`merge_state=${mergeStateStatus}`);
     }
     if (typeof snapshot.unresolvedThreadCount === 'number' && snapshot.unresolvedThreadCount > 0) {
@@ -701,6 +1337,9 @@ export function resolveActionRequiredReasons(snapshot) {
         reasons.push(`unacknowledged_bot_feedback=${snapshot.unacknowledgedBotFeedbackCount}`);
     }
     const requiredChecks = snapshot.requiredChecks && typeof snapshot.requiredChecks === 'object' ? snapshot.requiredChecks : null;
+    if (snapshot.requiredChecksQueryFailed === true) {
+        reasons.push('required_checks_query_failed');
+    }
     const requiredFailedCount = Array.isArray(requiredChecks?.failed) ? requiredChecks.failed.length : 0;
     if (requiredFailedCount > 0 && snapshot.readyToMerge === false) {
         reasons.push(`required_checks_failed=${requiredFailedCount}`);
@@ -708,12 +1347,93 @@ export function resolveActionRequiredReasons(snapshot) {
     else {
         const rollupFailedCount = Array.isArray(snapshot.checks?.failed) ? snapshot.checks.failed.length : 0;
         const rollupPendingCount = Array.isArray(snapshot.checks?.pending) ? snapshot.checks.pending.length : 0;
-        if (!requiredChecks && !MERGEABLE_STATES.has(mergeStateStatus) && rollupPendingCount === 0 && rollupFailedCount > 0) {
+        if (!requiredChecks
+            && snapshot.requiredChecksQueryFailed !== true
+            && readinessMode !== 'review'
+            && !mergeStateRequiresAuthorAction
+            && !MERGEABLE_STATES.has(mergeStateStatus)
+            && rollupPendingCount === 0
+            && rollupFailedCount > 0) {
             reasons.push(`checks_failed=${rollupFailedCount}`);
         }
     }
     return reasons;
 }
+function readPrecomputedRecoveryReasonList(snapshotOrReasons) {
+    if (Array.isArray(snapshotOrReasons)) {
+        return snapshotOrReasons.filter((reason) => typeof reason === 'string' && reason.trim().length > 0);
+    }
+    const precomputedReasons = snapshotOrReasons?.action_required_reasons;
+    return Array.isArray(precomputedReasons)
+        ? precomputedReasons.filter((reason) => typeof reason === 'string' && reason.trim().length > 0)
+        : [];
+}
+function readRecoveryGateReasons(snapshotOrReasons) {
+    if (!snapshotOrReasons || Array.isArray(snapshotOrReasons) || typeof snapshotOrReasons !== 'object') {
+        return [];
+    }
+    const rawGateReasons = Array.isArray(snapshotOrReasons.gateReasons)
+        ? snapshotOrReasons.gateReasons
+        : snapshotOrReasons.gate_reasons;
+    return Array.isArray(rawGateReasons)
+        ? rawGateReasons.filter((reason) => typeof reason === 'string' && reason.trim().length > 0)
+        : [];
+}
+export function resolveAutomaticBranchRecoveryReason(snapshotOrReasons, options = {}) {
+    const reasons = readPrecomputedRecoveryReasonList(snapshotOrReasons);
+    const resolvedReasons = reasons.length > 0
+        ? reasons
+        : resolveActionRequiredReasons(snapshotOrReasons, options);
+    const recoveryReason = reasons.find((reason) => AUTOMATIC_BRANCH_RECOVERY_REASONS.has(reason));
+    const selectedReason = typeof recoveryReason === 'string'
+        ? recoveryReason
+        : resolvedReasons.find((reason) => AUTOMATIC_BRANCH_RECOVERY_REASONS.has(reason));
+    if (typeof selectedReason !== 'string') {
+        return null;
+    }
+    if (options.requireExclusive === true) {
+        if (resolvedReasons.length === 0
+            || resolvedReasons.some((reason) => !AUTOMATIC_BRANCH_RECOVERY_REASONS.has(reason))) {
+            return null;
+        }
+        const gateReasons = readRecoveryGateReasons(snapshotOrReasons);
+        if (gateReasons.some((reason) => !AUTOMATIC_BRANCH_RECOVERY_REASONS.has(reason))) {
+            return null;
+        }
+    }
+    return selectedReason;
+}
+export function shouldAttemptAutomaticBranchRecovery(snapshotOrReasons, options = {}) {
+    const reasons = readPrecomputedRecoveryReasonList(snapshotOrReasons);
+    const resolvedReasons = reasons.length > 0
+        ? reasons
+        : resolveActionRequiredReasons(snapshotOrReasons, options);
+    const recoveryReason = resolveAutomaticBranchRecoveryReason(snapshotOrReasons, {
+        ...options,
+        requireExclusive: true
+    });
+    return (typeof recoveryReason === 'string'
+        && resolvedReasons.length === 1
+        && resolvedReasons[0] === recoveryReason);
+}
+export function isConflictLikeBranchRecoveryFailureMessage(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return false;
+    }
+    return (/\bconflict(?:ing|s)?\b/iu.test(value)
+        || /\bcannot be (?:cleanly )?(?:rebased|merged)\b/iu.test(value)
+        || /\bmerge conflict\b/iu.test(value));
+}
+export function shouldSucceedAfterTimeout(snapshot, options = {}) {
+    if (!snapshot || typeof snapshot !== 'object') {
+        return false;
+    }
+    if (options.pollingHealthy === false) {
+        return false;
+    }
+    const readinessMode = normalizeReadinessMode(options.readinessMode ?? snapshot.readinessMode);
+    return readinessMode === 'review' && snapshot.readyToMerge === true;
+}
 function formatStatusLine(snapshot, quietRemainingMs) {
     const requiredChecks = snapshot.requiredChecks;
     const failedNames = snapshot.checks.failed.map((item) => `${item.name}:${item.state}`).join(', ') || '-';
@@ -723,11 +1443,25 @@ function formatStatusLine(snapshot, quietRemainingMs) {
         : '-';
     const requiredPendingNames = requiredChecks ? requiredChecks.pending.join(', ') || '-' : '-';
     const reasons = snapshot.gateReasons.join(', ') || 'none';
+    const githubRateLimit = snapshot.githubRateLimit
+        ? `${snapshot.githubRateLimit.surface ?? 'unknown'}/${snapshot.githubRateLimit.limit_type ?? 'unknown'}`
+        : 'none';
+    const coderabbitRollup = snapshot.botRereviewDiagnostics?.coderabbit?.statusCheckRollup;
+    const coderabbitRollupState = coderabbitRollup?.state ?? 'unknown';
+    const coderabbitRollupNames = Array.isArray(coderabbitRollup?.contexts)
+        ? coderabbitRollup.contexts.map((context) => context.name).filter(Boolean).join('+') || '-'
+        : '-';
+    const clearedRereviewPending = Array.isArray(snapshot.botRereviewDiagnostics?.clearedPendingBots)
+        ? snapshot.botRereviewDiagnostics.clearedPendingBots.join(', ') || '-'
+        : '-';
     return [
         `PR #${snapshot.number}`,
         `state=${snapshot.state}`,
         `merge_state=${snapshot.mergeStateStatus}`,
         `review=${snapshot.reviewDecision}`,
+        `target=${normalizeReadinessMode(snapshot.readinessMode)}`,
+        `fanout_cache=${snapshot.fanoutCacheHit ? 'hit' : 'miss'}`,
+        `github_rate_limit=${githubRateLimit}`,
         `gate_checks=${snapshot.gateChecksSource}`,
         `checks_ok=${snapshot.checks.successCount}/${snapshot.checks.total}`,
         `checks_pending=${snapshot.checks.pending.length}`,
@@ -741,6 +1475,9 @@ function formatStatusLine(snapshot, quietRemainingMs) {
         `bot_rereview_fetch_error=${snapshot.botRereviewFetchError ? 'yes' : 'no'}`,
         `bot_rereview_pending=[${snapshot.botRereviewPending.join(', ') || '-'}]`,
         `bot_rereview_in_progress=[${snapshot.botRereviewInProgress.join(', ') || '-'}]`,
+        `bot_rereview_cleared=[${clearedRereviewPending}]`,
+        `coderabbit_rollup=${coderabbitRollupState}`,
+        `coderabbit_rollup_contexts=[${coderabbitRollupNames}]`,
         `coderabbit_actionable=${snapshot.coderabbitReviewMeta.actionableCount}`,
         `coderabbit_out_of_diff=${snapshot.coderabbitReviewMeta.outsideDiffCount}`,
         `coderabbit_nitpick=${snapshot.coderabbitReviewMeta.nitpickCount}`,
@@ -752,6 +1489,16 @@ function formatStatusLine(snapshot, quietRemainingMs) {
         `required_failed=[${requiredFailedNames}]`
     ].join(' | ');
 }
+function planPollingRateLimitSleepMs(rateLimit, { owner, repo, prNumber, intervalMs, deadline }) {
+    const nowMs = Date.now();
+    const remainingMs = Math.max(0, deadline - nowMs);
+    return planGitHubRateLimitBackoff(rateLimit, {
+        nowMs,
+        fallbackMs: intervalMs,
+        remainingMs,
+        jitterSeed: `${owner}/${repo}#${prNumber}:${rateLimit?.surface ?? 'unknown'}:${rateLimit?.limit_type ?? 'unknown'}`
+    });
+}
 async function fetchRequiredChecks(owner, repo, prNumber) {
     try {
         const result = await runGhJson([
@@ -768,13 +1515,24 @@ async function fetchRequiredChecks(owner, repo, prNumber) {
         const summary = summarizeRequiredChecks(entries);
         return {
             summary: summary.total > 0 ? summary : null,
-            fetchError: false
+            fetchError: false,
+            rateLimit: null
         };
     }
-    catch {
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (isNoRequiredChecksReportedErrorMessage(message)) {
+            return {
+                summary: null,
+                fetchError: false,
+                rateLimit: null
+            };
+        }
+        const rateLimit = resolveGitHubRateLimitStatus(error, { surface: 'rest' });
         return {
             summary: null,
-            fetchError: true
+            fetchError: true,
+            rateLimit
         };
     }
 }
@@ -904,18 +1662,27 @@ function maxCommentTimestampForKind(issueComments, kind, requestAtMs, headOid) {
         if (resolveBotKindFromLogin(comment.user?.login) !== kind) {
             continue;
         }
-        if (comment.__source !== 'pull') {
-            continue;
+        if (comment.__source === 'pull') {
+            const commentCommitId = typeof comment.commit_id === 'string' ? comment.commit_id : null;
+            if (headOid && commentCommitId && commentCommitId !== headOid) {
+                continue;
+            }
         }
-        const commentCommitId = typeof comment.commit_id === 'string' ? comment.commit_id : null;
-        if (headOid && commentCommitId && commentCommitId !== headOid) {
+        else if (!(kind === 'coderabbit' &&
+            typeof comment.body === 'string' &&
+            typeof headOid === 'string' &&
+            headOid.length > 0 &&
+            comment.body.toLowerCase().includes(headOid.toLowerCase()) &&
+            CODERABBIT_ISSUE_COMMENT_COMPLETION_PATTERNS.some((pattern) => pattern.test(comment.body)))) {
             continue;
         }
         const createdAtMs = parseTimestampMs(comment.created_at);
-        if (createdAtMs === null || createdAtMs <= requestAtMs) {
+        const updatedAtMs = parseTimestampMs(comment.updated_at);
+        const effectiveAtMs = comment.__source === 'issue' ? maxTimestamp([createdAtMs, updatedAtMs]) : createdAtMs;
+        if (effectiveAtMs === null || effectiveAtMs <= requestAtMs) {
             continue;
         }
-        timestamps.push(createdAtMs);
+        timestamps.push(effectiveAtMs);
     }
     return maxTimestamp(timestamps);
 }
@@ -1001,6 +1768,7 @@ async function fetchBotRereviewSignals(owner, repo, prNumber, headOid) {
         if (requestedKinds.length === 0) {
             return {
                 fetchError: false,
+                rateLimit: null,
                 pendingBots: [],
                 inProgressBots: [],
                 coderabbit
@@ -1008,7 +1776,9 @@ async function fetchBotRereviewSignals(owner, repo, prNumber, headOid) {
         }
         const pendingBots = [];
         const inProgressBots = [];
+        const requestTimesByBot = {};
         let hadSignalFetchError = false;
+        let signalRateLimit = null;
         for (const kind of requestedKinds) {
             const request = rereviewRequests[kind];
             if (!request) {
@@ -1019,8 +1789,9 @@ async function fetchBotRereviewSignals(owner, repo, prNumber, headOid) {
                 try {
                     requestCommentReactions = await fetchCommentReactionsBySource(owner, repo, request.source, request.commentId);
                 }
-                catch {
+                catch (error) {
                     hadSignalFetchError = true;
+                    signalRateLimit = signalRateLimit ?? resolveGitHubRateLimitStatus(error, { surface: 'rest' });
                     requestCommentReactions = [];
                 }
             }
@@ -1035,6 +1806,7 @@ async function fetchBotRereviewSignals(owner, repo, prNumber, headOid) {
             });
             const hasActiveInProgress = inProgressAtMs !== null && (completeAtMs === null || inProgressAtMs > completeAtMs);
             const label = BOT_KIND_LABELS[kind] ?? kind;
+            requestTimesByBot[label] = request.createdAtMs;
             if (hasActiveInProgress) {
                 inProgressBots.push(label);
             }
@@ -1044,14 +1816,17 @@ async function fetchBotRereviewSignals(owner, repo, prNumber, headOid) {
         }
         return {
             fetchError: hadSignalFetchError,
+            rateLimit: signalRateLimit,
             pendingBots,
             inProgressBots,
+            requestTimesByBot,
             coderabbit
         };
     }
-    catch {
+    catch (error) {
         return {
             fetchError: true,
+            rateLimit: resolveGitHubRateLimitStatus(error, { surface: 'rest' }),
             pendingBots: [],
             inProgressBots: [],
             coderabbit: {
@@ -1064,7 +1839,7 @@ async function fetchBotRereviewSignals(owner, repo, prNumber, headOid) {
 }
 async function fetchInlineBotFeedback(owner, repo, prNumber, headOid) {
     if (!headOid) {
-        return { fetchError: false, unacknowledgedCount: 0 };
+        return { fetchError: false, rateLimit: null, unacknowledgedCount: 0 };
     }
     try {
         const pagedPayload = await runGhJsonSlurped([
@@ -1111,13 +1886,17 @@ async function fetchInlineBotFeedback(owner, repo, prNumber, headOid) {
                 unacknowledgedCount += 1;
             }
         }
-        return { fetchError: false, unacknowledgedCount };
+        return { fetchError: false, rateLimit: null, unacknowledgedCount };
     }
-    catch {
-        return { fetchError: true, unacknowledgedCount: 0 };
+    catch (error) {
+        return {
+            fetchError: true,
+            rateLimit: resolveGitHubRateLimitStatus(error, { surface: 'rest' }),
+            unacknowledgedCount: 0
+        };
     }
 }
-async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache = null) {
+async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache = null, options = {}) {
     const response = await runGhJson([
         'api',
         'graphql',
@@ -1131,26 +1910,65 @@ async function fetchSnapshot(owner, repo, prNumber, previousRequiredChecksCache
         `number=${prNumber}`
     ]);
     const currentHeadOid = response?.data?.repository?.pullRequest?.commits?.nodes?.[0]?.commit?.oid || null;
+    const currentUpdatedAt = response?.data?.repository?.pullRequest?.updatedAt || null;
+    const cachedFanout = resolveReusableFanoutCache(previousRequiredChecksCache, currentHeadOid, currentUpdatedAt);
     const previousRequiredChecks = resolveCachedRequiredChecksSummary(previousRequiredChecksCache, currentHeadOid);
-    const [requiredChecksResult, inlineBotFeedback, botRereviewSignals] = await Promise.all([
-        fetchRequiredChecks(owner, repo, prNumber),
-        fetchInlineBotFeedback(owner, repo, prNumber, currentHeadOid),
-        fetchBotRereviewSignals(owner, repo, prNumber, currentHeadOid)
-    ]);
+    let requiredChecksResult;
+    let inlineBotFeedback;
+    let botRereviewSignals;
+    let fanoutCacheHit = false;
+    if (cachedFanout) {
+        requiredChecksResult = await fetchRequiredChecks(owner, repo, prNumber);
+        inlineBotFeedback = cachedFanout.inlineBotFeedback;
+        botRereviewSignals = cachedFanout.botRereviewSignals;
+        fanoutCacheHit = true;
+    }
+    else {
+        [requiredChecksResult, inlineBotFeedback, botRereviewSignals] = await Promise.all([
+            fetchRequiredChecks(owner, repo, prNumber),
+            fetchInlineBotFeedback(owner, repo, prNumber, currentHeadOid),
+            fetchBotRereviewSignals(owner, repo, prNumber, currentHeadOid)
+        ]);
+    }
     const requiredChecks = resolveRequiredChecksSummary(requiredChecksResult.summary, previousRequiredChecks, requiredChecksResult.fetchError);
+    const githubRateLimits = [
+        requiredChecksResult.rateLimit,
+        inlineBotFeedback?.rateLimit,
+        botRereviewSignals?.rateLimit
+    ].filter(Boolean);
     return {
         snapshot: buildStatusSnapshot(response, requiredChecks, {
             ...inlineBotFeedback,
             rereview: botRereviewSignals
+        }, {
+            ...options,
+            fanoutCacheHit,
+            githubRateLimits,
+            requiredChecksQueryFailed: requiredChecksResult.fetchError
         }),
-        requiredChecksForNextPoll: requiredChecks
-            ? {
-                headOid: currentHeadOid,
-                summary: requiredChecks
-            }
-            : null
+        requiredChecksForNextPoll: buildReusableFanoutCache({
+            headOid: currentHeadOid,
+            updatedAt: currentUpdatedAt,
+            requiredChecks,
+            requiredChecksResult,
+            inlineBotFeedback,
+            botRereviewSignals
+        })
     };
 }
+export async function fetchPrStatusSnapshot(input) {
+    const owner = typeof input?.owner === 'string' ? input.owner.trim() : '';
+    const repo = typeof input?.repo === 'string' ? input.repo.trim() : '';
+    const prNumber = Number(input?.prNumber);
+    if (!owner || !repo || !Number.isInteger(prNumber) || prNumber <= 0) {
+        throw new Error('fetchPrStatusSnapshot requires owner, repo, and a positive integer prNumber.');
+    }
+    const readinessMode = normalizeReadinessMode(input?.readinessMode);
+    const { snapshot } = await fetchSnapshot(owner, repo, prNumber, null, {
+        readinessMode
+    });
+    return snapshot;
+}
 export function buildPrMergeArgs({ owner, repo, 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}`, '--repo', `${owner}/${repo}`];
@@ -1166,8 +1984,26 @@ async function attemptMerge({ owner, repo, prNumber, mergeMethod, deleteBranch,
     const args = buildPrMergeArgs({ owner, repo, prNumber, mergeMethod, deleteBranch, headOid });
     return await runGh(args, { allowFailure: true });
 }
+async function attemptUpdateBranch({ owner, repo, prNumber }) {
+    const args = buildPrUpdateBranchArgs({ owner, repo, prNumber });
+    return await runGh(args, { allowFailure: true });
+}
+export function buildAutomaticBranchRecoveryKey(snapshot, recoveryReason) {
+    return [
+        recoveryReason,
+        snapshot?.headOid || 'no-head'
+    ].join('|');
+}
+function describeAutomaticBranchRecovery(recoveryReason) {
+    if (recoveryReason === 'merge_state=DIRTY') {
+        return 'conflict recovery';
+    }
+    return 'branch refresh';
+}
 async function runPrWatchMergeOrThrow(argv, options) {
     const { args, positionals } = parseArgs(argv);
+    const readinessMode = normalizeReadinessMode(options.readinessMode);
+    const isReviewMode = readinessMode === 'review';
     if (hasFlag(args, 'h') || hasFlag(args, 'help')) {
         printPrWatchMergeHelp(options);
         return;
@@ -1195,6 +2031,21 @@ async function runPrWatchMergeOrThrow(argv, options) {
         const label = unknownFlags[0] ? `--${unknownFlags[0]}` : positionals[0];
         throw new Error(`Unknown option: ${label}`);
     }
+    if (isReviewMode) {
+        const unsupportedFlags = [];
+        if (Object.prototype.hasOwnProperty.call(args, 'merge-method')) {
+            unsupportedFlags.push('--merge-method');
+        }
+        if (hasFlag(args, 'auto-merge') || hasFlag(args, 'no-auto-merge')) {
+            unsupportedFlags.push('--auto-merge/--no-auto-merge');
+        }
+        if (hasFlag(args, 'delete-branch') || hasFlag(args, 'no-delete-branch')) {
+            unsupportedFlags.push('--delete-branch/--no-delete-branch');
+        }
+        if (unsupportedFlags.length > 0) {
+            throw new Error(`ready-review does not support merge flags: ${unsupportedFlags.join(', ')}`);
+        }
+    }
     const intervalSeconds = parseNumber('interval-seconds', typeof args['interval-seconds'] === 'string'
         ? args['interval-seconds']
         : process.env.PR_MONITOR_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS);
@@ -1204,25 +2055,33 @@ async function runPrWatchMergeOrThrow(argv, options) {
     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 mergeMethod = isReviewMode
+        ? DEFAULT_MERGE_METHOD
+        : parseMergeMethod(typeof args['merge-method'] === 'string'
+            ? args['merge-method']
+            : process.env.PR_MONITOR_MERGE_METHOD || DEFAULT_MERGE_METHOD);
     const defaultAutoMergeFallback = typeof options.defaultAutoMerge === 'boolean' ? options.defaultAutoMerge : false;
     const defaultAutoMerge = envFlagEnabled(process.env.PR_MONITOR_AUTO_MERGE, defaultAutoMergeFallback);
     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;
+    let autoMerge = false;
+    if (!isReviewMode) {
+        autoMerge = defaultAutoMerge;
+        if (hasFlag(args, 'auto-merge')) {
+            autoMerge = true;
+        }
+        if (hasFlag(args, 'no-auto-merge')) {
+            autoMerge = false;
+        }
     }
-    if (hasFlag(args, 'no-delete-branch')) {
-        deleteBranch = false;
+    let deleteBranch = false;
+    if (!isReviewMode) {
+        deleteBranch = defaultDeleteBranch;
+        if (hasFlag(args, 'delete-branch')) {
+            deleteBranch = true;
+        }
+        if (hasFlag(args, 'no-delete-branch')) {
+            deleteBranch = false;
+        }
     }
     let exitOnActionRequired = Boolean(options.defaultExitOnActionRequired);
     if (hasFlag(args, 'exit-on-action-required')) {
@@ -1239,24 +2098,54 @@ async function runPrWatchMergeOrThrow(argv, options) {
     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'}, exit_on_action_required=${exitOnActionRequired ? 'on' : 'off'}, dry_run=${dryRun ? 'on' : 'off'}).`);
+    const automaticBranchRecoveryEnabled = isReviewMode
+        || autoMerge
+        || Boolean(options.enableAutomaticBranchRecovery);
+    log(isReviewMode
+        ? `Monitoring ${owner}/${repo}#${prNumber} every ${intervalSeconds}s (quiet window ${quietMinutes}m, timeout ${timeoutMinutes}m, target=review_handoff, exit_on_action_required=${exitOnActionRequired ? 'on' : 'off'}, dry_run=${dryRun ? 'on' : 'off'}).`
+        : `Monitoring ${owner}/${repo}#${prNumber} every ${intervalSeconds}s (quiet window ${quietMinutes}m, timeout ${timeoutMinutes}m, auto_merge=${autoMerge ? 'on' : 'off'}, exit_on_action_required=${exitOnActionRequired ? 'on' : 'off'}, dry_run=${dryRun ? 'on' : 'off'}).`);
     let quietWindowStartedAt = null;
     let quietWindowAnchorUpdatedAt = null;
     let quietWindowAnchorHeadOid = null;
     let lastMergeAttemptHeadOid = null;
-    let requiredChecksForNextPollCache = null;
+    let pendingAutomaticBranchRecoveryKey = null;
+    let attemptedAutomaticBranchRecoveryKey = null;
+    let fanoutForNextPollCache = null;
+    let latestSnapshot = null;
+    let pollingHealthySinceLatestSnapshot = false;
     while (Date.now() <= deadline) {
         let snapshot;
         try {
-            const fetched = await fetchSnapshot(owner, repo, prNumber, requiredChecksForNextPollCache);
+            const fetched = await fetchSnapshot(owner, repo, prNumber, fanoutForNextPollCache, {
+                readinessMode
+            });
             snapshot = fetched.snapshot;
-            requiredChecksForNextPollCache = fetched.requiredChecksForNextPoll;
+            fanoutForNextPollCache = fetched.requiredChecksForNextPoll;
         }
         catch (error) {
+            pollingHealthySinceLatestSnapshot = false;
+            const rateLimit = resolveGitHubRateLimitStatus(error);
+            if (rateLimit) {
+                const sleepMs = planPollingRateLimitSleepMs(rateLimit, {
+                    owner,
+                    repo,
+                    prNumber,
+                    intervalMs,
+                    deadline
+                });
+                if (sleepMs <= 0) {
+                    break;
+                }
+                log(`Polling GitHub API rate limit: ${formatGitHubRateLimitStatus(rateLimit)} (retrying in ${formatDuration(sleepMs)}).`);
+                await sleep(sleepMs);
+                continue;
+            }
             log(`Polling error: ${error instanceof Error ? error.message : String(error)} (retrying).`);
             await sleep(intervalMs);
             continue;
         }
+        latestSnapshot = snapshot;
+        pollingHealthySinceLatestSnapshot = true;
         if (snapshot.state === 'MERGED' || snapshot.mergedAt) {
             log(`PR #${prNumber} is merged.`);
             if (snapshot.url) {
@@ -1290,20 +2179,132 @@ async function runPrWatchMergeOrThrow(argv, options) {
         const quietElapsedMs = quietWindowStartedAt ? Date.now() - quietWindowStartedAt : 0;
         const quietRemainingMs = quietWindowStartedAt ? Math.max(quietMs - quietElapsedMs, 0) : quietMs;
         log(formatStatusLine(snapshot, quietRemainingMs));
+        const actionRequiredReasons = resolveActionRequiredReasons(snapshot, { readinessMode });
+        const automaticBranchRecoveryReason = automaticBranchRecoveryEnabled
+            ? resolveAutomaticBranchRecoveryReason(snapshot, {
+                readinessMode,
+                requireExclusive: true
+            })
+            : null;
+        const shouldAttemptRecovery = automaticBranchRecoveryEnabled
+            && shouldAttemptAutomaticBranchRecovery(snapshot, { readinessMode });
+        const automaticBranchRecoveryKey = automaticBranchRecoveryReason
+            ? buildAutomaticBranchRecoveryKey(snapshot, automaticBranchRecoveryReason)
+            : null;
+        if (pendingAutomaticBranchRecoveryKey
+            && pendingAutomaticBranchRecoveryKey !== automaticBranchRecoveryKey) {
+            pendingAutomaticBranchRecoveryKey = null;
+        }
+        if (attemptedAutomaticBranchRecoveryKey
+            && attemptedAutomaticBranchRecoveryKey !== automaticBranchRecoveryKey) {
+            attemptedAutomaticBranchRecoveryKey = null;
+        }
+        if (exitOnActionRequired
+            && actionRequiredReasons.length > 0
+            && !shouldAttemptRecovery) {
+            const details = actionRequiredReasons.join(', ');
+            throw new PrWatchMergeExitError(`${isReviewMode ? 'Action required before review handoff' : 'Action required before merge'}: ${details}${snapshot.url ? ` (${snapshot.url})` : ''}`, 2);
+        }
+        if (snapshot.githubRateLimit) {
+            pollingHealthySinceLatestSnapshot = false;
+            const sleepMs = planPollingRateLimitSleepMs(snapshot.githubRateLimit, {
+                owner,
+                repo,
+                prNumber,
+                intervalMs,
+                deadline
+            });
+            if (sleepMs <= 0) {
+                break;
+            }
+            log(`GitHub API fan-out is rate limited: ${formatGitHubRateLimitStatus(snapshot.githubRateLimit)} (retrying in ${formatDuration(sleepMs)}).`);
+            await sleep(sleepMs);
+            continue;
+        }
+        if (shouldAttemptRecovery
+            && automaticBranchRecoveryReason
+            && automaticBranchRecoveryKey
+            && pendingAutomaticBranchRecoveryKey !== automaticBranchRecoveryKey
+            && attemptedAutomaticBranchRecoveryKey !== automaticBranchRecoveryKey) {
+            if (dryRun) {
+                log(`Dry run: would attempt automatic ${describeAutomaticBranchRecovery(automaticBranchRecoveryReason)} for ${automaticBranchRecoveryReason}.`);
+            }
+            else {
+                log(`Attempting automatic ${describeAutomaticBranchRecovery(automaticBranchRecoveryReason)} via gh pr update-branch (${automaticBranchRecoveryReason}).`);
+                const updateBranchResult = await attemptUpdateBranch({
+                    owner,
+                    repo,
+                    prNumber
+                });
+                if (updateBranchResult.exitCode === 0) {
+                    attemptedAutomaticBranchRecoveryKey = automaticBranchRecoveryKey;
+                    pendingAutomaticBranchRecoveryKey = automaticBranchRecoveryKey;
+                    quietWindowStartedAt = null;
+                    quietWindowAnchorUpdatedAt = null;
+                    quietWindowAnchorHeadOid = null;
+                    lastMergeAttemptHeadOid = null;
+                    log(`Automatic ${describeAutomaticBranchRecovery(automaticBranchRecoveryReason)} requested for PR #${prNumber}; waiting for GitHub readiness to refresh.`);
+                    const remainingTimeMs = deadline - Date.now();
+                    if (remainingTimeMs <= 0) {
+                        break;
+                    }
+                    await sleep(Math.min(intervalMs, remainingTimeMs));
+                    continue;
+                }
+                const updateBranchRateLimit = resolveGitHubRateLimitStatus(updateBranchResult, {
+                    surface: 'rest'
+                });
+                if (updateBranchRateLimit) {
+                    const sleepMs = planPollingRateLimitSleepMs(updateBranchRateLimit, {
+                        owner,
+                        repo,
+                        prNumber,
+                        intervalMs,
+                        deadline
+                    });
+                    if (sleepMs <= 0) {
+                        break;
+                    }
+                    log(`Automatic ${describeAutomaticBranchRecovery(automaticBranchRecoveryReason)} is rate limited: ${formatGitHubRateLimitStatus(updateBranchRateLimit)} (retrying in ${formatDuration(sleepMs)}).`);
+                    await sleep(sleepMs);
+                    continue;
+                }
+                attemptedAutomaticBranchRecoveryKey = automaticBranchRecoveryKey;
+                const details = updateBranchResult.stderr
+                    || updateBranchResult.stdout
+                    || `exit code ${updateBranchResult.exitCode}`;
+                log(`Automatic ${describeAutomaticBranchRecovery(automaticBranchRecoveryReason)} failed: ${details}`);
+                if (isConflictLikeBranchRecoveryFailureMessage(details)) {
+                    log('GitHub reported merge conflicts while attempting automatic branch recovery.');
+                }
+            }
+        }
         if (exitOnActionRequired) {
-            const actionRequiredReasons = resolveActionRequiredReasons(snapshot);
             if (actionRequiredReasons.length > 0) {
+                if (shouldAttemptRecovery
+                    && automaticBranchRecoveryKey
+                    && pendingAutomaticBranchRecoveryKey === automaticBranchRecoveryKey) {
+                    log(`Automatic ${describeAutomaticBranchRecovery(automaticBranchRecoveryReason)} is still pending; suppressing action-required exit for now.`);
+                    const remainingTimeMs = deadline - Date.now();
+                    if (remainingTimeMs <= 0) {
+                        break;
+                    }
+                    await sleep(Math.min(intervalMs, remainingTimeMs));
+                    continue;
+                }
                 const details = actionRequiredReasons.join(', ');
-                throw new PrWatchMergeExitError(`Action required before merge: ${details}${snapshot.url ? ` (${snapshot.url})` : ''}`, 2);
+                throw new PrWatchMergeExitError(`${isReviewMode ? 'Action required before review handoff' : 'Action required before merge'}: ${details}${snapshot.url ? ` (${snapshot.url})` : ''}`, 2);
             }
         }
         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.');
+                log(isReviewMode
+                    ? 'Review handoff conditions satisfied and quiet window elapsed.'
+                    : 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}`);
+                    log(`${isReviewMode ? 'Ready for review' : 'Ready to merge'}: ${snapshot.url}`);
                 }
                 return;
             }
@@ -1335,6 +2336,13 @@ async function runPrWatchMergeOrThrow(argv, options) {
         }
         await sleep(Math.min(intervalMs, remainingTimeMs));
     }
+    if (shouldSucceedAfterTimeout(latestSnapshot, { readinessMode, pollingHealthy: pollingHealthySinceLatestSnapshot })) {
+        log('Bounded wait expired cleanly with no remaining automated-feedback blockers.');
+        if (latestSnapshot?.url) {
+            log(`Ready for review: ${latestSnapshot.url}`);
+        }
+        return;
+    }
     throw new PrWatchMergeExitError(`Timed out after ${timeoutMinutes} minute(s) while monitoring PR #${prNumber}.`, 3);
 }
 export async function runPrWatchMerge(argv, options = {}) {