@kbediako/codex-orchestrator 0.1.38 → 0.2.1

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

@@ -0,0 +1,756 @@
+import { isoTimestamp } from '../utils/time.js';
+import { readSharedLinearBudgetStatus, resolveLinearPollingInterval } from './linearBudgetState.js';
+import { resolveLiveLinearTrackedIssues, } from './linearDispatchSource.js';
+import { resolveLinearWebhookSourceSetup } from './linearWebhookController.js';
+import { initializeProviderPollingHealth, isProviderPollingStuck, flushProviderPollingHealthUpdates, markProviderPollingStuck, markProviderPollingCompleted, markProviderPollingStarted, noteProviderPollingRequest, readProviderPollingHealth, scheduleProviderPolling } from './providerPollingHealth.js';
+import { beginClosingControlServerHttpServer, closeControlServerOwnedRuntime, startControlServerReadyInstanceLifecycle } from './controlServerReadyInstanceLifecycle.js';
+import { prepareControlServerStartupInputs } from './controlServerStartupInputPreparation.js';
+import { acquireControlHostOwnership } from './controlHostOwnership.js';
+const EXPIRY_INTERVAL_MS = 15_000;
+const PROVIDER_REFRESH_INTERVAL_MS = 15_000;
+const PROVIDER_REFRESH_STUCK_AFTER_MS = 45_000;
+const PROVIDER_CLOSE_STUCK_DRAIN_GRACE_MS = 1_000;
+const PROVIDER_FULL_RECOVERY_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
+const SESSION_TTL_MS = 15 * 60 * 1000;
+const providerIssueHandoffOperations = new WeakMap();
+export async function startControlServerPublicLifecycle(options) {
+    let controlHostOwnership = null;
+    try {
+        controlHostOwnership =
+            !options.controlHostOwnership
+                ? null
+                : await acquireControlHostOwnership({
+                    paths: options.paths,
+                    runId: options.runId,
+                    repoRoot: options.controlHostOwnership?.repoRoot,
+                    taskId: options.controlHostOwnership?.taskId,
+                    pipelineId: options.controlHostOwnership?.pipelineId
+                });
+        const startupInputs = await prepareControlServerStartupInputs({
+            paths: options.paths,
+            config: options.config,
+            eventStream: options.eventStream,
+            runId: options.runId,
+            sessionTtlMs: SESSION_TTL_MS,
+            providerWorkflowConfigStore: options.providerWorkflowConfigStore,
+            createProviderIssueHandoff: options.createProviderIssueHandoff
+        });
+        const readyInstance = await startControlServerReadyInstanceLifecycle({
+            requestContextShared: startupInputs.requestContextShared,
+            host: startupInputs.host,
+            controlToken: startupInputs.controlToken,
+            intervalMs: EXPIRY_INTERVAL_MS
+        });
+        const providerRefreshCoordinator = startupInputs.requestContextShared.providerIssueHandoff
+            ? createProviderRefreshCoordinator(startupInputs.requestContextShared.providerIssueHandoff, {
+                readFeatureToggles: startupInputs.requestContextShared.controlStore
+                    ? () => startupInputs.requestContextShared.controlStore.snapshot().feature_toggles
+                    : null
+            })
+            : null;
+        if (startupInputs.requestContextShared.providerIssueHandoff) {
+            const persistProviderIntakePolling = startupInputs.requestContextShared.persist?.providerIntakePolling ?? null;
+            const persistedPollingSnapshot = startupInputs.requestContextShared.providerIntakeState?.polling ?? null;
+            initializeProviderPollingHealth(startupInputs.requestContextShared.providerIssueHandoff, {
+                intervalMs: PROVIDER_REFRESH_INTERVAL_MS,
+                stuckAfterMs: PROVIDER_REFRESH_STUCK_AFTER_MS,
+                controlHostOwner: controlHostOwnership?.polling ?? null,
+                skipInitialUpdate: persistedPollingSnapshot !== null,
+                onUpdate: startupInputs.requestContextShared.providerIntakeState && persistProviderIntakePolling
+                    ? async (polling) => {
+                        const pollingUpdatedAt = typeof polling.updated_at === 'string' && polling.updated_at.trim().length > 0
+                            ? polling.updated_at
+                            : isoTimestamp();
+                        const stateUpdatedAt = pickLatestTimestamp(startupInputs.requestContextShared.providerIntakeState.updated_at, pollingUpdatedAt);
+                        const nextPolling = {
+                            ...polling,
+                            updated_at: pollingUpdatedAt
+                        };
+                        startupInputs.requestContextShared.providerIntakeState.polling = nextPolling;
+                        startupInputs.requestContextShared.providerIntakeState.updated_at = stateUpdatedAt;
+                        await persistProviderIntakePolling(nextPolling, stateUpdatedAt);
+                    }
+                    : null
+            });
+        }
+        const providerRefreshStartupTrigger = providerRefreshCoordinator
+            ? scheduleStartupProviderRefresh(providerRefreshCoordinator.trigger)
+            : null;
+        return {
+            server: readyInstance.server,
+            requestContextShared: startupInputs.requestContextShared,
+            lifecycleState: readyInstance.lifecycleState,
+            ...(controlHostOwnership ? { controlHostOwnership } : {}),
+            ...(providerRefreshCoordinator
+                ? {
+                    providerRefreshTimer: providerRefreshCoordinator.timer,
+                    providerRefreshStartupTrigger,
+                    triggerProviderRefresh: providerRefreshCoordinator.trigger
+                }
+                : {}),
+            baseUrl: readyInstance.baseUrl
+        };
+    }
+    catch (error) {
+        await controlHostOwnership?.release().catch(() => undefined);
+        throw error;
+    }
+}
+export async function closeControlServerPublicLifecycle(state) {
+    if (state.providerRefreshStartupTrigger) {
+        clearTimeout(state.providerRefreshStartupTrigger);
+    }
+    if (state.providerRefreshTimer) {
+        state.providerRefreshTimer.cancel();
+    }
+    const serverClosePromise = beginClosingControlServerHttpServer(state.server);
+    void serverClosePromise.catch(() => undefined);
+    const providerIssueHandoff = state.requestContextShared.providerIssueHandoff ?? null;
+    let closeError = null;
+    const captureCloseError = (error) => {
+        if (closeError === null) {
+            closeError = error;
+        }
+    };
+    if (providerIssueHandoff) {
+        try {
+            await waitForProviderIssueHandoffQueueToDrain(providerIssueHandoff, () => resolveProviderIssueHandoffWatchdogDelayMs(providerIssueHandoff), { settleStuckPending: true });
+            await flushProviderPollingHealthUpdates(providerIssueHandoff);
+        }
+        catch (error) {
+            captureCloseError(error);
+        }
+    }
+    try {
+        await closeControlServerOwnedRuntime({
+            server: state.server,
+            requestContextShared: state.requestContextShared,
+            lifecycleState: state.lifecycleState,
+            serverClosePromise
+        });
+    }
+    catch (error) {
+        captureCloseError(error);
+    }
+    try {
+        await serverClosePromise;
+    }
+    catch (error) {
+        captureCloseError(error);
+    }
+    try {
+        await state.controlHostOwnership?.release();
+    }
+    catch (error) {
+        captureCloseError(error);
+    }
+    if (closeError !== null) {
+        throw closeError;
+    }
+}
+export function runProviderIssueHandoffRefresh(providerIssueHandoff, options) {
+    const state = getProviderIssueHandoffOperationState(providerIssueHandoff);
+    const acknowledgeAccepted = options?.acknowledgeAccepted === true;
+    const allowIdleRestartRequiredRetry = options?.allowIdleRestartRequiredRetry === true;
+    if (state.active) {
+        const continueWhileBusy = () => {
+            if (!options?.queueIfBusy) {
+                return mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, waitForProviderIssueHandoffPending(providerIssueHandoff, state.active), {
+                    queued: true,
+                    coalesced: true
+                });
+            }
+            noteProviderPollingRequest(providerIssueHandoff, {
+                mode: 'refresh',
+                queued: true,
+                preserveActiveMode: true
+            });
+            if (state.queuedRefresh) {
+                const queuedOutcome = {
+                    queued: true,
+                    coalesced: true
+                };
+                return acknowledgeAccepted
+                    ? acknowledgeProviderIssueHandoffAccepted(state.queuedRefresh, queuedOutcome)
+                    : mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, state.queuedRefresh, queuedOutcome);
+            }
+            const queuedRefresh = queueProviderIssueHandoffRefresh(providerIssueHandoff, state, () => providerIssueHandoff.refresh(), {
+                mode: 'refresh'
+            });
+            const queuedOutcome = {
+                queued: true,
+                coalesced: false
+            };
+            return acknowledgeAccepted
+                ? acknowledgeProviderIssueHandoffAccepted(queuedRefresh, queuedOutcome)
+                : mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, queuedRefresh, queuedOutcome);
+        };
+        if (isProviderPollingStuck(providerIssueHandoff)) {
+            return (async () => {
+                const stuckOutcome = await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff);
+                if (!stuckOutcome) {
+                    return continueWhileBusy();
+                }
+                if (allowIdleRestartRequiredRetry) {
+                    detachProviderIssueHandoffPending(state.active);
+                    detachProviderIssueHandoffPending(state.queuedRefresh);
+                    state.active = null;
+                    state.queuedRefresh = null;
+                    providerIssueHandoff.resetStuckRefreshLifecycle?.();
+                    const activeRefresh = waitForProviderIssueHandoffPending(providerIssueHandoff, startProviderIssueHandoffOperation(providerIssueHandoff, state, () => providerIssueHandoff.refresh(), {
+                        mode: 'refresh'
+                    }));
+                    const activeOutcome = {
+                        queued: true,
+                        coalesced: false
+                    };
+                    return acknowledgeAccepted
+                        ? acknowledgeProviderIssueHandoffAccepted(activeRefresh, activeOutcome)
+                        : mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, activeRefresh, activeOutcome);
+                }
+                noteProviderPollingRequest(providerIssueHandoff, {
+                    mode: 'refresh',
+                    queued: state.queuedRefresh !== null,
+                    replaceQueued: true,
+                    preserveActiveMode: true
+                });
+                return stuckOutcome;
+            })();
+        }
+        return continueWhileBusy();
+    }
+    const idleStuckError = buildProviderIssueHandoffRestartRequiredError(providerIssueHandoff);
+    if (idleStuckError && !allowIdleRestartRequiredRetry) {
+        clearProviderIssueHandoffOperationState(providerIssueHandoff, state);
+        return mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, Promise.reject(idleStuckError), {
+            queued: true,
+            coalesced: true
+        });
+    }
+    const activeRefresh = waitForProviderIssueHandoffPending(providerIssueHandoff, startProviderIssueHandoffOperation(providerIssueHandoff, state, () => providerIssueHandoff.refresh(), {
+        mode: 'refresh'
+    }));
+    const activeOutcome = {
+        queued: true,
+        coalesced: false
+    };
+    return acknowledgeAccepted
+        ? acknowledgeProviderIssueHandoffAccepted(activeRefresh, activeOutcome)
+        : mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, activeRefresh, activeOutcome);
+}
+export function runProviderIssueHandoffRehydrate(providerIssueHandoff) {
+    return runProviderIssueHandoffOperation(providerIssueHandoff, () => providerIssueHandoff.rehydrate());
+}
+export function runProviderIssueHandoffPoll(providerIssueHandoff, input, options) {
+    return runProviderIssueHandoffOperation(providerIssueHandoff, () => providerIssueHandoff.poll
+        ? providerIssueHandoff.poll(input)
+        : providerIssueHandoff.refresh(), options, {
+        mode: providerIssueHandoff.poll ? 'poll' : 'refresh'
+    });
+}
+function createProviderRefreshCoordinator(providerIssueHandoff, context) {
+    let stopped = false;
+    let timer = null;
+    let rescheduleGeneration = 0;
+    let lastSuccessfulFullRecoverySweepAtMs = null;
+    const clearScheduledTrigger = () => {
+        if (!timer) {
+            return;
+        }
+        clearTimeout(timer);
+        timer = null;
+    };
+    const scheduleNextTriggerAsync = async () => {
+        if (stopped || timer) {
+            return;
+        }
+        const schedule = await resolveProviderRefreshSchedule().catch(() => ({
+            interval_ms: PROVIDER_REFRESH_INTERVAL_MS,
+            reason: null,
+            linear_budget: null
+        }));
+        if (stopped || timer) {
+            return;
+        }
+        scheduleProviderPolling(providerIssueHandoff, {
+            intervalMs: schedule.interval_ms,
+            reason: schedule.reason,
+            linearBudget: schedule.linear_budget
+        });
+        timer = setTimeout(() => {
+            timer = null;
+            void trigger();
+        }, schedule.interval_ms);
+        timer.unref?.();
+    };
+    const resolveProviderRefreshSchedule = async () => resolveLinearPollingInterval({
+        budget: await readSharedLinearBudgetStatus(process.env, {
+            operation: 'dispatch_source_tracked_issues'
+        }).catch(() => null),
+        default_interval_ms: PROVIDER_REFRESH_INTERVAL_MS,
+        operation: 'dispatch_source_tracked_issues'
+    });
+    const resolveWatchdogDelayMs = () => resolveProviderIssueHandoffWatchdogDelayMs(providerIssueHandoff);
+    const shouldRunFullRecoverySweep = (nowMs) => lastSuccessfulFullRecoverySweepAtMs === null ||
+        nowMs - lastSuccessfulFullRecoverySweepAtMs >= PROVIDER_FULL_RECOVERY_SWEEP_INTERVAL_MS;
+    const trigger = async () => {
+        if (stopped) {
+            return;
+        }
+        const preflightSchedule = await resolveProviderRefreshSchedule().catch(() => null);
+        if (stopped) {
+            clearScheduledTrigger();
+            return;
+        }
+        if (preflightSchedule?.linear_budget?.cooldown_active) {
+            clearScheduledTrigger();
+            await scheduleNextTriggerAsync();
+            return;
+        }
+        if (isProviderPollingStuck(providerIssueHandoff)) {
+            await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff);
+            await scheduleNextTriggerAsync();
+            return;
+        }
+        clearScheduledTrigger();
+        const generation = ++rescheduleGeneration;
+        try {
+            const operation = runProviderIssueHandoffOperation(providerIssueHandoff, async () => {
+                if (!providerIssueHandoff.poll || !context.readFeatureToggles) {
+                    await providerIssueHandoff.refresh();
+                    return;
+                }
+                const refetchTrackedIssues = async (input) => await resolveProviderPollTrackedIssues(context, input);
+                if (shouldRunFullRecoverySweep(Date.now())) {
+                    const pollResolution = await refetchTrackedIssues({
+                        mode: 'recovery_sweep'
+                    });
+                    if (pollResolution.kind === 'ready') {
+                        await providerIssueHandoff.poll({
+                            trackedIssues: pollResolution.trackedIssues,
+                            refetchTrackedIssues,
+                            allowPollFailClosed: true
+                        });
+                        lastSuccessfulFullRecoverySweepAtMs = Date.now();
+                        return;
+                    }
+                    if (pollResolution.reason === 'dispatch_source_provider_rate_limited') {
+                        return;
+                    }
+                    noteProviderPollingRequest(providerIssueHandoff, {
+                        mode: 'refresh',
+                        queued: getProviderIssueHandoffOperationState(providerIssueHandoff).queuedRefresh !== null,
+                        replaceQueued: true
+                    });
+                    await providerIssueHandoff.refresh();
+                    return;
+                }
+                await providerIssueHandoff.poll({
+                    trackedIssues: [],
+                    refetchTrackedIssues,
+                    deferFreshDiscovery: true
+                });
+                return;
+            }, undefined, {
+                mode: providerIssueHandoff.poll && context.readFeatureToggles ? 'poll' : 'refresh'
+            });
+            await waitForProviderIssueHandoffPendingWithWatchdog(providerIssueHandoff, operation, resolveWatchdogDelayMs);
+        }
+        catch {
+            // Best-effort provider refreshes should not crash the public lifecycle.
+        }
+        await waitForProviderIssueHandoffQueueToDrain(providerIssueHandoff, resolveWatchdogDelayMs);
+        if (stopped || generation !== rescheduleGeneration) {
+            return;
+        }
+        await scheduleNextTriggerAsync();
+    };
+    return {
+        timer: {
+            cancel: () => {
+                stopped = true;
+                rescheduleGeneration += 1;
+                clearScheduledTrigger();
+            }
+        },
+        trigger
+    };
+}
+function scheduleStartupProviderRefresh(trigger) {
+    const startupTrigger = setTimeout(() => {
+        void trigger();
+    }, 0);
+    startupTrigger.unref?.();
+    return startupTrigger;
+}
+function resolveProviderIssueHandoffWatchdogDelayMs(providerIssueHandoff) {
+    const health = readProviderPollingHealth(providerIssueHandoff);
+    if (!health?.checking || health.operation_elapsed_ms === null) {
+        return PROVIDER_REFRESH_STUCK_AFTER_MS;
+    }
+    return Math.max(0, PROVIDER_REFRESH_STUCK_AFTER_MS - health.operation_elapsed_ms);
+}
+async function resolveProviderPollTrackedIssues(context, input) {
+    if (!context.readFeatureToggles) {
+        return {
+            kind: 'skip',
+            reason: 'dispatch_source_unavailable'
+        };
+    }
+    const sourceSetup = resolveLinearWebhookSourceSetup(context.readFeatureToggles(), process.env);
+    if ('error' in sourceSetup) {
+        return {
+            kind: 'skip',
+            reason: sourceSetup.error
+        };
+    }
+    const resolution = await resolveLiveLinearTrackedIssues({
+        sourceSetup: sourceSetup.sourceSetup,
+        env: process.env,
+        queryMode: input?.mode,
+        eligibleIssueTargetCount: input?.eligibleTargetCount,
+        eligibleStateSlotCounts: input?.eligibleStateSlotCounts,
+        excludedIssueIds: input?.excludedIssueIds
+    });
+    if (resolution.kind !== 'ready') {
+        return {
+            kind: 'skip',
+            reason: resolution.reason
+        };
+    }
+    return {
+        kind: 'ready',
+        trackedIssues: dedupeProviderPollTrackedIssues(resolution.tracked_issues)
+    };
+}
+function dedupeProviderPollTrackedIssues(trackedIssues) {
+    const seenIssueIds = new Set();
+    const deduped = [];
+    for (const trackedIssue of trackedIssues) {
+        if (seenIssueIds.has(trackedIssue.id)) {
+            continue;
+        }
+        seenIssueIds.add(trackedIssue.id);
+        deduped.push(trackedIssue);
+    }
+    return deduped;
+}
+function pickLatestTimestamp(currentIso, candidateIso) {
+    const currentMs = Date.parse(currentIso ?? '');
+    const candidateMs = Date.parse(candidateIso);
+    if (!Number.isFinite(currentMs)) {
+        return candidateIso;
+    }
+    if (!Number.isFinite(candidateMs)) {
+        return currentIso ?? candidateIso;
+    }
+    return candidateMs >= currentMs ? candidateIso : currentIso ?? candidateIso;
+}
+function runProviderIssueHandoffOperation(providerIssueHandoff, operation, options, healthContext) {
+    const state = getProviderIssueHandoffOperationState(providerIssueHandoff);
+    if (state.active) {
+        const continueWhileBusy = () => {
+            if (!options?.queueIfBusy) {
+                return waitForProviderIssueHandoffPending(providerIssueHandoff, state.active);
+            }
+            if (healthContext) {
+                noteProviderPollingRequest(providerIssueHandoff, {
+                    mode: healthContext.mode,
+                    queued: true,
+                    preserveActiveMode: true
+                });
+            }
+            return queueProviderIssueHandoffRefresh(providerIssueHandoff, state, operation, healthContext);
+        };
+        if (isProviderPollingStuck(providerIssueHandoff)) {
+            return (async () => {
+                const stuckOutcome = await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff);
+                if (!stuckOutcome) {
+                    return continueWhileBusy();
+                }
+                if (healthContext) {
+                    noteProviderPollingRequest(providerIssueHandoff, {
+                        mode: healthContext.mode,
+                        queued: state.queuedRefresh !== null,
+                        replaceQueued: true,
+                        preserveActiveMode: true
+                    });
+                }
+                throw new Error(stuckOutcome?.reason ?? 'provider_refresh_lifecycle_stuck');
+            })();
+        }
+        return continueWhileBusy();
+    }
+    const idleStuckError = buildProviderIssueHandoffRestartRequiredError(providerIssueHandoff);
+    if (idleStuckError) {
+        clearProviderIssueHandoffOperationState(providerIssueHandoff, state);
+        return Promise.reject(idleStuckError);
+    }
+    return waitForProviderIssueHandoffPending(providerIssueHandoff, startProviderIssueHandoffOperation(providerIssueHandoff, state, operation, healthContext));
+}
+function buildProviderIssueHandoffRestartRequiredError(providerIssueHandoff) {
+    if (!isProviderPollingStuck(providerIssueHandoff)) {
+        return null;
+    }
+    return new Error(readProviderPollingHealth(providerIssueHandoff)?.reason ?? 'provider_refresh_lifecycle_stuck');
+}
+function startProviderIssueHandoffOperation(providerIssueHandoff, state, operation, healthContext) {
+    resetProviderIssueHandoffStuckSignal(state);
+    if (healthContext) {
+        markProviderPollingStarted(providerIssueHandoff, {
+            mode: healthContext.mode
+        });
+    }
+    let operationResult;
+    try {
+        operationResult = operation();
+    }
+    catch (error) {
+        operationResult = Promise.reject(error);
+    }
+    const operationPromise = operationResult
+        .then((value) => {
+        if (healthContext && state.active === operationPromise) {
+            markProviderPollingCompleted(providerIssueHandoff);
+        }
+        return value;
+    }, (error) => {
+        if (healthContext && state.active === operationPromise) {
+            markProviderPollingCompleted(providerIssueHandoff, {
+                error
+            });
+        }
+        throw error;
+    })
+        .finally(() => {
+        if (state.active === operationPromise) {
+            state.active = null;
+            clearProviderIssueHandoffOperationState(providerIssueHandoff, state);
+        }
+    });
+    state.active = operationPromise;
+    return operationPromise;
+}
+function queueProviderIssueHandoffRefresh(providerIssueHandoff, state, operation, healthContext) {
+    if (state.queuedRefresh) {
+        return state.queuedRefresh;
+    }
+    const queuedRefresh = waitForProviderIssueHandoffPending(providerIssueHandoff, state.active)
+        .catch(async (error) => {
+        const stuckReason = resolveProviderIssueHandoffStuckErrorReason(error);
+        if (stuckReason) {
+            throw new Error(stuckReason);
+        }
+        if (await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff)) {
+            throw new Error(readProviderPollingHealth(providerIssueHandoff)?.reason ??
+                'provider_refresh_lifecycle_stuck');
+        }
+    })
+        .then(async () => {
+        if (await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff)) {
+            throw new Error(readProviderPollingHealth(providerIssueHandoff)?.reason ??
+                'provider_refresh_lifecycle_stuck');
+        }
+        if (state.queuedRefresh !== queuedRefresh) {
+            return;
+        }
+        state.queuedRefresh = null;
+        if (state.active) {
+            return queueProviderIssueHandoffRefresh(providerIssueHandoff, state, operation, healthContext);
+        }
+        return waitForProviderIssueHandoffPending(providerIssueHandoff, startProviderIssueHandoffOperation(providerIssueHandoff, state, operation, healthContext));
+    })
+        .finally(() => {
+        if (state.queuedRefresh === queuedRefresh) {
+            state.queuedRefresh = null;
+        }
+        clearProviderIssueHandoffOperationState(providerIssueHandoff, state);
+    });
+    state.queuedRefresh = queuedRefresh;
+    return queuedRefresh;
+}
+function detachProviderIssueHandoffPending(pending) {
+    if (!pending) {
+        return;
+    }
+    void pending.catch(() => undefined);
+}
+async function waitForProviderIssueHandoffQueueToDrain(providerIssueHandoff, resolveWatchdogDelayMs, options = {}) {
+    for (;;) {
+        const state = getProviderIssueHandoffOperationState(providerIssueHandoff);
+        const pending = state.active ?? state.queuedRefresh;
+        if (!pending) {
+            return;
+        }
+        if (await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff)) {
+            if (options.settleStuckPending) {
+                await settleProviderIssueHandoffStuckPending(providerIssueHandoff, state, pending, options);
+                continue;
+            }
+            return;
+        }
+        try {
+            await waitForProviderIssueHandoffPendingWithWatchdog(providerIssueHandoff, pending, resolveWatchdogDelayMs);
+        }
+        catch {
+            if (await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff)) {
+                if (options.settleStuckPending) {
+                    await settleProviderIssueHandoffStuckPending(providerIssueHandoff, state, pending, options);
+                    continue;
+                }
+                return;
+            }
+        }
+    }
+}
+async function settleProviderIssueHandoffStuckPending(providerIssueHandoff, state, pending, options) {
+    let timeout = null;
+    const graceMs = Math.max(0, options.stuckPendingGraceMs ?? PROVIDER_CLOSE_STUCK_DRAIN_GRACE_MS);
+    const outcome = await Promise.race([
+        pending.then(() => 'settled', () => 'settled'),
+        new Promise((resolve) => {
+            timeout = setTimeout(() => resolve('timed_out'), graceMs);
+            timeout.unref?.();
+        })
+    ]);
+    if (timeout) {
+        clearTimeout(timeout);
+    }
+    if (outcome === 'settled') {
+        return;
+    }
+    detachProviderIssueHandoffPending(pending);
+    providerIssueHandoff.resetStuckRefreshLifecycle?.();
+    if (state.active === pending) {
+        state.active = null;
+    }
+    if (state.queuedRefresh === pending) {
+        state.queuedRefresh = null;
+    }
+    clearProviderIssueHandoffOperationState(providerIssueHandoff, state);
+}
+function getProviderIssueHandoffOperationState(providerIssueHandoff) {
+    const existingState = providerIssueHandoffOperations.get(providerIssueHandoff);
+    if (existingState) {
+        return existingState;
+    }
+    const nextState = {
+        active: null,
+        queuedRefresh: null,
+        ...createProviderIssueHandoffStuckSignal()
+    };
+    providerIssueHandoffOperations.set(providerIssueHandoff, nextState);
+    return nextState;
+}
+function clearProviderIssueHandoffOperationState(providerIssueHandoff, state) {
+    if (!state.active && !state.queuedRefresh) {
+        providerIssueHandoffOperations.delete(providerIssueHandoff);
+    }
+}
+async function resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff) {
+    if (!isProviderPollingStuck(providerIssueHandoff)) {
+        return null;
+    }
+    await markProviderPollingStuck(providerIssueHandoff);
+    const outcome = {
+        queued: true,
+        coalesced: true,
+        stuck: true,
+        restart_required: true,
+        reason: readProviderPollingHealth(providerIssueHandoff)?.reason ?? 'provider_refresh_lifecycle_stuck'
+    };
+    signalProviderIssueHandoffStuck(providerIssueHandoff, outcome);
+    return outcome;
+}
+function mapProviderIssueHandoffRefreshOutcome(providerIssueHandoff, pending, successOutcome) {
+    return pending.then(() => successOutcome, async (error) => {
+        const stuckOutcome = await resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff);
+        if (stuckOutcome) {
+            return stuckOutcome;
+        }
+        const stuckReason = resolveProviderIssueHandoffStuckErrorReason(error);
+        if (stuckReason) {
+            return {
+                queued: true,
+                coalesced: true,
+                stuck: true,
+                restart_required: true,
+                reason: stuckReason
+            };
+        }
+        throw error;
+    });
+}
+function resolveProviderIssueHandoffStuckErrorReason(error) {
+    if (!(error instanceof Error)) {
+        return null;
+    }
+    if (error.name === 'ProviderRefreshLifecycleStuckError' ||
+        error.message === 'provider_refresh_lifecycle_stuck') {
+        return 'provider_refresh_lifecycle_stuck';
+    }
+    if (error.name === 'ProviderPollLifecycleStuckError' ||
+        error.message === 'provider_poll_lifecycle_stuck') {
+        return 'provider_poll_lifecycle_stuck';
+    }
+    return null;
+}
+function acknowledgeProviderIssueHandoffAccepted(pending, successOutcome) {
+    // Public refresh routes return as soon as the lifecycle accepts the work, so
+    // keep the detached refresh promise from surfacing later failures as
+    // unhandled rejections.
+    void pending.catch(() => undefined);
+    return Promise.resolve(successOutcome);
+}
+function waitForProviderIssueHandoffPending(providerIssueHandoff, pending) {
+    const state = getProviderIssueHandoffOperationState(providerIssueHandoff);
+    return Promise.race([
+        pending,
+        state.stuckSignal.then((outcome) => {
+            throw new Error(outcome.reason ?? 'provider_refresh_lifecycle_stuck');
+        })
+    ]);
+}
+async function waitForProviderIssueHandoffPendingWithWatchdog(providerIssueHandoff, pending, resolveWatchdogDelayMs) {
+    let stuckWatchdog = null;
+    try {
+        await Promise.race([
+            waitForProviderIssueHandoffPending(providerIssueHandoff, pending),
+            new Promise((resolve) => {
+                const watchdogDelayMs = resolveWatchdogDelayMs();
+                stuckWatchdog = setTimeout(() => {
+                    void resolveProviderIssueHandoffStuckOutcome(providerIssueHandoff).finally(resolve);
+                }, watchdogDelayMs);
+                stuckWatchdog.unref?.();
+            })
+        ]);
+    }
+    finally {
+        if (stuckWatchdog) {
+            clearTimeout(stuckWatchdog);
+        }
+    }
+}
+function createProviderIssueHandoffStuckSignal() {
+    let resolveStuckSignal = null;
+    const stuckSignal = new Promise((resolve) => {
+        resolveStuckSignal = resolve;
+    });
+    return {
+        stuckSignal,
+        resolveStuckSignal
+    };
+}
+function resetProviderIssueHandoffStuckSignal(state) {
+    const nextSignal = createProviderIssueHandoffStuckSignal();
+    state.stuckSignal = nextSignal.stuckSignal;
+    state.resolveStuckSignal = nextSignal.resolveStuckSignal;
+}
+function signalProviderIssueHandoffStuck(providerIssueHandoff, outcome) {
+    const state = providerIssueHandoffOperations.get(providerIssueHandoff);
+    if (!state?.resolveStuckSignal) {
+        return;
+    }
+    state.resolveStuckSignal(outcome);
+    state.resolveStuckSignal = null;
+}