@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/dist/orchestrator/src/cli/control/providerMergeCloseout.js

@@ -0,0 +1,1868 @@
+import { execFile } from 'node:child_process';
+import process from 'node:process';
+import { promisify } from 'node:util';
+import { classifyProviderLinearWorkflowState } from './providerLinearWorkflowStates.js';
+import { getProviderLinearIssueContext, transitionProviderLinearIssueState } from './providerLinearWorkflowFacade.js';
+import { isoTimestamp } from '../utils/time.js';
+import { buildPrMergeArgs, buildPrUpdateBranchArgs, fetchPrStatusSnapshot, formatGitHubRateLimitStatus, isConflictLikeBranchRecoveryFailureMessage, parseGitHubRepoFromRemoteUrl, resolveAutomaticBranchRecoveryReason, resolveActionRequiredReasons, resolveGitHubRateLimitStatus, shouldAttemptAutomaticBranchRecovery } from '../../../../scripts/lib/pr-watch-merge.js';
+const execFileAsync = promisify(execFile);
+const PROVIDER_MERGE_CLOSEOUT_COMMAND_TIMEOUT_MS = 15_000;
+const PROVIDER_MERGE_CLOSEOUT_MERGE_METHOD = 'squash';
+export async function runProviderDeterministicMergeCloseout(input, deps = {}) {
+    const env = input.env ?? process.env;
+    const now = deps.now ?? isoTimestamp;
+    const readIssueContext = deps.readIssueContext ?? getProviderLinearIssueContext;
+    const transitionIssueState = deps.transitionIssueState ?? transitionProviderLinearIssueState;
+    const runCommand = deps.runCommand ?? runProviderMergeCloseoutCommand;
+    const resolveSnapshot = deps.fetchSnapshot ?? fetchPrStatusSnapshot;
+    const resolveSnapshotActionRequiredReasons = deps.resolveSnapshotActionRequiredReasons ??
+        ((snapshot, options) => resolveActionRequiredReasons(snapshot, options));
+    const mode = input.mode ?? 'full';
+    const recordedAt = now();
+    const base = {
+        recorded_at: recordedAt,
+        issue_id: input.issueId,
+        issue_identifier: normalizeOptionalString(input.issueIdentifier),
+        issue_state: normalizeOptionalString(input.issueState),
+        issue_state_type: normalizeOptionalString(input.issueStateType),
+        issue_updated_at: normalizeOptionalString(input.issueUpdatedAt),
+        attached_pr_urls: [],
+        ignored_historical_pr_urls: [],
+        ignored_closed_unmerged_pr_urls: [],
+        conflicting_attached_pr_urls: [],
+        pr: null,
+        snapshot: null,
+        branch_recovery: null,
+        merge_attempt: null,
+        shared_root: null,
+        linear_transition: null,
+        github_rate_limit: null
+    };
+    const repoOriginResult = await runCommand({
+        command: 'git',
+        args: ['-C', input.repoRoot, 'remote', 'get-url', 'origin'],
+        cwd: input.repoRoot
+    });
+    if (!repoOriginResult.ok) {
+        return {
+            ...base,
+            status: 'merge_failed',
+            reason: 'shared_root_origin_unavailable',
+            summary: 'Shared repo origin remote could not be resolved.',
+            attached_pr_urls: [],
+            pr: null,
+            snapshot: null,
+            merge_attempt: null,
+            shared_root: null,
+            linear_transition: null
+        };
+    }
+    const parsedRepo = parseGitHubRepoFromRemoteUrl(repoOriginResult.stdout);
+    const repoKey = parsedRepo
+        ? `${parsedRepo.owner.toLowerCase()}/${parsedRepo.repo.toLowerCase()}`
+        : null;
+    if (!repoKey) {
+        return {
+            ...base,
+            status: 'merge_failed',
+            reason: 'shared_root_repo_unrecognized',
+            summary: 'Shared repo origin is not a GitHub repository URL.',
+            attached_pr_urls: [],
+            pr: null,
+            snapshot: null,
+            merge_attempt: null,
+            shared_root: null,
+            linear_transition: null
+        };
+    }
+    const issueContext = await readIssueContext({
+        issueId: input.issueId,
+        env,
+        sourceSetup: input.sourceSetup,
+        fallbackToCacheOnFailure: mode === 'probe-merged-recovery'
+    });
+    if (!issueContext.ok) {
+        return {
+            ...base,
+            status: 'merge_failed',
+            reason: 'linear_issue_context_failed',
+            summary: `Linear issue context could not be loaded (${issueContext.error.code}).`,
+            attached_pr_urls: [],
+            pr: null,
+            snapshot: null,
+            merge_attempt: null,
+            shared_root: null,
+            linear_transition: null
+        };
+    }
+    const attachedPrCandidates = collectAttachedGitHubPrCandidates(issueContext.issue.attachments);
+    const attachedPrUrls = attachedPrCandidates.map((candidate) => candidate.pr.url);
+    const usedCachedIssueContext = issueContext.cache_fallback_used === true;
+    if (mode === 'probe-merged-recovery' &&
+        usedCachedIssueContext &&
+        !isProbeRecoveryCacheContextFreshEnough({
+            issueState: input.issueState,
+            issueStateType: input.issueStateType,
+            issueUpdatedAt: input.issueUpdatedAt,
+            issueContext: issueContext.issue
+        })) {
+        return {
+            ...base,
+            attached_pr_urls: [...attachedPrUrls],
+            status: 'watching',
+            reason: 'probe_issue_context_cache_stale',
+            summary: 'Cached Linear issue context does not match the tracked issue metadata, so merged recovery will not transition the issue to Done until a fresh issue-context read succeeds.',
+            pr: null,
+            snapshot: null,
+            merge_attempt: null,
+            shared_root: null,
+            linear_transition: null
+        };
+    }
+    const sameRepoPrs = attachedPrCandidates.filter((candidate) => `${candidate.pr.owner.toLowerCase()}/${candidate.pr.repo.toLowerCase()}` === repoKey);
+    const currentIssueState = issueContext.issue.state?.name ?? base.issue_state;
+    const currentIssueStateType = issueContext.issue.state?.type ?? base.issue_state_type;
+    const currentIssueUpdatedAt = issueContext.issue.updated_at ?? base.issue_updated_at;
+    const currentIssueAlreadyCompleted = currentIssueStateType === 'completed';
+    const allowCompletedIssueRecovery = mode === 'probe-merged-recovery' && currentIssueAlreadyCompleted;
+    const baseWithContext = {
+        ...base,
+        issue_state: currentIssueState,
+        issue_state_type: currentIssueStateType,
+        issue_updated_at: currentIssueUpdatedAt,
+        attached_pr_urls: [...attachedPrUrls]
+    };
+    if (normalizeProviderMergeCloseoutIssueState(currentIssueState) !== 'merging' &&
+        !allowCompletedIssueRecovery) {
+        return {
+            ...baseWithContext,
+            status: 'action_required',
+            reason: 'issue_no_longer_merging',
+            summary: currentIssueState && currentIssueState.trim().length > 0
+                ? `Live Linear issue state is ${currentIssueState}, so deterministic merge closeout is not armed.`
+                : 'Live Linear issue state is no longer Merging, so deterministic merge closeout is not armed.'
+        };
+    }
+    if (sameRepoPrs.length === 0) {
+        return {
+            ...baseWithContext,
+            status: 'action_required',
+            reason: attachedPrUrls.length === 0 ? 'no_attached_pr' : 'attached_pr_repo_mismatch',
+            summary: attachedPrUrls.length === 0
+                ? 'No attached GitHub pull request is present for this Merging issue.'
+                : 'Attached GitHub pull requests do not match the shared repository root.'
+        };
+    }
+    let ignoredHistoricalPrUrls = [];
+    let ignoredClosedUnmergedPrUrls = [];
+    let conflictingAttachedPrUrls = [];
+    let selectionNote = null;
+    let pr = sameRepoPrs[0].pr;
+    let snapshot = null;
+    if (sameRepoPrs.length > 1) {
+        let resolution;
+        try {
+            resolution = await resolveAttachedSameRepoPullRequestCandidate({
+                candidates: sameRepoPrs,
+                mode: 'merge_closeout',
+                resolveSnapshot,
+                resolveSnapshotActionRequiredReasons
+            });
+        }
+        catch (error) {
+            const githubRateLimit = resolveProviderGitHubRateLimitRecord(error);
+            if (githubRateLimit) {
+                return {
+                    ...baseWithContext,
+                    status: 'watching',
+                    reason: 'github_rate_limited',
+                    summary: `GitHub API budget blocked attached pull-request disambiguation during merge closeout: ${formatProviderGitHubRateLimitSummary(githubRateLimit)}.`,
+                    github_rate_limit: githubRateLimit
+                };
+            }
+            return {
+                ...baseWithContext,
+                status: 'merge_failed',
+                reason: 'snapshot_read_failed',
+                summary: `GitHub merge-readiness snapshot could not be loaded while disambiguating attached pull requests: ${error?.message ?? String(error)}.`
+            };
+        }
+        ignoredHistoricalPrUrls = resolution.ignored_historical_pr_urls;
+        ignoredClosedUnmergedPrUrls = resolution.ignored_closed_unmerged_pr_urls;
+        conflictingAttachedPrUrls = resolution.conflicting_attached_pr_urls;
+        selectionNote = resolution.selection_note;
+        if (!resolution.selected_pr) {
+            return {
+                ...baseWithContext,
+                ignored_historical_pr_urls: [...ignoredHistoricalPrUrls],
+                ignored_closed_unmerged_pr_urls: [...ignoredClosedUnmergedPrUrls],
+                conflicting_attached_pr_urls: [...conflictingAttachedPrUrls],
+                status: 'action_required',
+                reason: 'multiple_attached_prs',
+                summary: buildMultipleAttachedPrsSummary({
+                    repoKey,
+                    ignoredHistoricalPrUrls,
+                    ignoredClosedUnmergedPrUrls,
+                    conflictingAttachedPrUrls
+                })
+            };
+        }
+        pr = resolution.selected_pr;
+        snapshot = resolution.selected_snapshot;
+    }
+    const baseWithResolution = {
+        ...baseWithContext,
+        ignored_historical_pr_urls: [...ignoredHistoricalPrUrls],
+        ignored_closed_unmerged_pr_urls: [...ignoredClosedUnmergedPrUrls],
+        conflicting_attached_pr_urls: [...conflictingAttachedPrUrls]
+    };
+    const summarizeSelection = (summary) => selectionNote ? `${summary} ${selectionNote}` : summary;
+    if (!snapshot) {
+        try {
+            snapshot = await loadProviderSnapshotRecord({
+                owner: pr.owner,
+                repo: pr.repo,
+                prNumber: pr.number,
+                readinessMode: 'merge',
+                resolveSnapshot,
+                resolveSnapshotActionRequiredReasons
+            });
+        }
+        catch (error) {
+            const githubRateLimit = resolveProviderGitHubRateLimitRecord(error);
+            if (githubRateLimit) {
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    status: 'watching',
+                    reason: 'github_rate_limited',
+                    summary: summarizeSelection(`GitHub API budget blocked merge-readiness snapshot loading: ${formatProviderGitHubRateLimitSummary(githubRateLimit)}.`),
+                    snapshot: null,
+                    github_rate_limit: githubRateLimit
+                };
+            }
+            return {
+                ...baseWithResolution,
+                pr,
+                status: 'merge_failed',
+                reason: 'snapshot_read_failed',
+                summary: summarizeSelection(`GitHub merge-readiness snapshot could not be loaded: ${error?.message ?? String(error)}`),
+                snapshot: null
+            };
+        }
+    }
+    if (!snapshot) {
+        return {
+            ...baseWithResolution,
+            pr,
+            status: 'merge_failed',
+            reason: 'snapshot_read_failed',
+            summary: summarizeSelection('GitHub merge-readiness snapshot could not be loaded.'),
+            snapshot: null
+        };
+    }
+    let alreadyMerged = snapshot.merged_at !== null || snapshot.state === 'MERGED';
+    if (mode === 'probe-merged-recovery' && !alreadyMerged) {
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot,
+            status: 'watching',
+            reason: 'probe_pr_not_merged',
+            summary: summarizeSelection(`Attached PR #${pr.number} is not merged yet, so merged recovery cannot retire the rehydrated Merging claim.`)
+        };
+    }
+    let branchRecovery = null;
+    if (!alreadyMerged && !snapshot.ready_to_merge) {
+        const preRecoveryOutcome = classifyPreBranchRecoverySnapshot(snapshot, pr.number, 'merge_closeout');
+        if (preRecoveryOutcome) {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot,
+                ...preRecoveryOutcome,
+                summary: summarizeSelection(preRecoveryOutcome.summary)
+            };
+        }
+        branchRecovery = await attemptProviderBranchRecovery({
+            pr,
+            snapshot,
+            previousBranchRecovery: input.previousBranchRecovery ?? null,
+            repoRoot: input.repoRoot,
+            now,
+            runCommand
+        });
+        if (branchRecovery?.ok) {
+            try {
+                snapshot = await loadProviderSnapshotRecord({
+                    owner: pr.owner,
+                    repo: pr.repo,
+                    prNumber: pr.number,
+                    readinessMode: 'merge',
+                    resolveSnapshot,
+                    resolveSnapshotActionRequiredReasons
+                });
+            }
+            catch (error) {
+                const githubRateLimit = resolveProviderGitHubRateLimitRecord(error);
+                if (githubRateLimit) {
+                    return {
+                        ...baseWithResolution,
+                        pr,
+                        snapshot,
+                        branch_recovery: branchRecovery,
+                        status: 'watching',
+                        reason: 'github_rate_limited',
+                        summary: summarizeSelection(`GitHub API budget blocked post-branch-recovery readiness verification: ${formatProviderGitHubRateLimitSummary(githubRateLimit)}.`),
+                        github_rate_limit: githubRateLimit
+                    };
+                }
+                // Preserve the pre-recovery snapshot when verification cannot be reread.
+            }
+            alreadyMerged = snapshot.merged_at !== null || snapshot.state === 'MERGED';
+            if (!alreadyMerged && !snapshot.ready_to_merge) {
+                const prePendingRecoveryOutcome = classifyPreBranchRecoverySnapshot(snapshot, pr.number, 'merge_closeout');
+                if (prePendingRecoveryOutcome) {
+                    return {
+                        ...baseWithResolution,
+                        pr,
+                        snapshot,
+                        branch_recovery: branchRecovery,
+                        ...prePendingRecoveryOutcome,
+                        summary: summarizeSelection(prePendingRecoveryOutcome.summary)
+                    };
+                }
+                const pendingRecovery = classifyPendingBranchRecovery({
+                    snapshot,
+                    recoveryAttempt: branchRecovery,
+                    prNumber: pr.number,
+                    mode: 'merge_closeout'
+                });
+                if (pendingRecovery) {
+                    return {
+                        ...baseWithResolution,
+                        pr,
+                        snapshot,
+                        branch_recovery: branchRecovery,
+                        ...pendingRecovery,
+                        summary: summarizeSelection(pendingRecovery.summary)
+                    };
+                }
+                const nonMergedOutcome = classifyNonMergedSnapshot(snapshot, pr.number);
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    snapshot,
+                    branch_recovery: branchRecovery,
+                    ...nonMergedOutcome,
+                    summary: summarizeSelection(nonMergedOutcome.summary)
+                };
+            }
+        }
+        else if (branchRecovery?.failure_kind === 'conflict') {
+            const transitionAttemptedAt = now();
+            const transitionResult = await transitionIssueState({
+                issueId: input.issueId,
+                stateName: 'Rework',
+                expectedStateName: currentIssueState,
+                expectedStateType: currentIssueStateType,
+                expectedUpdatedAt: currentIssueUpdatedAt,
+                env,
+                sourceSetup: input.sourceSetup
+            });
+            const linearTransition = transitionResult.ok
+                ? {
+                    status: transitionResult.action === 'noop' ? 'noop' : 'transitioned',
+                    attempted_at: transitionAttemptedAt,
+                    previous_state: transitionResult.previous_state?.name ?? currentIssueState ?? null,
+                    target_state: transitionResult.target_state.name,
+                    issue_state: transitionResult.issue.state?.name ?? null,
+                    issue_state_type: transitionResult.issue.state?.type ?? null,
+                    issue_updated_at: transitionResult.issue.updated_at ?? currentIssueUpdatedAt,
+                    error: null
+                }
+                : {
+                    status: 'failed',
+                    attempted_at: transitionAttemptedAt,
+                    previous_state: currentIssueState ?? null,
+                    target_state: 'Rework',
+                    issue_state: currentIssueState ?? null,
+                    issue_state_type: currentIssueStateType ?? null,
+                    issue_updated_at: currentIssueUpdatedAt,
+                    error: `${transitionResult.error.code}: ${transitionResult.error.message}`
+                };
+            if (!transitionResult.ok) {
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    snapshot,
+                    branch_recovery: branchRecovery,
+                    linear_transition: linearTransition,
+                    status: 'transition_failed',
+                    reason: 'linear_rework_transition_failed_after_branch_recovery_conflict',
+                    summary: summarizeSelection(`Automatic ${describeProviderBranchRecoveryReason(branchRecovery.recovery_reason)} hit a merge conflict for attached PR #${pr.number}, and the Linear issue could not transition to Rework.`)
+                };
+            }
+            return {
+                ...baseWithResolution,
+                issue_state: linearTransition.issue_state,
+                issue_state_type: linearTransition.issue_state_type,
+                issue_updated_at: linearTransition.issue_updated_at,
+                pr,
+                snapshot,
+                branch_recovery: branchRecovery,
+                linear_transition: linearTransition,
+                status: 'action_required',
+                reason: 'branch_recovery_conflict',
+                summary: summarizeSelection(`Automatic ${describeProviderBranchRecoveryReason(branchRecovery.recovery_reason)} hit a merge conflict for attached PR #${pr.number}; moved the issue to Rework with exact recovery metadata recorded.`)
+            };
+        }
+        else if (branchRecovery) {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot,
+                branch_recovery: branchRecovery,
+                status: 'action_required',
+                reason: 'branch_recovery_failed',
+                summary: summarizeSelection(`Automatic ${describeProviderBranchRecoveryReason(branchRecovery.recovery_reason)} failed for attached PR #${pr.number}; inspect the recorded gh output before merge closeout can continue.`)
+            };
+        }
+        if (!alreadyMerged && !snapshot.ready_to_merge) {
+            const nonMergedOutcome = classifyNonMergedSnapshot(snapshot, pr.number);
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot,
+                ...nonMergedOutcome,
+                summary: summarizeSelection(nonMergedOutcome.summary)
+            };
+        }
+    }
+    const preMergeRateLimitOutcome = classifyProviderMutationRateLimitSnapshot(snapshot, pr.number, 'merge_closeout');
+    if (preMergeRateLimitOutcome) {
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot,
+            branch_recovery: branchRecovery,
+            ...preMergeRateLimitOutcome,
+            summary: summarizeSelection(preMergeRateLimitOutcome.summary)
+        };
+    }
+    let mergeAttempt = null;
+    let verificationSnapshot = snapshot;
+    if (!alreadyMerged) {
+        const mergeAttemptedAt = now();
+        const mergeArgs = buildPrMergeArgs({
+            owner: pr.owner,
+            repo: pr.repo,
+            prNumber: pr.number,
+            mergeMethod: PROVIDER_MERGE_CLOSEOUT_MERGE_METHOD,
+            deleteBranch: false,
+            headOid: snapshot.head_oid
+        });
+        const mergeResult = await runCommand({
+            command: 'gh',
+            args: mergeArgs,
+            cwd: input.repoRoot
+        });
+        mergeAttempt = {
+            attempted_at: mergeAttemptedAt,
+            command: 'gh',
+            args: mergeArgs,
+            exit_code: mergeResult.exitCode,
+            ok: mergeResult.ok,
+            stdout: normalizeCommandText(mergeResult.stdout),
+            stderr: normalizeCommandText(mergeResult.stderr)
+        };
+        let verificationRateLimit = null;
+        try {
+            const rawVerificationSnapshot = await resolveSnapshot({
+                owner: pr.owner,
+                repo: pr.repo,
+                prNumber: pr.number,
+                readinessMode: 'merge'
+            });
+            verificationSnapshot = mapSnapshotRecord(rawVerificationSnapshot, resolveSnapshotActionRequiredReasons(rawVerificationSnapshot, {
+                readinessMode: 'merge'
+            }));
+        }
+        catch (error) {
+            verificationRateLimit = resolveProviderGitHubRateLimitRecord(error);
+            // Preserve the pre-merge readiness snapshot when verification cannot be reread.
+        }
+        if (verificationRateLimit && mergeResult.ok === false) {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot: verificationSnapshot,
+                branch_recovery: branchRecovery,
+                merge_attempt: mergeAttempt,
+                status: 'merge_failed',
+                reason: 'merge_command_failed',
+                summary: summarizeSelection(`GitHub merge command failed before the pull request was confirmed merged; post-merge verification was also blocked by GitHub API budget: ${formatProviderGitHubRateLimitSummary(verificationRateLimit)}.`),
+                github_rate_limit: verificationRateLimit
+            };
+        }
+        if (verificationRateLimit) {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot: verificationSnapshot,
+                branch_recovery: branchRecovery,
+                merge_attempt: mergeAttempt,
+                status: 'watching',
+                reason: 'github_rate_limited',
+                summary: summarizeSelection(`GitHub API budget blocked post-merge verification snapshot loading: ${formatProviderGitHubRateLimitSummary(verificationRateLimit)}.`),
+                github_rate_limit: verificationRateLimit
+            };
+        }
+        if (verificationSnapshot.merged_at === null && verificationSnapshot.state !== 'MERGED') {
+            const verificationOutcome = classifyNonMergedSnapshot(verificationSnapshot, pr.number);
+            if (verificationOutcome) {
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    snapshot: verificationSnapshot,
+                    branch_recovery: branchRecovery,
+                    merge_attempt: mergeAttempt,
+                    ...verificationOutcome,
+                    summary: summarizeSelection(verificationOutcome.summary)
+                };
+            }
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot: verificationSnapshot,
+                branch_recovery: branchRecovery,
+                merge_attempt: mergeAttempt,
+                status: 'merge_failed',
+                reason: mergeResult.ok ? 'merge_not_confirmed' : 'merge_command_failed',
+                summary: summarizeSelection(mergeResult.ok
+                    ? 'GitHub merge command exited successfully, but the pull request did not report a merged timestamp.'
+                    : 'GitHub merge command failed before the pull request was confirmed merged.')
+            };
+        }
+    }
+    const sharedRoot = await reconcileSharedRootAfterMerge({
+        repoRoot: input.repoRoot,
+        now,
+        runCommand
+    });
+    if (sharedRoot.status === 'failed') {
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot: verificationSnapshot,
+            branch_recovery: branchRecovery,
+            merge_attempt: mergeAttempt,
+            shared_root: sharedRoot,
+            status: 'merge_failed',
+            reason: 'shared_root_reconciliation_failed',
+            summary: summarizeSelection('The pull request merged, but shared-root reconciliation failed.')
+        };
+    }
+    if (sharedRoot.status === 'skipped') {
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot: verificationSnapshot,
+            branch_recovery: branchRecovery,
+            merge_attempt: mergeAttempt,
+            shared_root: sharedRoot,
+            status: 'action_required',
+            reason: 'pending_shared_root_reconciliation',
+            summary: summarizeSelection(alreadyMerged
+                ? `Attached PR #${pr.number} was already merged; shared-root reconciliation is pending (${sharedRoot.reason}) before the Linear issue can transition to Done.`
+                : `Merged attached PR #${pr.number}; shared-root reconciliation is pending (${sharedRoot.reason}) before the Linear issue can transition to Done.`)
+        };
+    }
+    const transitionAttemptedAt = now();
+    const transitionResult = await transitionIssueState({
+        issueId: input.issueId,
+        stateName: 'Done',
+        expectedStateName: currentIssueState,
+        expectedStateType: currentIssueStateType,
+        expectedUpdatedAt: currentIssueUpdatedAt,
+        env,
+        sourceSetup: input.sourceSetup
+    });
+    const linearTransition = transitionResult.ok
+        ? {
+            status: transitionResult.action === 'noop' ? 'noop' : 'transitioned',
+            attempted_at: transitionAttemptedAt,
+            previous_state: transitionResult.previous_state?.name ?? currentIssueState ?? null,
+            target_state: transitionResult.target_state.name,
+            issue_state: transitionResult.issue.state?.name ?? null,
+            issue_state_type: transitionResult.issue.state?.type ?? null,
+            issue_updated_at: transitionResult.issue.updated_at ?? currentIssueUpdatedAt,
+            error: null
+        }
+        : {
+            status: 'failed',
+            attempted_at: transitionAttemptedAt,
+            previous_state: currentIssueState ?? null,
+            target_state: 'Done',
+            issue_state: currentIssueState ?? null,
+            issue_state_type: currentIssueStateType ?? null,
+            issue_updated_at: currentIssueUpdatedAt,
+            error: `${transitionResult.error.code}: ${transitionResult.error.message}`
+        };
+    if (!transitionResult.ok) {
+        if (alreadyMerged && transitionResult.error.code === 'linear_rate_limited') {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot: verificationSnapshot,
+                branch_recovery: branchRecovery,
+                merge_attempt: mergeAttempt,
+                shared_root: sharedRoot,
+                linear_transition: linearTransition,
+                status: 'merged',
+                reason: 'merged_and_shared_root_reconciled_transition_deferred',
+                summary: summarizeSelection(`Attached PR #${pr.number} was already merged and the shared root is reconciled; local merge closeout is authoritative while the Linear Done transition is deferred by shared-budget cooldown.`)
+            };
+        }
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot: verificationSnapshot,
+            branch_recovery: branchRecovery,
+            merge_attempt: mergeAttempt,
+            shared_root: sharedRoot,
+            linear_transition: linearTransition,
+            status: 'transition_failed',
+            reason: 'linear_done_transition_failed',
+            summary: summarizeSelection('The pull request merged, but the Linear issue could not transition to Done.')
+        };
+    }
+    return {
+        ...baseWithResolution,
+        issue_state: linearTransition.issue_state,
+        issue_state_type: linearTransition.issue_state_type,
+        issue_updated_at: linearTransition.issue_updated_at,
+        pr,
+        snapshot: verificationSnapshot,
+        branch_recovery: branchRecovery,
+        merge_attempt: mergeAttempt,
+        shared_root: sharedRoot,
+        linear_transition: linearTransition,
+        status: 'merged',
+        reason: alreadyMerged
+            ? 'merged_and_transitioned_done_after_recovery'
+            : 'merged_and_transitioned_done',
+        summary: summarizeSelection(alreadyMerged
+            ? `Attached PR #${pr.number} was already merged; reconciled shared root and transitioned the Linear issue to Done.`
+            : `Merged attached PR #${pr.number}, reconciled shared root, and transitioned the Linear issue to Done.`)
+    };
+}
+export async function runProviderReviewHandoffPromotion(input, deps = {}) {
+    const env = input.env ?? process.env;
+    const now = deps.now ?? isoTimestamp;
+    const readIssueContext = deps.readIssueContext ?? getProviderLinearIssueContext;
+    const transitionIssueState = deps.transitionIssueState ?? transitionProviderLinearIssueState;
+    const runCommand = deps.runCommand ?? runProviderMergeCloseoutCommand;
+    const resolveSnapshot = deps.fetchSnapshot ?? fetchPrStatusSnapshot;
+    const resolveSnapshotActionRequiredReasons = deps.resolveSnapshotActionRequiredReasons ??
+        ((snapshot, options) => resolveActionRequiredReasons(snapshot, options));
+    const recordedAt = now();
+    const base = {
+        recorded_at: recordedAt,
+        issue_id: input.issueId,
+        issue_identifier: normalizeOptionalString(input.issueIdentifier),
+        issue_state: normalizeOptionalString(input.issueState),
+        issue_state_type: normalizeOptionalString(input.issueStateType),
+        issue_updated_at: normalizeOptionalString(input.issueUpdatedAt),
+        attached_pr_urls: [],
+        ignored_historical_pr_urls: [],
+        ignored_closed_unmerged_pr_urls: [],
+        ignored_cross_issue_pr_urls: [],
+        conflicting_attached_pr_urls: [],
+        pr: null,
+        snapshot: null,
+        branch_recovery: null,
+        linear_transition: null,
+        github_rate_limit: null
+    };
+    const repoOriginResult = await runCommand({
+        command: 'git',
+        args: ['-C', input.repoRoot, 'remote', 'get-url', 'origin'],
+        cwd: input.repoRoot
+    });
+    if (!repoOriginResult.ok) {
+        return {
+            ...base,
+            status: 'promotion_failed',
+            reason: 'shared_root_origin_unavailable',
+            summary: 'Shared repo origin remote could not be resolved.'
+        };
+    }
+    const parsedRepo = parseGitHubRepoFromRemoteUrl(repoOriginResult.stdout);
+    const repoKey = parsedRepo
+        ? `${parsedRepo.owner.toLowerCase()}/${parsedRepo.repo.toLowerCase()}`
+        : null;
+    if (!repoKey) {
+        return {
+            ...base,
+            status: 'promotion_failed',
+            reason: 'shared_root_repo_unrecognized',
+            summary: 'Shared repo origin is not a GitHub repository URL.'
+        };
+    }
+    const issueContext = await readIssueContext({
+        issueId: input.issueId,
+        env,
+        sourceSetup: input.sourceSetup,
+        fallbackToCacheOnFailure: false
+    });
+    if (!issueContext.ok) {
+        return {
+            ...base,
+            status: 'promotion_failed',
+            reason: 'linear_issue_context_failed',
+            summary: `Linear issue context could not be loaded (${issueContext.error.code}).`
+        };
+    }
+    const attachedPrCandidates = collectAttachedGitHubPrCandidates(issueContext.issue.attachments);
+    const attachedPrUrls = attachedPrCandidates.map((candidate) => candidate.pr.url);
+    const sameRepoPrs = attachedPrCandidates.filter((candidate) => `${candidate.pr.owner.toLowerCase()}/${candidate.pr.repo.toLowerCase()}` === repoKey);
+    const currentIssueState = issueContext.issue.state?.name ?? base.issue_state;
+    const currentIssueStateType = issueContext.issue.state?.type ?? base.issue_state_type;
+    const currentIssueUpdatedAt = issueContext.issue.updated_at ?? base.issue_updated_at;
+    const currentWorkflowState = classifyProviderLinearWorkflowState({
+        state: currentIssueState,
+        state_type: currentIssueStateType
+    });
+    const baseWithContext = {
+        ...base,
+        issue_state: currentIssueState,
+        issue_state_type: currentIssueStateType,
+        issue_updated_at: currentIssueUpdatedAt,
+        attached_pr_urls: [...attachedPrUrls]
+    };
+    if (!currentWorkflowState.isHandoff) {
+        return {
+            ...baseWithContext,
+            status: 'action_required',
+            reason: 'issue_no_longer_review_handoff',
+            summary: currentIssueState && currentIssueState.trim().length > 0
+                ? `Live Linear issue state is ${currentIssueState}, so review-handoff promotion is not armed.`
+                : 'Live Linear issue state is no longer a review handoff state, so review-handoff promotion is not armed.'
+        };
+    }
+    if (sameRepoPrs.length === 0) {
+        return {
+            ...baseWithContext,
+            status: 'action_required',
+            reason: attachedPrUrls.length === 0 ? 'no_attached_pr' : 'attached_pr_repo_mismatch',
+            summary: attachedPrUrls.length === 0
+                ? 'No attached GitHub pull request is present for this review handoff issue.'
+                : 'Attached GitHub pull requests do not match the shared repository root.'
+        };
+    }
+    let ignoredHistoricalPrUrls = [];
+    let ignoredClosedUnmergedPrUrls = [];
+    let ignoredCrossIssuePrUrls = [];
+    let conflictingAttachedPrUrls = [];
+    let selectionNote = null;
+    let pr = sameRepoPrs[0].pr;
+    let snapshot = null;
+    if (sameRepoPrs.length > 1) {
+        let resolution;
+        try {
+            resolution = await resolveAttachedSameRepoPullRequestCandidate({
+                candidates: sameRepoPrs,
+                mode: 'review_promotion',
+                issueIdentifier: issueContext.issue.identifier,
+                blockedBy: input.blockedBy ?? null,
+                resolveSnapshot,
+                resolveSnapshotActionRequiredReasons
+            });
+        }
+        catch (error) {
+            const githubRateLimit = resolveProviderGitHubRateLimitRecord(error);
+            if (githubRateLimit) {
+                return {
+                    ...baseWithContext,
+                    status: 'watching',
+                    reason: 'github_rate_limited',
+                    summary: `GitHub API budget blocked attached pull-request disambiguation during review-handoff promotion: ${formatProviderGitHubRateLimitSummary(githubRateLimit)}.`,
+                    github_rate_limit: githubRateLimit
+                };
+            }
+            return {
+                ...baseWithContext,
+                status: 'promotion_failed',
+                reason: 'snapshot_read_failed',
+                summary: `GitHub merge-readiness snapshot could not be loaded while disambiguating attached pull requests: ${error?.message ?? String(error)}.`
+            };
+        }
+        ignoredHistoricalPrUrls = resolution.ignored_historical_pr_urls;
+        ignoredClosedUnmergedPrUrls = resolution.ignored_closed_unmerged_pr_urls;
+        ignoredCrossIssuePrUrls = resolution.ignored_cross_issue_pr_urls;
+        conflictingAttachedPrUrls = resolution.conflicting_attached_pr_urls;
+        selectionNote = resolution.selection_note;
+        if (!resolution.selected_pr) {
+            return {
+                ...baseWithContext,
+                ignored_historical_pr_urls: [...ignoredHistoricalPrUrls],
+                ignored_closed_unmerged_pr_urls: [...ignoredClosedUnmergedPrUrls],
+                ignored_cross_issue_pr_urls: [...ignoredCrossIssuePrUrls],
+                conflicting_attached_pr_urls: [...conflictingAttachedPrUrls],
+                status: 'action_required',
+                reason: 'multiple_attached_prs',
+                summary: buildMultipleAttachedPrsPromotionSummary({
+                    repoKey,
+                    ignoredHistoricalPrUrls,
+                    ignoredClosedUnmergedPrUrls,
+                    ignoredCrossIssuePrUrls,
+                    conflictingAttachedPrUrls
+                })
+            };
+        }
+        pr = resolution.selected_pr;
+        snapshot = resolution.selected_snapshot;
+    }
+    const baseWithResolution = {
+        ...baseWithContext,
+        ignored_historical_pr_urls: [...ignoredHistoricalPrUrls],
+        ignored_closed_unmerged_pr_urls: [...ignoredClosedUnmergedPrUrls],
+        ignored_cross_issue_pr_urls: [...ignoredCrossIssuePrUrls],
+        conflicting_attached_pr_urls: [...conflictingAttachedPrUrls]
+    };
+    const summarizeSelection = (summary) => selectionNote ? `${summary} ${selectionNote}` : summary;
+    if (!snapshot) {
+        try {
+            snapshot = await loadProviderSnapshotRecord({
+                owner: pr.owner,
+                repo: pr.repo,
+                prNumber: pr.number,
+                readinessMode: 'merge',
+                resolveSnapshot,
+                resolveSnapshotActionRequiredReasons
+            });
+        }
+        catch (error) {
+            const githubRateLimit = resolveProviderGitHubRateLimitRecord(error);
+            if (githubRateLimit) {
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    status: 'watching',
+                    reason: 'github_rate_limited',
+                    summary: summarizeSelection(`GitHub API budget blocked review-handoff readiness snapshot loading: ${formatProviderGitHubRateLimitSummary(githubRateLimit)}.`),
+                    snapshot: null,
+                    github_rate_limit: githubRateLimit
+                };
+            }
+            return {
+                ...baseWithResolution,
+                pr,
+                status: 'promotion_failed',
+                reason: 'snapshot_read_failed',
+                summary: summarizeSelection(`GitHub merge-readiness snapshot could not be loaded: ${error?.message ?? String(error)}`),
+                snapshot: null
+            };
+        }
+    }
+    if (!snapshot) {
+        return {
+            ...baseWithResolution,
+            pr,
+            status: 'promotion_failed',
+            reason: 'snapshot_read_failed',
+            summary: summarizeSelection('GitHub merge-readiness snapshot could not be loaded.'),
+            snapshot: null
+        };
+    }
+    let alreadyMerged = isMergedPullRequestSnapshot(snapshot);
+    let branchRecovery = null;
+    if (!alreadyMerged && !snapshot.ready_to_merge) {
+        const preRecoveryOutcome = classifyPreBranchRecoverySnapshot(snapshot, pr.number, 'review_promotion');
+        if (preRecoveryOutcome) {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot,
+                ...preRecoveryOutcome,
+                summary: summarizeSelection(preRecoveryOutcome.summary)
+            };
+        }
+        branchRecovery = await attemptProviderBranchRecovery({
+            pr,
+            snapshot,
+            previousBranchRecovery: input.previousBranchRecovery ?? null,
+            repoRoot: input.repoRoot,
+            now,
+            runCommand
+        });
+        if (branchRecovery?.ok) {
+            try {
+                snapshot = await loadProviderSnapshotRecord({
+                    owner: pr.owner,
+                    repo: pr.repo,
+                    prNumber: pr.number,
+                    readinessMode: 'merge',
+                    resolveSnapshot,
+                    resolveSnapshotActionRequiredReasons
+                });
+            }
+            catch (error) {
+                const githubRateLimit = resolveProviderGitHubRateLimitRecord(error);
+                if (githubRateLimit) {
+                    return {
+                        ...baseWithResolution,
+                        pr,
+                        snapshot,
+                        branch_recovery: branchRecovery,
+                        status: 'watching',
+                        reason: 'github_rate_limited',
+                        summary: summarizeSelection(`GitHub API budget blocked post-branch-recovery review-handoff verification: ${formatProviderGitHubRateLimitSummary(githubRateLimit)}.`),
+                        github_rate_limit: githubRateLimit
+                    };
+                }
+                // Preserve the pre-recovery snapshot when verification cannot be reread.
+            }
+            alreadyMerged = isMergedPullRequestSnapshot(snapshot);
+            if (!alreadyMerged && !snapshot.ready_to_merge) {
+                const prePendingRecoveryOutcome = classifyPreBranchRecoverySnapshot(snapshot, pr.number, 'review_promotion');
+                if (prePendingRecoveryOutcome) {
+                    return {
+                        ...baseWithResolution,
+                        pr,
+                        snapshot,
+                        branch_recovery: branchRecovery,
+                        ...prePendingRecoveryOutcome,
+                        summary: summarizeSelection(prePendingRecoveryOutcome.summary)
+                    };
+                }
+                const pendingRecovery = classifyPendingBranchRecovery({
+                    snapshot,
+                    recoveryAttempt: branchRecovery,
+                    prNumber: pr.number,
+                    mode: 'review_promotion'
+                });
+                if (pendingRecovery) {
+                    return {
+                        ...baseWithResolution,
+                        pr,
+                        snapshot,
+                        branch_recovery: branchRecovery,
+                        ...pendingRecovery,
+                        summary: summarizeSelection(pendingRecovery.summary)
+                    };
+                }
+                const promotionOutcome = classifyNonMergedReviewPromotionSnapshot(snapshot, pr.number);
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    snapshot,
+                    branch_recovery: branchRecovery,
+                    ...promotionOutcome,
+                    summary: summarizeSelection(promotionOutcome.summary)
+                };
+            }
+        }
+        else if (branchRecovery?.failure_kind === 'conflict') {
+            const transitionAttemptedAt = now();
+            const transitionResult = await transitionIssueState({
+                issueId: input.issueId,
+                stateName: 'Rework',
+                expectedStateName: currentIssueState,
+                expectedStateType: currentIssueStateType,
+                expectedUpdatedAt: currentIssueUpdatedAt,
+                env,
+                sourceSetup: input.sourceSetup
+            });
+            const linearTransition = transitionResult.ok
+                ? {
+                    status: transitionResult.action === 'noop' ? 'noop' : 'transitioned',
+                    attempted_at: transitionAttemptedAt,
+                    previous_state: transitionResult.previous_state?.name ?? currentIssueState ?? null,
+                    target_state: transitionResult.target_state.name,
+                    issue_state: transitionResult.issue.state?.name ?? null,
+                    issue_state_type: transitionResult.issue.state?.type ?? null,
+                    issue_updated_at: transitionResult.issue.updated_at ?? currentIssueUpdatedAt,
+                    error: null
+                }
+                : {
+                    status: 'failed',
+                    attempted_at: transitionAttemptedAt,
+                    previous_state: currentIssueState ?? null,
+                    target_state: 'Rework',
+                    issue_state: currentIssueState ?? null,
+                    issue_state_type: currentIssueStateType ?? null,
+                    issue_updated_at: currentIssueUpdatedAt,
+                    error: `${transitionResult.error.code}: ${transitionResult.error.message}`
+                };
+            if (!transitionResult.ok) {
+                return {
+                    ...baseWithResolution,
+                    pr,
+                    snapshot,
+                    branch_recovery: branchRecovery,
+                    linear_transition: linearTransition,
+                    status: 'transition_failed',
+                    reason: 'linear_rework_transition_failed_after_branch_recovery_conflict',
+                    summary: summarizeSelection(`Automatic ${describeProviderBranchRecoveryReason(branchRecovery.recovery_reason)} hit a merge conflict for attached PR #${pr.number}, and the Linear issue could not transition to Rework before review handoff could continue.`)
+                };
+            }
+            return {
+                ...baseWithResolution,
+                issue_state: linearTransition.issue_state,
+                issue_state_type: linearTransition.issue_state_type,
+                issue_updated_at: linearTransition.issue_updated_at,
+                pr,
+                snapshot,
+                branch_recovery: branchRecovery,
+                linear_transition: linearTransition,
+                status: 'action_required',
+                reason: 'branch_recovery_conflict',
+                summary: summarizeSelection(`Automatic ${describeProviderBranchRecoveryReason(branchRecovery.recovery_reason)} hit a merge conflict for attached PR #${pr.number}; moved the issue to Rework with exact recovery metadata recorded.`)
+            };
+        }
+        else if (branchRecovery) {
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot,
+                branch_recovery: branchRecovery,
+                status: 'action_required',
+                reason: 'branch_recovery_failed',
+                summary: summarizeSelection(`Automatic ${describeProviderBranchRecoveryReason(branchRecovery.recovery_reason)} failed for attached PR #${pr.number}; inspect the recorded gh output before review-handoff promotion can continue.`)
+            };
+        }
+        if (!alreadyMerged && !snapshot.ready_to_merge) {
+            const promotionOutcome = classifyNonMergedReviewPromotionSnapshot(snapshot, pr.number);
+            return {
+                ...baseWithResolution,
+                pr,
+                snapshot,
+                ...promotionOutcome,
+                summary: summarizeSelection(promotionOutcome.summary)
+            };
+        }
+    }
+    const prePromotionRateLimitOutcome = classifyProviderMutationRateLimitSnapshot(snapshot, pr.number, 'review_promotion');
+    if (prePromotionRateLimitOutcome) {
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot,
+            branch_recovery: branchRecovery,
+            ...prePromotionRateLimitOutcome,
+            summary: summarizeSelection(prePromotionRateLimitOutcome.summary)
+        };
+    }
+    const transitionAttemptedAt = now();
+    const transitionResult = await transitionIssueState({
+        issueId: input.issueId,
+        stateName: 'Merging',
+        expectedStateName: currentIssueState,
+        expectedStateType: currentIssueStateType,
+        expectedUpdatedAt: currentIssueUpdatedAt,
+        env,
+        sourceSetup: input.sourceSetup
+    });
+    const linearTransition = transitionResult.ok
+        ? {
+            status: transitionResult.action === 'noop' ? 'noop' : 'transitioned',
+            attempted_at: transitionAttemptedAt,
+            previous_state: transitionResult.previous_state?.name ?? currentIssueState ?? null,
+            target_state: transitionResult.target_state.name,
+            issue_state: transitionResult.issue.state?.name ?? null,
+            issue_state_type: transitionResult.issue.state?.type ?? null,
+            issue_updated_at: transitionResult.issue.updated_at ?? currentIssueUpdatedAt,
+            error: null
+        }
+        : {
+            status: 'failed',
+            attempted_at: transitionAttemptedAt,
+            previous_state: currentIssueState ?? null,
+            target_state: 'Merging',
+            issue_state: currentIssueState ?? null,
+            issue_state_type: currentIssueStateType ?? null,
+            issue_updated_at: currentIssueUpdatedAt,
+            error: `${transitionResult.error.code}: ${transitionResult.error.message}`
+        };
+    if (!transitionResult.ok) {
+        return {
+            ...baseWithResolution,
+            pr,
+            snapshot,
+            branch_recovery: branchRecovery,
+            linear_transition: linearTransition,
+            status: 'transition_failed',
+            reason: 'linear_merging_transition_failed',
+            summary: summarizeSelection(alreadyMerged
+                ? `Attached PR #${pr.number} is already merged, but the Linear issue could not transition to Merging for deterministic closeout.`
+                : `Attached PR #${pr.number} is merge-ready, but the Linear issue could not transition to Merging.`)
+        };
+    }
+    return {
+        ...baseWithResolution,
+        issue_state: linearTransition.issue_state,
+        issue_state_type: linearTransition.issue_state_type,
+        issue_updated_at: linearTransition.issue_updated_at,
+        pr,
+        snapshot,
+        branch_recovery: branchRecovery,
+        linear_transition: linearTransition,
+        status: 'promoted',
+        reason: 'promoted_to_merging',
+        summary: summarizeSelection(alreadyMerged
+            ? `Attached PR #${pr.number} is already merged; promoted the issue from review handoff into Merging for deterministic closeout.`
+            : `Promoted attached PR #${pr.number} from review handoff into Merging.`)
+    };
+}
+async function reconcileSharedRootAfterMerge(input) {
+    const attemptedAt = input.now();
+    const beforeStatusResult = await input.runCommand({
+        command: 'git',
+        args: ['-C', input.repoRoot, 'status', '--short', '--branch'],
+        cwd: input.repoRoot
+    });
+    const beforeStatus = normalizeCommandText(beforeStatusResult.stdout);
+    if (!beforeStatusResult.ok) {
+        return {
+            status: 'failed',
+            attempted_at: attemptedAt,
+            before_status: beforeStatus,
+            after_status: null,
+            reason: 'git_status_failed'
+        };
+    }
+    const safety = assessSharedRootMergeSafety(beforeStatus);
+    if (!safety.safe) {
+        return {
+            status: 'skipped',
+            attempted_at: attemptedAt,
+            before_status: beforeStatus,
+            after_status: beforeStatus,
+            reason: safety.reason
+        };
+    }
+    const fetchResult = await input.runCommand({
+        command: 'git',
+        args: ['-C', input.repoRoot, 'fetch', 'origin', 'refs/heads/main:refs/remotes/origin/main'],
+        cwd: input.repoRoot
+    });
+    if (!fetchResult.ok) {
+        return {
+            status: 'failed',
+            attempted_at: attemptedAt,
+            before_status: beforeStatus,
+            after_status: null,
+            reason: 'shared_root_fetch_failed'
+        };
+    }
+    const mergeResult = await input.runCommand({
+        command: 'git',
+        args: ['-C', input.repoRoot, 'merge', '--ff-only', 'origin/main'],
+        cwd: input.repoRoot
+    });
+    if (!mergeResult.ok) {
+        return {
+            status: 'failed',
+            attempted_at: attemptedAt,
+            before_status: beforeStatus,
+            after_status: null,
+            reason: 'shared_root_fast_forward_failed'
+        };
+    }
+    const afterStatusResult = await input.runCommand({
+        command: 'git',
+        args: ['-C', input.repoRoot, 'status', '--short', '--branch'],
+        cwd: input.repoRoot
+    });
+    return {
+        status: afterStatusResult.ok ? 'reconciled' : 'failed',
+        attempted_at: attemptedAt,
+        before_status: beforeStatus,
+        after_status: normalizeCommandText(afterStatusResult.stdout),
+        reason: afterStatusResult.ok ? 'shared_root_reconciled' : 'git_status_after_failed'
+    };
+}
+async function runProviderMergeCloseoutCommand(input) {
+    try {
+        const { stdout, stderr } = await execFileAsync(input.command, input.args, {
+            cwd: input.cwd,
+            timeout: PROVIDER_MERGE_CLOSEOUT_COMMAND_TIMEOUT_MS
+        });
+        return {
+            ok: true,
+            exitCode: 0,
+            stdout,
+            stderr
+        };
+    }
+    catch (error) {
+        const execError = error;
+        const timedOut = execError.killed === true && execError.signal === 'SIGTERM';
+        return {
+            ok: false,
+            exitCode: typeof execError.code === 'number' && Number.isInteger(execError.code)
+                ? execError.code
+                : null,
+            stdout: typeof execError.stdout === 'string' ? execError.stdout : '',
+            stderr: typeof execError.stderr === 'string' && execError.stderr.length > 0
+                ? execError.stderr
+                : timedOut
+                    ? `command timed out after ${PROVIDER_MERGE_CLOSEOUT_COMMAND_TIMEOUT_MS}ms`
+                    : (execError.message ?? '')
+        };
+    }
+}
+function collectAttachedGitHubPrCandidates(attachments) {
+    const candidatesByUrl = new Map();
+    for (const attachment of attachments) {
+        const parsed = parseGitHubPullRequestUrl(attachment?.url);
+        const comparisonKey = parsed
+            ? `${parsed.owner.toLowerCase()}/${parsed.repo.toLowerCase()}#${parsed.number}`
+            : null;
+        if (!parsed || !comparisonKey) {
+            continue;
+        }
+        const title = normalizeOptionalString(attachment?.title);
+        const existingCandidate = candidatesByUrl.get(comparisonKey);
+        if (existingCandidate) {
+            existingCandidate.attachment_title = title;
+            continue;
+        }
+        candidatesByUrl.set(comparisonKey, {
+            pr: parsed,
+            attachment_title: title
+        });
+    }
+    return [...candidatesByUrl.values()];
+}
+async function resolveAttachedSameRepoPullRequestCandidate(input) {
+    const mode = input.mode ?? 'merge_closeout';
+    const ignoredCrossIssueCandidates = mode === 'review_promotion'
+        ? input.candidates.filter((candidate) => isReviewPromotionCrossIssueCandidate({
+            attachmentTitle: candidate.attachment_title,
+            issueIdentifier: input.issueIdentifier ?? null,
+            blockedBy: input.blockedBy ?? null
+        }))
+        : [];
+    const ignoredCrossIssuePrUrls = ignoredCrossIssueCandidates.map((candidate) => candidate.pr.url);
+    const ignoredCrossIssueUrlSet = new Set(ignoredCrossIssuePrUrls);
+    const inspectedCandidates = [];
+    for (const candidate of input.candidates) {
+        if (ignoredCrossIssueUrlSet.has(candidate.pr.url)) {
+            continue;
+        }
+        const rawSnapshot = await input.resolveSnapshot({
+            owner: candidate.pr.owner,
+            repo: candidate.pr.repo,
+            prNumber: candidate.pr.number,
+            readinessMode: 'merge'
+        });
+        const snapshot = mapSnapshotRecord(rawSnapshot, input.resolveSnapshotActionRequiredReasons(rawSnapshot, {
+            readinessMode: 'merge'
+        }));
+        if (snapshot.github_rate_limit && !isTerminalPullRequestSnapshot(snapshot)) {
+            throw buildProviderGitHubRateLimitError(snapshot.github_rate_limit);
+        }
+        inspectedCandidates.push({
+            pr: candidate.pr,
+            snapshot,
+            attachment_title: candidate.attachment_title
+        });
+    }
+    const openUnmergedCandidates = inspectedCandidates.filter((candidate) => !isMergedPullRequestSnapshot(candidate.snapshot) && candidate.snapshot.state !== 'CLOSED');
+    const ignoredClosedUnmergedCandidates = mode === 'merge_closeout' && openUnmergedCandidates.length === 1
+        ? inspectedCandidates.filter((candidate) => isClosedUnmergedPullRequestSnapshot(candidate.snapshot))
+        : inspectedCandidates.filter((candidate) => isClosedUnmergedPullRequestSnapshot(candidate.snapshot) &&
+            openUnmergedCandidates.some((openCandidate) => isSnapshotStrictlyOlderThanSelection(candidate.snapshot, openCandidate.snapshot)));
+    const ignoredClosedUnmergedPrUrls = ignoredClosedUnmergedCandidates.map((candidate) => candidate.pr.url);
+    const ignoredClosedUnmergedUrlSet = new Set(ignoredClosedUnmergedPrUrls);
+    const resolutionCandidates = inspectedCandidates.filter((candidate) => !ignoredClosedUnmergedUrlSet.has(candidate.pr.url));
+    if (resolutionCandidates.length === 1) {
+        const selectedCandidate = resolutionCandidates[0];
+        return {
+            selected_pr: selectedCandidate.pr,
+            selected_snapshot: selectedCandidate.snapshot,
+            ignored_historical_pr_urls: [],
+            ignored_closed_unmerged_pr_urls: ignoredClosedUnmergedPrUrls,
+            ignored_cross_issue_pr_urls: ignoredCrossIssuePrUrls,
+            conflicting_attached_pr_urls: [],
+            selection_note: buildIgnoredAttachedPrSelectionNote({
+                ignoredClosedUnmergedPrUrls,
+                ignoredCrossIssuePrUrls
+            })
+        };
+    }
+    const mergedCandidates = resolutionCandidates.filter((candidate) => isMergedPullRequestSnapshot(candidate.snapshot));
+    const nonMergedCandidates = resolutionCandidates.filter((candidate) => !isMergedPullRequestSnapshot(candidate.snapshot));
+    if (mergedCandidates.length > 0 && nonMergedCandidates.length === 1) {
+        const selectedCandidate = nonMergedCandidates[0];
+        const ignoredHistoricalCandidates = mergedCandidates.filter((candidate) => isSnapshotStrictlyOlderThanSelection(candidate.snapshot, selectedCandidate.snapshot));
+        if (ignoredHistoricalCandidates.length === mergedCandidates.length) {
+            const ignoredHistoricalPrUrls = ignoredHistoricalCandidates.map((candidate) => candidate.pr.url);
+            return {
+                selected_pr: selectedCandidate.pr,
+                selected_snapshot: selectedCandidate.snapshot,
+                ignored_historical_pr_urls: ignoredHistoricalPrUrls,
+                ignored_closed_unmerged_pr_urls: ignoredClosedUnmergedPrUrls,
+                ignored_cross_issue_pr_urls: ignoredCrossIssuePrUrls,
+                conflicting_attached_pr_urls: [],
+                selection_note: appendIgnoredAttachedPrSelectionNote(ignoredHistoricalPrUrls.length > 0
+                    ? `Ignored historical merged PR URLs: ${ignoredHistoricalPrUrls.join(', ')}.`
+                    : null, {
+                    ignoredClosedUnmergedPrUrls,
+                    ignoredCrossIssuePrUrls
+                })
+            };
+        }
+    }
+    const selectedMergedCandidate = mergedCandidates.reduce((currentNewest, candidate) => !currentNewest || isSnapshotStrictlyOlderThanSelection(currentNewest.snapshot, candidate.snapshot)
+        ? candidate
+        : currentNewest, null);
+    if (selectedMergedCandidate) {
+        const otherMergedCandidates = mergedCandidates.filter((candidate) => candidate.pr.url !== selectedMergedCandidate.pr.url);
+        const ignoredHistoricalMergedCandidates = otherMergedCandidates.filter((candidate) => isSnapshotStrictlyOlderThanSelection(candidate.snapshot, selectedMergedCandidate.snapshot));
+        const staleUnmergedCandidates = nonMergedCandidates.filter((candidate) => isSnapshotStrictlyOlderThanSelection(candidate.snapshot, selectedMergedCandidate.snapshot));
+        if (ignoredHistoricalMergedCandidates.length === otherMergedCandidates.length &&
+            staleUnmergedCandidates.length === nonMergedCandidates.length) {
+            const ignoredHistoricalMergedPrUrls = ignoredHistoricalMergedCandidates.map((candidate) => candidate.pr.url);
+            const staleUnmergedPrUrls = staleUnmergedCandidates.map((candidate) => candidate.pr.url);
+            const ignoredHistoricalPrUrls = [
+                ...ignoredHistoricalMergedPrUrls,
+                ...staleUnmergedPrUrls
+            ];
+            return {
+                selected_pr: selectedMergedCandidate.pr,
+                selected_snapshot: selectedMergedCandidate.snapshot,
+                ignored_historical_pr_urls: ignoredHistoricalPrUrls,
+                ignored_closed_unmerged_pr_urls: ignoredClosedUnmergedPrUrls,
+                ignored_cross_issue_pr_urls: ignoredCrossIssuePrUrls,
+                conflicting_attached_pr_urls: [],
+                selection_note: appendIgnoredAttachedPrSelectionNote(`Selected already-merged PR ${selectedMergedCandidate.pr.url} because all remaining attached same-repo PR URLs are older.${ignoredHistoricalMergedPrUrls.length > 0 ? ` Ignored older merged PR URLs: ${ignoredHistoricalMergedPrUrls.join(', ')}.` : ''}${staleUnmergedPrUrls.length > 0 ? ` Older unmerged PR URLs: ${staleUnmergedPrUrls.join(', ')}.` : ''}`, {
+                    ignoredClosedUnmergedPrUrls,
+                    ignoredCrossIssuePrUrls
+                })
+            };
+        }
+    }
+    const ignoredHistoricalCandidates = nonMergedCandidates.length > 0
+        ? mergedCandidates.filter((candidate) => nonMergedCandidates.every((currentCandidate) => isSnapshotStrictlyOlderThanSelection(candidate.snapshot, currentCandidate.snapshot)))
+        : [];
+    const ignoredHistoricalPrUrls = ignoredHistoricalCandidates.map((candidate) => candidate.pr.url);
+    const ignoredHistoricalUrlSet = new Set(ignoredHistoricalPrUrls);
+    return {
+        selected_pr: null,
+        selected_snapshot: null,
+        ignored_historical_pr_urls: ignoredHistoricalPrUrls,
+        ignored_closed_unmerged_pr_urls: ignoredClosedUnmergedPrUrls,
+        ignored_cross_issue_pr_urls: ignoredCrossIssuePrUrls,
+        conflicting_attached_pr_urls: resolutionCandidates
+            .filter((candidate) => !ignoredHistoricalUrlSet.has(candidate.pr.url))
+            .map((candidate) => candidate.pr.url),
+        selection_note: null
+    };
+}
+function buildMultipleAttachedPrsSummary(input) {
+    const ignoredSummary = buildIgnoredAttachedPrSummary({
+        ignoredHistoricalPrUrls: input.ignoredHistoricalPrUrls,
+        ignoredClosedUnmergedPrUrls: input.ignoredClosedUnmergedPrUrls,
+        ignoredCrossIssuePrUrls: []
+    });
+    if (input.conflictingAttachedPrUrls.length === 0) {
+        return `Attached GitHub pull requests match ${input.repoKey}, but no current merge candidate remains after bounded filtering; merge closeout is not armed.${ignoredSummary}`;
+    }
+    return `Multiple attached GitHub pull requests match ${input.repoKey}; conflicting attached PR URLs still require deterministic disambiguation: ${input.conflictingAttachedPrUrls.join(', ')}.${ignoredSummary}`;
+}
+function buildMultipleAttachedPrsPromotionSummary(input) {
+    const ignoredSummary = buildIgnoredAttachedPrSummary({
+        ignoredHistoricalPrUrls: input.ignoredHistoricalPrUrls,
+        ignoredClosedUnmergedPrUrls: input.ignoredClosedUnmergedPrUrls,
+        ignoredCrossIssuePrUrls: input.ignoredCrossIssuePrUrls
+    });
+    if (input.conflictingAttachedPrUrls.length === 0) {
+        return `Attached GitHub pull requests match ${input.repoKey}, but no current review-handoff promotion candidate remains after bounded filtering.${ignoredSummary}`;
+    }
+    return `Multiple attached GitHub pull requests match ${input.repoKey}; conflicting current-candidate PR URLs still require deterministic disambiguation before review-handoff promotion can continue: ${input.conflictingAttachedPrUrls.join(', ')}.${ignoredSummary}`;
+}
+async function loadProviderSnapshotRecord(input) {
+    const rawSnapshot = await input.resolveSnapshot({
+        owner: input.owner,
+        repo: input.repo,
+        prNumber: input.prNumber,
+        readinessMode: input.readinessMode
+    });
+    const actionRequiredReasons = input.resolveSnapshotActionRequiredReasons(rawSnapshot, {
+        readinessMode: input.readinessMode
+    });
+    return mapSnapshotRecord(rawSnapshot, actionRequiredReasons);
+}
+function describeProviderBranchRecoveryReason(reason) {
+    if (reason === 'merge_state=DIRTY') {
+        return 'conflict recovery';
+    }
+    return 'branch refresh';
+}
+function doesProviderBranchRecoveryMatchPullRequest(recovery, pr) {
+    if (!recovery || recovery.command !== 'gh') {
+        return false;
+    }
+    const expectedRepo = `${pr.owner}/${pr.repo}`;
+    return (recovery.args[0] === 'pr'
+        && recovery.args[1] === 'update-branch'
+        && recovery.args[2] === String(pr.number)
+        && recovery.args.includes(expectedRepo));
+}
+async function attemptProviderBranchRecovery(input) {
+    const recoveryReason = resolveAutomaticBranchRecoveryReason(input.snapshot, {
+        requireExclusive: true
+    });
+    if (!recoveryReason
+        || !shouldAttemptAutomaticBranchRecovery(input.snapshot)) {
+        return null;
+    }
+    const previousBranchRecovery = input.previousBranchRecovery ?? null;
+    if (previousBranchRecovery?.ok === true
+        && previousBranchRecovery.failure_kind === null
+        && doesProviderBranchRecoveryMatchPullRequest(previousBranchRecovery, input.pr)
+        && previousBranchRecovery.head_oid === input.snapshot.head_oid
+        && previousBranchRecovery.recovery_reason === recoveryReason) {
+        return previousBranchRecovery;
+    }
+    const attemptedAt = input.now();
+    const args = buildPrUpdateBranchArgs({
+        owner: input.pr.owner,
+        repo: input.pr.repo,
+        prNumber: input.pr.number
+    });
+    const result = await input.runCommand({
+        command: 'gh',
+        args,
+        cwd: input.repoRoot
+    });
+    const details = normalizeCommandText(result.stderr) ?? normalizeCommandText(result.stdout);
+    return {
+        attempted_at: attemptedAt,
+        head_oid: input.snapshot.head_oid,
+        recovery_reason: recoveryReason,
+        command: 'gh',
+        args,
+        exit_code: result.exitCode,
+        ok: result.ok,
+        stdout: normalizeCommandText(result.stdout),
+        stderr: normalizeCommandText(result.stderr),
+        failure_kind: result.ok
+            ? null
+            : isConflictLikeBranchRecoveryFailureMessage(details) ? 'conflict' : 'other'
+    };
+}
+function classifyPreBranchRecoverySnapshot(snapshot, prNumber, mode) {
+    if (snapshot.state === 'CLOSED') {
+        return {
+            status: 'action_required',
+            reason: 'pr_closed_unmerged',
+            summary: mode === 'review_promotion'
+                ? `Attached PR #${prNumber} is closed without merging; reopen it or attach a replacement PR before review-handoff promotion can continue.`
+                : `Attached PR #${prNumber} is closed without merging; reopen it or attach a replacement PR.`
+        };
+    }
+    if (snapshot.action_required_reasons.length > 0
+        && !shouldAttemptAutomaticBranchRecovery(snapshot)) {
+        return {
+            status: 'action_required',
+            reason: snapshot.action_required_reasons[0] ??
+                (mode === 'review_promotion'
+                    ? 'review_handoff_promotion_blocked'
+                    : 'merge_action_required'),
+            summary: mode === 'review_promotion'
+                ? `Review-handoff promotion is blocked by: ${snapshot.action_required_reasons.join(', ')}.`
+                : `Merge closeout is blocked by: ${snapshot.action_required_reasons.join(', ')}.`
+        };
+    }
+    if (snapshot.github_rate_limit) {
+        return {
+            status: 'watching',
+            reason: 'github_rate_limited',
+            summary: mode === 'review_promotion'
+                ? `Review-handoff promotion is waiting for GitHub API budget recovery before rereading PR #${prNumber}: ${formatProviderGitHubRateLimitSummary(snapshot.github_rate_limit)}.`
+                : `Merge closeout is waiting for GitHub API budget recovery before rereading PR #${prNumber}: ${formatProviderGitHubRateLimitSummary(snapshot.github_rate_limit)}.`,
+            github_rate_limit: snapshot.github_rate_limit
+        };
+    }
+    return null;
+}
+function classifyProviderMutationRateLimitSnapshot(snapshot, prNumber, mode) {
+    if (!snapshot.github_rate_limit || isMergedPullRequestSnapshot(snapshot)) {
+        return null;
+    }
+    return {
+        status: 'watching',
+        reason: 'github_rate_limited',
+        summary: mode === 'review_promotion'
+            ? `Review-handoff promotion is waiting for GitHub API budget recovery before mutating PR #${prNumber}: ${formatProviderGitHubRateLimitSummary(snapshot.github_rate_limit)}.`
+            : `Merge closeout is waiting for GitHub API budget recovery before mutating PR #${prNumber}: ${formatProviderGitHubRateLimitSummary(snapshot.github_rate_limit)}.`,
+        github_rate_limit: snapshot.github_rate_limit
+    };
+}
+function classifyPendingBranchRecovery(input) {
+    const pendingReason = resolveAutomaticBranchRecoveryReason(input.snapshot, {
+        requireExclusive: true
+    });
+    if (pendingReason !== input.recoveryAttempt.recovery_reason
+        || !shouldAttemptAutomaticBranchRecovery(input.snapshot)) {
+        return null;
+    }
+    const action = describeProviderBranchRecoveryReason(input.recoveryAttempt.recovery_reason);
+    return {
+        status: 'watching',
+        reason: 'branch_refresh_requested',
+        summary: input.mode === 'review_promotion'
+            ? `Requested automatic ${action} for attached PR #${input.prNumber}; waiting for GitHub to recompute review-handoff readiness.`
+            : `Requested automatic ${action} for attached PR #${input.prNumber}; waiting for GitHub to recompute merge readiness.`
+    };
+}
+function classifyNonMergedSnapshot(snapshot, prNumber) {
+    if (snapshot.state === 'CLOSED') {
+        return {
+            status: 'action_required',
+            reason: 'pr_closed_unmerged',
+            summary: `Attached PR #${prNumber} is closed without merging; reopen it or attach a replacement PR.`
+        };
+    }
+    if (snapshot.action_required_reasons.length > 0) {
+        return {
+            status: 'action_required',
+            reason: snapshot.action_required_reasons[0] ?? 'merge_action_required',
+            summary: `Merge closeout is blocked by: ${snapshot.action_required_reasons.join(', ')}.`
+        };
+    }
+    if (snapshot.github_rate_limit) {
+        return {
+            status: 'watching',
+            reason: 'github_rate_limited',
+            summary: `Merge closeout is waiting for GitHub API budget recovery before rereading PR #${prNumber}: ${formatProviderGitHubRateLimitSummary(snapshot.github_rate_limit)}.`,
+            github_rate_limit: snapshot.github_rate_limit
+        };
+    }
+    if (snapshot.gate_reasons.length > 0 || !snapshot.ready_to_merge) {
+        return {
+            status: 'watching',
+            reason: snapshot.gate_reasons[0] ?? 'waiting_for_merge_ready',
+            summary: snapshot.gate_reasons.length > 0
+                ? `Merge closeout is waiting for readiness gates to clear: ${snapshot.gate_reasons.join(', ')}.`
+                : 'Merge closeout is waiting for the attached pull request to become merge-ready.'
+        };
+    }
+    return null;
+}
+function classifyNonMergedReviewPromotionSnapshot(snapshot, prNumber) {
+    if (snapshot.state === 'CLOSED') {
+        return {
+            status: 'action_required',
+            reason: 'pr_closed_unmerged',
+            summary: `Attached PR #${prNumber} is closed without merging; reopen it or attach a replacement PR before review-handoff promotion can continue.`
+        };
+    }
+    if (snapshot.action_required_reasons.length > 0) {
+        return {
+            status: 'action_required',
+            reason: snapshot.action_required_reasons[0] ?? 'review_handoff_promotion_blocked',
+            summary: `Review-handoff promotion is blocked by: ${snapshot.action_required_reasons.join(', ')}.`
+        };
+    }
+    if (snapshot.github_rate_limit) {
+        return {
+            status: 'watching',
+            reason: 'github_rate_limited',
+            summary: `Review-handoff promotion is waiting for GitHub API budget recovery before rereading PR #${prNumber}: ${formatProviderGitHubRateLimitSummary(snapshot.github_rate_limit)}.`,
+            github_rate_limit: snapshot.github_rate_limit
+        };
+    }
+    if (snapshot.gate_reasons.length > 0 || !snapshot.ready_to_merge) {
+        return {
+            status: 'watching',
+            reason: snapshot.gate_reasons[0] ?? 'waiting_for_merge_ready',
+            summary: snapshot.gate_reasons.length > 0
+                ? `Review-handoff promotion is waiting for readiness gates to clear: ${snapshot.gate_reasons.join(', ')}.`
+                : 'Review-handoff promotion is waiting for the attached pull request to become merge-ready.'
+        };
+    }
+    return null;
+}
+function isMergedPullRequestSnapshot(snapshot) {
+    return snapshot.merged_at !== null || snapshot.state === 'MERGED';
+}
+function isClosedUnmergedPullRequestSnapshot(snapshot) {
+    return snapshot.state === 'CLOSED' && !isMergedPullRequestSnapshot(snapshot);
+}
+function isTerminalPullRequestSnapshot(snapshot) {
+    return isMergedPullRequestSnapshot(snapshot) || snapshot.state === 'CLOSED';
+}
+function isSnapshotStrictlyOlderThanSelection(candidate, selected) {
+    const candidateTimestamp = resolveSnapshotDisambiguationTimestamp(candidate);
+    const selectedTimestamp = resolveSnapshotDisambiguationTimestamp(selected);
+    if (candidateTimestamp === null || selectedTimestamp === null) {
+        return false;
+    }
+    return candidateTimestamp < selectedTimestamp;
+}
+function buildIgnoredAttachedPrSummary(input) {
+    const parts = [];
+    if (input.ignoredHistoricalPrUrls.length > 0) {
+        parts.push(`Ignored historical merged PR URLs: ${input.ignoredHistoricalPrUrls.join(', ')}.`);
+    }
+    if (input.ignoredClosedUnmergedPrUrls.length > 0) {
+        parts.push(`Ignored closed prior-attempt PR URLs: ${input.ignoredClosedUnmergedPrUrls.join(', ')}.`);
+    }
+    if (input.ignoredCrossIssuePrUrls.length > 0) {
+        parts.push(`Ignored cross-issue PR URLs: ${input.ignoredCrossIssuePrUrls.join(', ')}.`);
+    }
+    return parts.length > 0 ? ` ${parts.join(' ')}` : '';
+}
+function buildIgnoredAttachedPrSelectionNote(input) {
+    return appendIgnoredAttachedPrSelectionNote(null, input);
+}
+function appendIgnoredAttachedPrSelectionNote(baseNote, input) {
+    const parts = [];
+    if (typeof baseNote === 'string' && baseNote.trim().length > 0) {
+        parts.push(baseNote.trim());
+    }
+    if (input.ignoredClosedUnmergedPrUrls.length > 0) {
+        parts.push(`Ignored closed prior-attempt PR URLs: ${input.ignoredClosedUnmergedPrUrls.join(', ')}.`);
+    }
+    if (input.ignoredCrossIssuePrUrls.length > 0) {
+        parts.push(`Ignored cross-issue PR URLs: ${input.ignoredCrossIssuePrUrls.join(', ')}.`);
+    }
+    return parts.length > 0 ? parts.join(' ') : null;
+}
+function isReviewPromotionCrossIssueCandidate(input) {
+    const currentIssueIdentifier = normalizeIssueIdentifierToken(input.issueIdentifier);
+    if (!currentIssueIdentifier) {
+        return false;
+    }
+    const leadingIssueIdentifier = extractLeadingIssueIdentifier(input.attachmentTitle);
+    if (!leadingIssueIdentifier || leadingIssueIdentifier === currentIssueIdentifier) {
+        return false;
+    }
+    const title = normalizeOptionalString(input.attachmentTitle) ?? '';
+    const blockedIssueIdentifiers = new Set((input.blockedBy ?? [])
+        .map((blocker) => normalizeIssueIdentifierToken(blocker.identifier))
+        .filter((value) => value !== null));
+    if (blockedIssueIdentifiers.has(leadingIssueIdentifier) &&
+        hasReviewPromotionBlockerWording(title)) {
+        return true;
+    }
+    return /\bfollow(?:-| )up\b/i.test(title);
+}
+function extractLeadingIssueIdentifier(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const match = /^\s*[[(]?([A-Z][A-Z0-9]+-\d+)\b/i.exec(value);
+    return normalizeIssueIdentifierToken(match?.[1] ?? null);
+}
+function hasReviewPromotionBlockerWording(value) {
+    return /\bblock(?:er|ed|ing)?\b/i.test(value);
+}
+function normalizeIssueIdentifierToken(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim().toUpperCase();
+    return /^[A-Z][A-Z0-9]+-\d+$/.test(trimmed) ? trimmed : null;
+}
+function resolveSnapshotDisambiguationTimestamp(snapshot) {
+    const preferredTimestamp = isMergedPullRequestSnapshot(snapshot)
+        ? snapshot.merged_at ?? snapshot.updated_at
+        : snapshot.updated_at;
+    const parsed = Date.parse(preferredTimestamp ?? '');
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function mapSnapshotRecord(snapshot, actionRequiredReasons) {
+    const snapshotRecord = readRecord(snapshot);
+    const checks = readRecord(snapshot.checks);
+    const requiredChecks = readRecord(snapshot.requiredChecks);
+    const githubRateLimit = mapProviderGitHubRateLimit(readRecord(snapshotRecord?.githubRateLimit) ?? readRecord(snapshotRecord?.github_rate_limit));
+    return {
+        state: normalizeOptionalString(snapshot.state),
+        review_decision: normalizeOptionalString(snapshot.reviewDecision),
+        merge_state_status: normalizeOptionalString(snapshot.mergeStateStatus),
+        ready_to_merge: snapshot.readyToMerge === true,
+        gate_reasons: readStringArray(snapshot.gateReasons),
+        action_required_reasons: [...actionRequiredReasons],
+        unresolved_thread_count: normalizeOptionalNumber(snapshot.unresolvedThreadCount),
+        checks_pending: readArrayLength(checks?.pending),
+        checks_failed: readArrayLength(checks?.failed),
+        required_checks_pending: readArrayLength(requiredChecks?.pending),
+        required_checks_failed: readArrayLength(requiredChecks?.failed),
+        updated_at: normalizeOptionalString(snapshot.updatedAt),
+        merged_at: normalizeOptionalString(snapshot.mergedAt),
+        head_oid: normalizeOptionalString(snapshot.headOid),
+        github_rate_limit: githubRateLimit
+    };
+}
+function resolveProviderGitHubRateLimitRecord(input) {
+    const inputRecord = readRecord(input);
+    const embedded = inputRecord?.githubRateLimit ?? inputRecord?.github_rate_limit;
+    const embeddedRateLimit = mapProviderGitHubRateLimit(embedded);
+    if (embeddedRateLimit) {
+        return embeddedRateLimit;
+    }
+    return mapProviderGitHubRateLimit(resolveGitHubRateLimitStatus(input));
+}
+function mapProviderGitHubRateLimit(input) {
+    const rateLimit = readRecord(input);
+    if (!rateLimit || rateLimit.kind !== 'github_rate_limited') {
+        return null;
+    }
+    return {
+        kind: 'github_rate_limited',
+        surface: normalizeOptionalString(rateLimit.surface) ?? 'unknown',
+        limit_type: normalizeOptionalString(rateLimit.limit_type) ?? 'unknown',
+        status: normalizeOptionalNumber(rateLimit.status),
+        reset_at: normalizeOptionalString(rateLimit.reset_at),
+        retry_after_seconds: normalizeOptionalNumber(rateLimit.retry_after_seconds),
+        retry_at: normalizeOptionalString(rateLimit.retry_at),
+        message: normalizeOptionalString(rateLimit.message)
+    };
+}
+function formatProviderGitHubRateLimitSummary(rateLimit) {
+    return formatGitHubRateLimitStatus(rateLimit);
+}
+function buildProviderGitHubRateLimitError(rateLimit) {
+    const error = new Error(formatProviderGitHubRateLimitSummary(rateLimit));
+    error.githubRateLimit = rateLimit;
+    return error;
+}
+function assessSharedRootMergeSafety(statusOutput) {
+    const lines = (statusOutput ?? '').split(/\r?\n/u).filter((line) => line.length > 0);
+    const branchHeader = lines[0]?.trim() ?? '';
+    if (!branchHeader.startsWith('## ')) {
+        return {
+            safe: false,
+            reason: 'shared_root_status_header_missing'
+        };
+    }
+    if (!/^## main(?:$|\.{3})/u.test(branchHeader)) {
+        return {
+            safe: false,
+            reason: 'shared_root_not_on_main'
+        };
+    }
+    const trackingStatusMatch = branchHeader.match(/\[([^\]]+)\]\s*$/u);
+    if (trackingStatusMatch) {
+        const trackingParts = trackingStatusMatch[1]
+            .split(',')
+            .map((part) => part.trim().toLowerCase())
+            .filter((part) => part.length > 0);
+        const fastForwardSafe = trackingParts.every((part) => /^behind \d+$/u.test(part));
+        if (!fastForwardSafe) {
+            return {
+                safe: false,
+                reason: 'shared_root_not_ff_only_safe'
+            };
+        }
+    }
+    if (lines.length > 1) {
+        return {
+            safe: false,
+            reason: 'shared_root_dirty'
+        };
+    }
+    return {
+        safe: true,
+        reason: 'shared_root_clean_main'
+    };
+}
+function parseGitHubPullRequestUrl(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        return null;
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname !== 'github.com' && hostname !== 'www.github.com') {
+        return null;
+    }
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const owner = normalizeOptionalString(segments[0] ?? null);
+    const repo = normalizeOptionalString(segments[1] ?? null);
+    const resource = normalizeOptionalString(segments[2] ?? null)?.toLowerCase() ?? null;
+    const number = normalizePrNumber(segments[3] ?? null);
+    if (!owner || !repo || resource !== 'pull' || number === null) {
+        return null;
+    }
+    return {
+        url: `https://github.com/${owner}/${repo}/pull/${number}`,
+        owner,
+        repo,
+        number
+    };
+}
+function normalizePrNumber(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized || !/^\d+$/u.test(normalized)) {
+        return null;
+    }
+    const parsed = Number.parseInt(normalized, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function normalizeOptionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function normalizeProviderMergeCloseoutIssueState(value) {
+    const normalized = normalizeOptionalString(value);
+    return normalized ? normalized.toLowerCase() : null;
+}
+function isProbeRecoveryCacheContextFreshEnough(input) {
+    const expectedState = normalizeProviderMergeCloseoutIssueState(input.issueState);
+    const cachedState = normalizeProviderMergeCloseoutIssueState(input.issueContext.state?.name ?? null);
+    if (expectedState !== null && cachedState !== expectedState) {
+        return false;
+    }
+    const expectedStateType = normalizeOptionalString(input.issueStateType);
+    const cachedStateType = normalizeOptionalString(input.issueContext.state?.type ?? null);
+    if (expectedStateType !== null && cachedStateType !== expectedStateType) {
+        return false;
+    }
+    const expectedUpdatedAt = normalizeOptionalString(input.issueUpdatedAt);
+    if (expectedUpdatedAt === null) {
+        return true;
+    }
+    const cachedUpdatedAt = normalizeOptionalString(input.issueContext.updated_at);
+    if (cachedUpdatedAt === null) {
+        return false;
+    }
+    const expectedUpdatedAtMs = Date.parse(expectedUpdatedAt);
+    const cachedUpdatedAtMs = Date.parse(cachedUpdatedAt);
+    if (Number.isFinite(expectedUpdatedAtMs) && Number.isFinite(cachedUpdatedAtMs)) {
+        return cachedUpdatedAtMs >= expectedUpdatedAtMs;
+    }
+    return cachedUpdatedAt === expectedUpdatedAt;
+}
+function normalizeOptionalNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function normalizeCommandText(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function readRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readArrayLength(value) {
+    return Array.isArray(value) ? value.length : null;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}