@kbediako/codex-orchestrator 0.1.38 → 0.2.1

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

@@ -0,0 +1,1789 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { acquireLockWithRetry } from '../../persistence/lockFile.js';
+import { writeJsonAtomic } from '../utils/fs.js';
+import { resolveCodexOrchestratorHome } from '../utils/codexPaths.js';
+import { resolveLinearApiTokenFingerprint, resolveLinearRequestTimeoutMs } from './linearGraphqlClient.js';
+import { extractLinearRateLimitDetailsFromHeaders } from './linearRateLimit.js';
+const LINEAR_BUDGET_STATE_SCHEMA_VERSION = 2;
+const LINEAR_BUDGET_ALIAS_SCHEMA_VERSION = 1;
+const LINEAR_BUDGET_STATE_DIRNAME = 'linear-budget';
+const LINEAR_BUDGET_SCOPE_DIRNAME = 'scopes';
+const LINEAR_BUDGET_ALIAS_DIRNAME = 'aliases';
+const LINEAR_BUDGET_DEFAULT_CONSTRAINED_POLL_INTERVAL_MS = 30_000;
+const LINEAR_BUDGET_DEFAULT_LOW_POLL_INTERVAL_MS = 60_000;
+const LINEAR_BUDGET_DEFAULT_ENDPOINT_CONSTRAINED_POLL_INTERVAL_MS = 45_000;
+const LINEAR_BUDGET_DEFAULT_ENDPOINT_LOW_POLL_INTERVAL_MS = 90_000;
+const LINEAR_BUDGET_REQUEST_HEADROOM_RESERVE_RATIO = 0.01;
+const LINEAR_BUDGET_REQUEST_HEADROOM_RESERVE_MAX = 50;
+const LINEAR_BUDGET_ENDPOINT_REQUEST_HEADROOM_RESERVE_RATIO = 0.05;
+const LINEAR_BUDGET_ENDPOINT_REQUEST_HEADROOM_RESERVE_MAX = 5;
+const LINEAR_BUDGET_REQUEST_BURN_HISTORY_LIMIT = 64;
+const LINEAR_BUDGET_UNKNOWN_RESET_EXHAUSTED_GRACE_MS = LINEAR_BUDGET_DEFAULT_LOW_POLL_INTERVAL_MS;
+const LINEAR_BUDGET_LOCK_RETRY = {
+    maxAttempts: 25,
+    initialDelayMs: 10,
+    backoffFactor: 1.5,
+    maxDelayMs: 250,
+    staleMs: 30_000
+};
+const LINEAR_BUDGET_RESERVATION_DEFAULT_TTL_GRACE_MS = 5_000;
+const LINEAR_BUDGET_POLL_JITTER_RATIO = 0.1;
+const LINEAR_BUDGET_POLL_JITTER_MAX_MS = 10_000;
+export async function readSharedLinearBudgetStatus(env = process.env, options = {}) {
+    const paths = resolveLinearBudgetStatePaths(env);
+    if (!paths) {
+        return null;
+    }
+    const persisted = await readNewestPersistedLinearBudgetStatus(paths, null);
+    return persisted ? hydrateLinearBudgetStatus(persisted, options) : null;
+}
+export async function recordLinearBudgetHeadersObservation(input) {
+    const details = extractLinearRateLimitDetailsFromHeaders(input.headers);
+    if (!hasRecordableLinearBudgetDetails(details)) {
+        return await readSharedLinearBudgetStatus(input.env ?? process.env);
+    }
+    return await recordLinearBudgetObservation({
+        env: input.env,
+        source: input.source,
+        details,
+        observedAt: input.observedAt,
+        scope: input.scope,
+        assumeUnknownResetsExhausted: false
+    });
+}
+export async function recordLinearBudgetRateLimitObservation(input) {
+    if (!hasRecordableLinearBudgetDetails(input.rateLimit.details)) {
+        return await readSharedLinearBudgetStatus(input.env ?? process.env);
+    }
+    return await recordLinearBudgetObservation({
+        env: input.env,
+        source: input.source,
+        details: input.rateLimit.details,
+        observedAt: input.observedAt,
+        scope: input.scope,
+        assumeUnknownResetsExhausted: true
+    });
+}
+export function resolveLinearBudgetPreflight(input) {
+    const budget = input.budget;
+    if (!budget) {
+        return { ok: true };
+    }
+    const minimumRequestsRemaining = normalizePositiveInteger(input.minimum_requests_remaining) ?? 1;
+    const inferredComplexityFloor = normalizePositiveInteger(input.minimum_complexity_remaining) ?? inferOperationComplexityFloor(budget.request_complexity, minimumRequestsRemaining);
+    const details = buildSharedLinearRateLimitDetails(budget, {
+        shared_budget_fail_fast: true,
+        operation: input.operation,
+        ...(input.allow_below_request_reserve === true
+            ? {
+                shared_budget_request_headroom_override: 'allow_below_request_reserve'
+            }
+            : {})
+    });
+    if (budget.cooldown_active) {
+        return {
+            ok: false,
+            error: {
+                code: 'linear_rate_limited',
+                message: 'Linear shared budget cooldown is active.',
+                status: 429,
+                retryable: true,
+                details
+            }
+        };
+    }
+    const requestShortfall = resolveBucketShortfall([
+        ['requests', budget.requests],
+        ['endpoint_requests', budget.endpoint_requests]
+    ], minimumRequestsRemaining);
+    if (requestShortfall) {
+        return {
+            ok: false,
+            error: {
+                code: 'linear_rate_limited',
+                message: `Linear shared budget is insufficient for ${input.operation}.`,
+                status: 429,
+                retryable: true,
+                details: {
+                    ...details,
+                    required_requests_remaining: minimumRequestsRemaining,
+                    shortfall_bucket: requestShortfall.bucket,
+                    shortfall_remaining: requestShortfall.remaining
+                }
+            }
+        };
+    }
+    if (inferredComplexityFloor !== null) {
+        const complexityShortfall = resolveBucketShortfall([
+            ['complexity', budget.complexity],
+            ['endpoint_complexity', budget.endpoint_complexity]
+        ], inferredComplexityFloor);
+        if (complexityShortfall) {
+            return {
+                ok: false,
+                error: {
+                    code: 'linear_rate_limited',
+                    message: `Linear shared complexity budget is insufficient for ${input.operation}.`,
+                    status: 429,
+                    retryable: true,
+                    details: {
+                        ...details,
+                        required_complexity_remaining: inferredComplexityFloor,
+                        shortfall_bucket: complexityShortfall.bucket,
+                        shortfall_remaining: complexityShortfall.remaining
+                    }
+                }
+            };
+        }
+    }
+    if (input.allow_below_request_reserve !== true) {
+        const requestReserveShortfall = resolveRequestReserveShortfall([
+            ['requests', budget.requests],
+            ['endpoint_requests', budget.endpoint_requests]
+        ], minimumRequestsRemaining);
+        if (requestReserveShortfall) {
+            return {
+                ok: false,
+                error: {
+                    code: 'linear_rate_limited',
+                    message: `Linear shared request headroom reserve is insufficient for ${input.operation}.`,
+                    status: 429,
+                    retryable: true,
+                    details: {
+                        ...details,
+                        required_requests_remaining: minimumRequestsRemaining,
+                        request_headroom_reserve_bucket: requestReserveShortfall.bucket,
+                        request_headroom_remaining: requestReserveShortfall.remaining,
+                        request_headroom_reserve: requestReserveShortfall.reserve,
+                        request_headroom_usable_remaining: Math.max(0, requestReserveShortfall.usable_remaining)
+                    }
+                }
+            };
+        }
+    }
+    const exhaustedBucket = findExhaustedLinearBudgetBucket(budget);
+    if (exhaustedBucket) {
+        return {
+            ok: false,
+            error: {
+                code: 'linear_rate_limited',
+                message: 'Linear shared budget is exhausted.',
+                status: 429,
+                retryable: true,
+                details: {
+                    ...details,
+                    exhausted_bucket: exhaustedBucket
+                }
+            }
+        };
+    }
+    return { ok: true };
+}
+export async function reserveLinearBudgetReservation(input) {
+    const env = input.env ?? process.env;
+    const paths = resolveLinearBudgetStatePaths(env);
+    if (!paths) {
+        return {
+            ok: true,
+            budget: null,
+            reservation: null
+        };
+    }
+    const requestUnits = normalizePositiveInteger(input.request_units) ?? 1;
+    const reservationTtlMs = normalizePositiveInteger(input.ttl_ms) ??
+        resolveLinearRequestTimeoutMs(env) + LINEAR_BUDGET_RESERVATION_DEFAULT_TTL_GRACE_MS;
+    const lockScopeKey = await resolveLinearBudgetLockScopeKey(paths);
+    return await withLinearBudgetStateLock(paths, async () => {
+        const persisted = await readNewestPersistedLinearBudgetStatus(paths, null);
+        if (!persisted) {
+            return {
+                ok: true,
+                budget: null,
+                reservation: null
+            };
+        }
+        const cleanedPersisted = pruneExpiredReservations(persisted);
+        const selectedBudget = hydrateLinearBudgetStatus(cleanedPersisted, {
+            operation: input.operation
+        });
+        const inferredComplexityFloor = normalizePositiveInteger(input.minimum_complexity_remaining) ??
+            inferOperationComplexityFloor(selectedBudget.request_complexity, requestUnits);
+        const preflight = resolveLinearBudgetPreflight({
+            budget: selectedBudget,
+            operation: input.operation,
+            minimum_requests_remaining: normalizePositiveInteger(input.minimum_requests_remaining) ?? requestUnits,
+            minimum_complexity_remaining: inferredComplexityFloor,
+            allow_below_request_reserve: input.allow_below_request_reserve === true
+        });
+        if (!preflight.ok) {
+            return {
+                ok: false,
+                error: preflight.error
+            };
+        }
+        const shouldReserve = selectedBudget.requests !== null ||
+            selectedBudget.complexity !== null ||
+            selectedBudget.endpoint_requests !== null ||
+            selectedBudget.endpoint_complexity !== null;
+        if (!shouldReserve) {
+            if (cleanedPersisted !== persisted) {
+                await writePersistedLinearBudgetStatus(paths, cleanedPersisted);
+            }
+            return {
+                ok: true,
+                budget: selectedBudget,
+                reservation: null
+            };
+        }
+        const expiresAt = new Date(Date.now() + reservationTtlMs).toISOString();
+        const reservationRecord = {
+            id: randomUUID(),
+            operation: input.operation,
+            endpoint_key: selectedBudget.selected_endpoint_key,
+            requests: requestUnits,
+            complexity: inferredComplexityFloor,
+            created_at: new Date().toISOString(),
+            expires_at: expiresAt
+        };
+        const nextPersisted = {
+            ...cleanedPersisted,
+            reservations: [...cleanedPersisted.reservations, reservationRecord]
+        };
+        await writePersistedLinearBudgetStatus(paths, nextPersisted);
+        const hydrated = hydrateLinearBudgetStatus(nextPersisted, {
+            operation: input.operation
+        });
+        return {
+            ok: true,
+            budget: hydrated,
+            reservation: {
+                id: reservationRecord.id,
+                endpoint_key: reservationRecord.endpoint_key,
+                endpoint_name: hydrated.endpoint_name,
+                requests: reservationRecord.requests,
+                complexity: reservationRecord.complexity,
+                release: async () => {
+                    await releaseLinearBudgetReservation({
+                        env,
+                        reservationId: reservationRecord.id
+                    });
+                }
+            }
+        };
+    }, lockScopeKey);
+}
+export async function releaseLinearBudgetReservation(input) {
+    const reservationId = normalizeOptionalString(input.reservationId);
+    if (!reservationId) {
+        return;
+    }
+    const env = input.env ?? process.env;
+    const paths = resolveLinearBudgetStatePaths(env);
+    if (!paths) {
+        return;
+    }
+    const lockScopeKey = await resolveLinearBudgetLockScopeKey(paths);
+    await withLinearBudgetStateLock(paths, async () => {
+        const persisted = await readNewestPersistedLinearBudgetStatus(paths, null);
+        if (!persisted) {
+            return;
+        }
+        const nextReservations = persisted.reservations.filter((entry) => entry.id !== reservationId);
+        if (nextReservations.length === persisted.reservations.length) {
+            return;
+        }
+        await writePersistedLinearBudgetStatus(paths, {
+            ...persisted,
+            reservations: nextReservations
+        });
+    }, lockScopeKey);
+}
+export function resolveLinearPollingInterval(input) {
+    const budget = input.budget;
+    if (!budget) {
+        return {
+            interval_ms: input.default_interval_ms,
+            reason: null,
+            linear_budget: null
+        };
+    }
+    const nowMs = input.nowMs ?? Date.now();
+    if (budget.cooldown_active) {
+        const cooldownUntilMs = parseIsoToMs(budget.cooldown_until);
+        const cooldownWaitMs = cooldownUntilMs === null ? input.default_interval_ms : Math.max(0, cooldownUntilMs - nowMs);
+        return {
+            interval_ms: Math.max(input.default_interval_ms, cooldownWaitMs),
+            reason: budget.suppression_reason ?? 'linear_budget_shared_cooldown',
+            linear_budget: budget
+        };
+    }
+    const pressure = resolveMaterializedBudgetPressure(budget);
+    const requestHeadroomGuard = resolveRequestPollingHeadroomGuard({
+        budget,
+        defaultIntervalMs: input.default_interval_ms,
+        nowMs
+    });
+    if (pressure.suppression === 'none') {
+        if (requestHeadroomGuard) {
+            const intervalMs = applyDeterministicPositiveJitter(requestHeadroomGuard.interval_ms, `${requestHeadroomGuard.reason}|${budget.selected_endpoint_key ?? 'global'}|${budget.observed_at}`, nowMs);
+            return {
+                interval_ms: intervalMs,
+                reason: requestHeadroomGuard.reason,
+                linear_budget: {
+                    ...budget,
+                    suppression: requestHeadroomGuard.suppression,
+                    suppression_reason: requestHeadroomGuard.reason
+                }
+            };
+        }
+        return {
+            interval_ms: input.default_interval_ms,
+            reason: null,
+            linear_budget: budget
+        };
+    }
+    let baseIntervalMs = input.default_interval_ms;
+    if (pressure.suppression === 'constrained') {
+        baseIntervalMs = Math.max(input.default_interval_ms, pressure.endpoint_specific
+            ? LINEAR_BUDGET_DEFAULT_ENDPOINT_CONSTRAINED_POLL_INTERVAL_MS
+            : LINEAR_BUDGET_DEFAULT_CONSTRAINED_POLL_INTERVAL_MS);
+    }
+    else {
+        baseIntervalMs = Math.max(input.default_interval_ms, pressure.endpoint_specific
+            ? LINEAR_BUDGET_DEFAULT_ENDPOINT_LOW_POLL_INTERVAL_MS
+            : LINEAR_BUDGET_DEFAULT_LOW_POLL_INTERVAL_MS);
+    }
+    let reason = pressure.reason;
+    let suppression = pressure.suppression;
+    if (requestHeadroomGuard && requestHeadroomGuard.interval_ms > baseIntervalMs) {
+        baseIntervalMs = requestHeadroomGuard.interval_ms;
+        if (reason === null ||
+            reason.startsWith('linear_budget_requests_') ||
+            reason.startsWith('linear_budget_endpoint_requests_')) {
+            reason = requestHeadroomGuard.reason;
+            suppression = requestHeadroomGuard.suppression;
+        }
+    }
+    const intervalMs = applyDeterministicPositiveJitter(baseIntervalMs, `${reason ?? 'linear_budget'}|${budget.selected_endpoint_key ?? 'global'}|${budget.observed_at}`, nowMs);
+    return {
+        interval_ms: intervalMs,
+        reason,
+        linear_budget: {
+            ...budget,
+            suppression,
+            suppression_reason: reason
+        }
+    };
+}
+export function buildSharedLinearRateLimitDetails(budget, extraDetails = {}) {
+    return {
+        ...(budget.retry_after_seconds !== null ? { retry_after_seconds: budget.retry_after_seconds } : {}),
+        ...(budget.request_id ? { request_id: budget.request_id } : {}),
+        ...(budget.cooldown_until ? { shared_budget_cooldown_until: budget.cooldown_until } : {}),
+        shared_budget_observed_at: budget.observed_at,
+        shared_budget_source: budget.source,
+        shared_budget_cooldown_active: budget.cooldown_active,
+        shared_budget_suppression: budget.suppression,
+        shared_budget_scope_kind: budget.scope_kind,
+        shared_budget_scope_key: budget.scope_key,
+        ...(budget.viewer_id ? { shared_budget_viewer_id: budget.viewer_id } : {}),
+        ...(budget.workspace_id ? { shared_budget_workspace_id: budget.workspace_id } : {}),
+        ...(budget.suppression_reason ? { shared_budget_suppression_reason: budget.suppression_reason } : {}),
+        ...(budget.endpoint_name ? { endpoint_name: budget.endpoint_name } : {}),
+        ...(budget.selected_endpoint_key ? { selected_endpoint_key: budget.selected_endpoint_key } : {}),
+        ...(budget.request_complexity !== null ? { request_complexity: budget.request_complexity } : {}),
+        ...(budget.reservations_active > 0 ? { shared_budget_reservations_active: budget.reservations_active } : {}),
+        ...serializeLinearBudgetBucketDetails('requests', budget.requests),
+        ...serializeLinearBudgetBucketDetails('endpoint_requests', budget.endpoint_requests),
+        ...serializeLinearBudgetBucketDetails('complexity', budget.complexity),
+        ...serializeLinearBudgetBucketDetails('endpoint_complexity', budget.endpoint_complexity),
+        ...extraDetails
+    };
+}
+async function recordLinearBudgetObservation(input) {
+    const env = input.env ?? process.env;
+    const paths = resolveLinearBudgetStatePaths(env);
+    if (!paths) {
+        return null;
+    }
+    const observedAt = normalizeOptionalString(input.observedAt) ?? new Date().toISOString();
+    const observation = buildLinearBudgetObservation({
+        details: input.details,
+        source: input.source,
+        observedAt,
+        assumeUnknownResetsExhausted: input.assumeUnknownResetsExhausted
+    });
+    const lockScopeKey = await resolveLinearBudgetLockScopeKey(paths, input.scope);
+    return await withLinearBudgetStateLock(paths, async () => {
+        const existing = await readNewestPersistedLinearBudgetStatus(paths, normalizeScopeHint(input.scope));
+        const scope = await resolveWriteScope(paths, input.scope, existing);
+        const staleObservation = isStalePersistedLinearBudgetObservation(existing, observation);
+        const mergedWithoutHistory = mergePersistedLinearBudgetStatus(existing, observation, scope);
+        const merged = appendPersistedLinearBudgetRequestBurnHistory(mergedWithoutHistory, staleObservation
+            ? null
+            : buildPersistedLinearBudgetRequestBurnHistoryEntry({
+                env,
+                existing,
+                observation,
+                merged: mergedWithoutHistory
+            }));
+        await writePersistedLinearBudgetStatus(paths, merged);
+        if (scope.kind === 'user') {
+            await writePersistedLinearBudgetAlias(paths, scope);
+        }
+        return hydrateLinearBudgetStatus(merged);
+    }, lockScopeKey);
+}
+function buildLinearBudgetObservation(input) {
+    const requests = parseLinearBudgetBucket(input.details, 'requests');
+    const complexity = parseLinearBudgetBucket(input.details, 'complexity');
+    const requestComplexity = parseNumberLike(input.details.request_complexity);
+    const endpointObservation = buildLinearBudgetEndpointObservation({
+        details: input.details,
+        source: input.source,
+        observedAt: input.observedAt,
+        assumeUnknownResetsExhausted: input.assumeUnknownResetsExhausted
+    });
+    return {
+        observed_at: input.observedAt,
+        source: input.source,
+        request_id: normalizeOptionalString(input.details.request_id),
+        retry_after_seconds: parseNumberLike(input.details.retry_after_seconds),
+        requests,
+        complexity,
+        request_complexity: requestComplexity,
+        endpoint: endpointObservation,
+        assume_unknown_resets_exhausted: input.assumeUnknownResetsExhausted
+    };
+}
+function buildLinearBudgetEndpointObservation(input) {
+    const endpointName = normalizeOptionalString(input.details.endpoint_name);
+    const requests = parseLinearBudgetBucket(input.details, 'endpoint_requests');
+    const complexity = parseLinearBudgetBucket(input.details, 'endpoint_complexity');
+    const requestComplexity = parseNumberLike(input.details.request_complexity);
+    if (!endpointName && !requests && !complexity && requestComplexity === null) {
+        return null;
+    }
+    return {
+        key: buildEndpointKey(endpointName, input.source),
+        endpoint_name: endpointName,
+        aliases: [input.source],
+        observed_at: input.observedAt,
+        requests,
+        complexity,
+        request_complexity: requestComplexity,
+        assume_unknown_resets_exhausted: input.assumeUnknownResetsExhausted
+    };
+}
+function mergePersistedLinearBudgetStatus(existing, observation, scope) {
+    if (isStalePersistedLinearBudgetObservation(existing, observation)) {
+        return adoptPersistedScope(existing, scope);
+    }
+    const base = existing ? adoptPersistedScope(pruneExpiredReservations(existing), scope) : createEmptyPersistedLinearBudgetStatus(scope);
+    const endpoints = clonePersistedEndpoints(base.endpoints);
+    let selectedEndpointKey = base.selected_endpoint_key;
+    if (observation.endpoint) {
+        const upsertedEndpoint = upsertPersistedEndpointObservation(endpoints, observation.endpoint);
+        selectedEndpointKey = upsertedEndpoint.selectedEndpointKey;
+    }
+    const merged = {
+        ...base,
+        observed_at: observation.observed_at,
+        source: observation.source,
+        request_id: observation.request_id,
+        retry_after_seconds: observation.retry_after_seconds,
+        requests: mergeLinearBudgetBucket(base.requests, observation.requests),
+        complexity: mergeLinearBudgetBucket(base.complexity, observation.complexity),
+        request_complexity: observation.request_complexity ?? base.request_complexity,
+        selected_endpoint_key: selectedEndpointKey,
+        endpoints,
+        reservations: base.reservations
+    };
+    merged.cooldown_until = resolveCooldownUntil({
+        persisted: merged,
+        observation
+    });
+    return merged;
+}
+function isStalePersistedLinearBudgetObservation(existing, observation) {
+    const existingObservedAtMs = existing ? parseIsoToMs(existing.observed_at) : null;
+    const observationObservedAtMs = parseIsoToMs(observation.observed_at);
+    return (existing !== null &&
+        existingObservedAtMs !== null &&
+        observationObservedAtMs !== null &&
+        observationObservedAtMs < existingObservedAtMs);
+}
+function createEmptyPersistedLinearBudgetStatus(scope) {
+    return {
+        schema_version: LINEAR_BUDGET_STATE_SCHEMA_VERSION,
+        scope_kind: scope.kind,
+        scope_key: scope.key,
+        viewer_id: scope.viewer_id,
+        workspace_id: scope.workspace_id,
+        token_fingerprints: [scope.token_fingerprint],
+        observed_at: new Date().toISOString(),
+        source: 'unknown',
+        request_id: null,
+        retry_after_seconds: null,
+        cooldown_until: null,
+        requests: null,
+        complexity: null,
+        request_complexity: null,
+        selected_endpoint_key: null,
+        endpoints: {},
+        reservations: [],
+        request_burn_history: []
+    };
+}
+function adoptPersistedScope(persisted, scope) {
+    return {
+        ...persisted,
+        scope_kind: scope.kind,
+        scope_key: scope.key,
+        viewer_id: scope.viewer_id ?? persisted.viewer_id,
+        workspace_id: scope.workspace_id ?? persisted.workspace_id,
+        token_fingerprints: uniqueStrings([...persisted.token_fingerprints, scope.token_fingerprint])
+    };
+}
+function clonePersistedLinearBudgetStatus(value) {
+    return {
+        ...value,
+        token_fingerprints: [...value.token_fingerprints],
+        requests: cloneBucket(value.requests),
+        complexity: cloneBucket(value.complexity),
+        endpoints: clonePersistedEndpoints(value.endpoints),
+        reservations: value.reservations.map((entry) => ({ ...entry })),
+        request_burn_history: clonePersistedLinearBudgetRequestBurnHistory(value.request_burn_history)
+    };
+}
+function clonePersistedEndpoints(value) {
+    return Object.fromEntries(Object.entries(value).map(([key, endpoint]) => [
+        key,
+        {
+            endpoint_name: endpoint.endpoint_name,
+            aliases: [...endpoint.aliases],
+            observed_at: endpoint.observed_at,
+            requests: cloneBucket(endpoint.requests),
+            complexity: cloneBucket(endpoint.complexity),
+            request_complexity: endpoint.request_complexity
+        }
+    ]));
+}
+function upsertPersistedEndpointObservation(endpoints, observation) {
+    const targetKey = resolvePersistedEndpointTargetKey(endpoints, observation);
+    const existing = endpoints[targetKey] ?? null;
+    const merged = {
+        endpoint_name: observation.endpoint_name ?? existing?.endpoint_name ?? null,
+        aliases: uniqueStrings([...(existing?.aliases ?? []), ...observation.aliases]),
+        observed_at: maxIsoTimestamp(existing?.observed_at ?? null, observation.observed_at) ?? observation.observed_at,
+        requests: mergeLinearBudgetBucket(existing?.requests ?? null, observation.requests),
+        complexity: mergeLinearBudgetBucket(existing?.complexity ?? null, observation.complexity),
+        request_complexity: observation.request_complexity ?? existing?.request_complexity ?? null
+    };
+    for (const [key, endpoint] of Object.entries(endpoints)) {
+        if (key === targetKey) {
+            continue;
+        }
+        if ((observation.endpoint_name && endpoint.endpoint_name === observation.endpoint_name) ||
+            endpoint.aliases.some((alias) => observation.aliases.includes(alias))) {
+            merged.aliases = uniqueStrings([...merged.aliases, ...endpoint.aliases]);
+            merged.requests = mergeLinearBudgetBucket(merged.requests, endpoint.requests);
+            merged.complexity = mergeLinearBudgetBucket(merged.complexity, endpoint.complexity);
+            merged.request_complexity = merged.request_complexity ?? endpoint.request_complexity ?? null;
+            merged.observed_at = maxIsoTimestamp(merged.observed_at, endpoint.observed_at) ?? merged.observed_at;
+            delete endpoints[key];
+        }
+    }
+    endpoints[targetKey] = merged;
+    return {
+        selectedEndpointKey: targetKey
+    };
+}
+function resolvePersistedEndpointTargetKey(endpoints, observation) {
+    if (endpoints[observation.key]) {
+        return observation.key;
+    }
+    if (observation.endpoint_name) {
+        for (const [key, endpoint] of Object.entries(endpoints)) {
+            if (endpoint.endpoint_name === observation.endpoint_name) {
+                return key;
+            }
+        }
+    }
+    for (const [key, endpoint] of Object.entries(endpoints)) {
+        if (endpoint.aliases.some((alias) => observation.aliases.includes(alias))) {
+            return observation.endpoint_name ? buildEndpointKey(observation.endpoint_name, observation.aliases[0] ?? key) : key;
+        }
+    }
+    return observation.key;
+}
+function mergePersistedLinearBudgetReservations(existing, candidate) {
+    if (candidate.scope_kind === 'user') {
+        return clonePersistedLinearBudgetReservations(candidate.reservations);
+    }
+    if (existing.scope_kind === 'user') {
+        return clonePersistedLinearBudgetReservations(existing.reservations);
+    }
+    return clonePersistedLinearBudgetReservations(candidate.reservations);
+}
+function comparePersistedReservationCreatedAt(left, right) {
+    const leftCreatedAtMs = parseIsoToMs(left.created_at) ?? Number.NEGATIVE_INFINITY;
+    const rightCreatedAtMs = parseIsoToMs(right.created_at) ?? Number.NEGATIVE_INFINITY;
+    return leftCreatedAtMs - rightCreatedAtMs;
+}
+function clonePersistedLinearBudgetReservations(value) {
+    return value.map((entry) => ({ ...entry })).sort(comparePersistedReservationCreatedAt);
+}
+function clonePersistedLinearBudgetRequestBurnHistory(value) {
+    return [...(value ?? [])]
+        .map((entry) => ({ ...entry }))
+        .sort(comparePersistedLinearBudgetRequestBurnHistoryEntry);
+}
+function comparePersistedLinearBudgetRequestBurnHistoryEntry(left, right) {
+    const leftRecordedAtMs = parseIsoToMs(left.recorded_at) ?? parseIsoToMs(left.observed_at) ?? Number.NEGATIVE_INFINITY;
+    const rightRecordedAtMs = parseIsoToMs(right.recorded_at) ?? parseIsoToMs(right.observed_at) ?? Number.NEGATIVE_INFINITY;
+    return leftRecordedAtMs - rightRecordedAtMs;
+}
+function mergePersistedLinearBudgetRequestBurnHistory(existing, candidate) {
+    const deduped = new Map();
+    for (const entry of [...(existing ?? []), ...(candidate ?? [])]) {
+        const key = [
+            entry.recorded_at,
+            entry.observed_at,
+            entry.source,
+            entry.request_id ?? '',
+            entry.request_bucket ?? '',
+            entry.remaining ?? '',
+            entry.reset_at ?? ''
+        ].join('|');
+        deduped.set(key, { ...entry });
+    }
+    return [...deduped.values()]
+        .sort(comparePersistedLinearBudgetRequestBurnHistoryEntry)
+        .slice(-LINEAR_BUDGET_REQUEST_BURN_HISTORY_LIMIT);
+}
+function appendPersistedLinearBudgetRequestBurnHistory(persisted, entry) {
+    if (!entry) {
+        return persisted;
+    }
+    const requestBurnHistory = mergePersistedLinearBudgetRequestBurnHistory(persisted.request_burn_history, [entry]);
+    return {
+        ...persisted,
+        request_burn_history: requestBurnHistory
+    };
+}
+function buildPersistedLinearBudgetRequestBurnHistoryEntry(input) {
+    const requestSample = resolveLinearBudgetRequestBurnSample(input.existing, input.observation);
+    if (!requestSample) {
+        return null;
+    }
+    const hydrated = hydrateLinearBudgetStatus(input.merged, {
+        operation: input.observation.source
+    });
+    return {
+        recorded_at: new Date().toISOString(),
+        observed_at: input.observation.observed_at,
+        source: input.observation.source,
+        operation: normalizeOptionalString(input.observation.source) ?? 'unknown',
+        run_id: resolveLinearBudgetObservationRunId(input.env),
+        process_pid: process.pid,
+        process_title: normalizeOptionalString(process.title),
+        request_id: input.observation.request_id,
+        request_bucket: requestSample.bucket,
+        remaining: requestSample.remaining,
+        remaining_delta: requestSample.remaining_delta,
+        reset_at: requestSample.reset_at,
+        suppression_reason: hydrated.suppression_reason,
+        cooldown_reason: hydrated.cooldown_active ? hydrated.suppression_reason : null
+    };
+}
+function resolveLinearBudgetRequestBurnSample(existing, observation) {
+    if (observation.requests) {
+        return {
+            bucket: 'requests',
+            remaining: observation.requests.remaining,
+            remaining_delta: resolveLinearBudgetRemainingDelta(existing?.requests?.remaining ?? null, observation.requests.remaining),
+            reset_at: observation.requests.reset_at
+        };
+    }
+    if (observation.endpoint?.requests) {
+        const targetKey = existing?.endpoints
+            ? resolvePersistedEndpointTargetKey(clonePersistedEndpoints(existing.endpoints), observation.endpoint)
+            : observation.endpoint.key;
+        return {
+            bucket: 'endpoint_requests',
+            remaining: observation.endpoint.requests.remaining,
+            remaining_delta: resolveLinearBudgetRemainingDelta(existing?.endpoints[targetKey]?.requests?.remaining ?? null, observation.endpoint.requests.remaining),
+            reset_at: observation.endpoint.requests.reset_at
+        };
+    }
+    return null;
+}
+function resolveLinearBudgetRemainingDelta(previousRemaining, nextRemaining) {
+    return previousRemaining !== null && nextRemaining !== null ? nextRemaining - previousRemaining : null;
+}
+function resolveLinearBudgetObservationRunId(env) {
+    return normalizeOptionalString(env.CODEX_ORCHESTRATOR_RUN_ID)
+        ?? normalizeOptionalString(env.CODEX_ORCHESTRATOR_PROVIDER_CONTROL_HOST_RUN_ID);
+}
+function hydrateLinearBudgetStatus(persisted, options = {}) {
+    const cleanedReservations = pruneExpiredReservations(persisted).reservations;
+    const normalizedEndpoints = Object.fromEntries(Object.entries(persisted.endpoints).map(([key, endpoint]) => [
+        key,
+        {
+            key,
+            endpoint_name: endpoint.endpoint_name,
+            aliases: [...endpoint.aliases],
+            observed_at: endpoint.observed_at,
+            requests: normalizeExpiredLinearBudgetBucket(endpoint.requests, endpoint.observed_at, {
+                requestReserveBucket: 'endpoint_requests'
+            }),
+            complexity: normalizeExpiredLinearBudgetBucket(endpoint.complexity, endpoint.observed_at),
+            request_complexity: endpoint.request_complexity
+        }
+    ]));
+    const base = {
+        observed_at: persisted.observed_at,
+        source: persisted.source,
+        request_id: persisted.request_id,
+        retry_after_seconds: persisted.retry_after_seconds,
+        cooldown_until: persisted.cooldown_until,
+        cooldown_active: isFutureIsoTimestamp(persisted.cooldown_until),
+        suppression: 'none',
+        suppression_reason: null,
+        scope_kind: persisted.scope_kind,
+        scope_key: persisted.scope_key,
+        viewer_id: persisted.viewer_id,
+        workspace_id: persisted.workspace_id,
+        token_fingerprints: [...persisted.token_fingerprints],
+        requests: normalizeExpiredLinearBudgetBucket(persisted.requests, persisted.observed_at, {
+            requestReserveBucket: 'requests'
+        }),
+        endpoint_requests: null,
+        complexity: normalizeExpiredLinearBudgetBucket(persisted.complexity, persisted.observed_at),
+        endpoint_complexity: null,
+        endpoint_name: null,
+        selected_endpoint_key: persisted.selected_endpoint_key,
+        request_complexity: persisted.request_complexity,
+        endpoints: normalizedEndpoints,
+        reservations: cleanedReservations.map((entry) => ({ ...entry })),
+        request_burn_history: clonePersistedLinearBudgetRequestBurnHistory(persisted.request_burn_history),
+        reservations_active: cleanedReservations.length
+    };
+    const materialized = materializeBudgetForOperation(base, options.operation ?? null);
+    if (materialized.cooldown_active) {
+        return {
+            ...materialized,
+            suppression: 'cooldown',
+            suppression_reason: 'linear_budget_shared_cooldown'
+        };
+    }
+    const pressure = resolveMaterializedBudgetPressure(materialized);
+    return {
+        ...materialized,
+        suppression: pressure.suppression,
+        suppression_reason: pressure.reason
+    };
+}
+function materializeBudgetForOperation(budget, operation) {
+    const view = resolveLinearBudgetOperationView(budget, operation ?? null);
+    return {
+        ...budget,
+        requests: view.requests,
+        endpoint_requests: view.endpoint_requests,
+        complexity: view.complexity,
+        endpoint_complexity: view.endpoint_complexity,
+        endpoint_name: view.endpoint_name,
+        selected_endpoint_key: view.endpoint_key,
+        request_complexity: view.request_complexity,
+        reservations_active: view.reservations_active
+    };
+}
+function resolveLinearBudgetOperationView(budget, operation) {
+    const normalizedOperation = normalizeOptionalString(operation);
+    const matchedEndpointKeys = normalizedOperation
+        ? resolveMatchingEndpointKeys(budget.endpoints, normalizedOperation)
+        : null;
+    const reservations = budget.reservations.filter((entry) => isFutureIsoTimestamp(entry.expires_at));
+    const selectedEndpointKey = resolveSelectedEndpointKey(budget, normalizedOperation, matchedEndpointKeys, reservations);
+    const selectedEndpoint = selectedEndpointKey ? budget.endpoints[selectedEndpointKey] ?? null : null;
+    const globalRequestsReserved = reservations.reduce((sum, entry) => sum + entry.requests, 0);
+    const globalComplexityReserved = reservations.reduce((sum, entry) => sum + (entry.complexity ?? 0), 0);
+    const endpointReservations = selectedEndpointKey
+        ? reservations.filter((entry) => entry.endpoint_key === selectedEndpointKey)
+        : [];
+    const endpointRequestsReserved = endpointReservations.reduce((sum, entry) => sum + entry.requests, 0);
+    const endpointComplexityReserved = endpointReservations.reduce((sum, entry) => sum + (entry.complexity ?? 0), 0);
+    return {
+        requests: subtractReservationFromBucket(budget.requests, globalRequestsReserved),
+        endpoint_requests: subtractReservationFromBucket(selectedEndpoint?.requests ?? null, endpointRequestsReserved),
+        complexity: subtractReservationFromBucket(budget.complexity, globalComplexityReserved),
+        endpoint_complexity: subtractReservationFromBucket(selectedEndpoint?.complexity ?? null, endpointComplexityReserved),
+        endpoint_key: selectedEndpointKey,
+        endpoint_name: selectedEndpoint?.endpoint_name ?? null,
+        request_complexity: resolveOperationRequestComplexity(budget, normalizedOperation, selectedEndpoint, matchedEndpointKeys),
+        reservations_active: reservations.length,
+        reservation_count: selectedEndpoint ? endpointReservations.length : reservations.length
+    };
+}
+function resolveSelectedEndpointKey(budget, operation, matchedEndpointKeys = null, reservations = []) {
+    if (operation) {
+        return selectMostConstrainedEndpointKey(budget.endpoints, matchedEndpointKeys ?? [], reservations);
+    }
+    if (budget.selected_endpoint_key && budget.endpoints[budget.selected_endpoint_key]) {
+        return budget.selected_endpoint_key;
+    }
+    return selectMostConstrainedEndpointKey(budget.endpoints);
+}
+function selectMostConstrainedEndpointKey(endpoints, candidateKeys = Object.keys(endpoints), reservations = []) {
+    let selected = { key: null, rank: -1, headroom: Number.POSITIVE_INFINITY };
+    for (const key of candidateKeys) {
+        const endpoint = endpoints[key];
+        if (!endpoint) {
+            continue;
+        }
+        const endpointReservations = reservations.filter((entry) => entry.endpoint_key === key);
+        const requestsReserved = endpointReservations.reduce((sum, entry) => sum + entry.requests, 0);
+        const complexityReserved = endpointReservations.reduce((sum, entry) => sum + (entry.complexity ?? 0), 0);
+        const pressure = resolveEndpointPressure({
+            requests: subtractReservationFromBucket(endpoint.requests, requestsReserved),
+            complexity: subtractReservationFromBucket(endpoint.complexity, complexityReserved)
+        });
+        if (pressure.rank > selected.rank ||
+            (pressure.rank === selected.rank && pressure.headroom < selected.headroom)) {
+            selected = {
+                key,
+                rank: pressure.rank,
+                headroom: pressure.headroom
+            };
+        }
+    }
+    return selected.key;
+}
+function resolveMatchingEndpointKeys(endpoints, operation) {
+    const matches = new Set();
+    const sourceKey = buildEndpointKey(null, operation);
+    if (endpoints[sourceKey]) {
+        matches.add(sourceKey);
+    }
+    const operationPrefix = `${operation}:`;
+    for (const [key, endpoint] of Object.entries(endpoints)) {
+        if (endpoint.aliases.some((alias) => alias === operation ||
+            alias.startsWith(operationPrefix) ||
+            operation.startsWith(`${alias}:`))) {
+            matches.add(key);
+        }
+    }
+    return [...matches];
+}
+function resolveOperationRequestComplexity(budget, operation, selectedEndpoint, matchedEndpointKeys) {
+    if (!operation) {
+        return selectedEndpoint?.request_complexity ?? budget.request_complexity;
+    }
+    const matchedComplexities = (matchedEndpointKeys ?? [])
+        .map((key) => budget.endpoints[key]?.request_complexity ?? null)
+        .filter((value) => value !== null);
+    if (matchedComplexities.length === 0) {
+        return null;
+    }
+    return Math.max(...matchedComplexities);
+}
+function resolveMaterializedBudgetPressure(budget) {
+    let selected = resolveBucketPressure('requests', budget.requests, false);
+    for (const next of [
+        resolveBucketPressure('complexity', budget.complexity, false),
+        resolveBucketPressure('endpoint_requests', budget.endpoint_requests, true),
+        resolveBucketPressure('endpoint_complexity', budget.endpoint_complexity, true)
+    ]) {
+        if (next.rank > selected.rank) {
+            selected = next;
+        }
+    }
+    return selected;
+}
+function resolveEndpointPressure(endpoint) {
+    const selected = [
+        resolveBucketPressure('endpoint_requests', endpoint.requests, true),
+        resolveBucketPressure('endpoint_complexity', endpoint.complexity, true)
+    ].reduce((selected, next) => (next.rank > selected.rank ? next : selected), {
+        rank: 0,
+        suppression: 'none',
+        reason: null,
+        endpoint_specific: true
+    });
+    return {
+        rank: selected.rank,
+        headroom: resolveEndpointHeadroom(endpoint.requests, endpoint.complexity)
+    };
+}
+function resolveEndpointHeadroom(requests, complexity) {
+    const candidates = [requests?.remaining ?? null, complexity?.remaining ?? null].filter((value) => value !== null);
+    return candidates.length > 0 ? Math.min(...candidates) : Number.POSITIVE_INFINITY;
+}
+function resolveBucketPressure(bucketKey, bucket, endpointSpecific) {
+    if (!bucket || bucket.remaining === null) {
+        return { rank: 0, suppression: 'none', reason: null, endpoint_specific: endpointSpecific };
+    }
+    if (bucket.remaining <= 0) {
+        return {
+            rank: endpointSpecific ? 4 : 3,
+            suppression: 'exhausted',
+            reason: bucketKey === 'endpoint_requests' || bucketKey === 'endpoint_complexity'
+                ? `linear_budget_${bucketKey}_exhausted`
+                : `linear_budget_${bucketKey}_exhausted`,
+            endpoint_specific: endpointSpecific
+        };
+    }
+    const limit = bucket.limit;
+    if (limit === null || limit <= 0) {
+        return { rank: 0, suppression: 'none', reason: null, endpoint_specific: endpointSpecific };
+    }
+    const lowThreshold = Math.max(1, Math.min(10, Math.floor(limit * 0.02)));
+    const constrainedThreshold = Math.max(lowThreshold + 1, Math.min(50, Math.floor(limit * 0.1)));
+    if (bucket.remaining <= lowThreshold) {
+        return {
+            rank: endpointSpecific ? 3 : 2,
+            suppression: 'low',
+            reason: `linear_budget_${bucketKey}_low`,
+            endpoint_specific: endpointSpecific
+        };
+    }
+    if (bucket.remaining <= constrainedThreshold) {
+        return {
+            rank: endpointSpecific ? 2 : 1,
+            suppression: 'constrained',
+            reason: `linear_budget_${bucketKey}_constrained`,
+            endpoint_specific: endpointSpecific
+        };
+    }
+    return { rank: 0, suppression: 'none', reason: null, endpoint_specific: endpointSpecific };
+}
+function resolveRequestPollingHeadroomGuard(input) {
+    let selected = null;
+    for (const candidate of [
+        resolveRequestBucketPollingHeadroomGuard({
+            bucket: input.budget.requests,
+            bucketKey: 'requests',
+            endpointSpecific: false,
+            defaultIntervalMs: input.defaultIntervalMs,
+            nowMs: input.nowMs
+        }),
+        resolveRequestBucketPollingHeadroomGuard({
+            bucket: input.budget.endpoint_requests,
+            bucketKey: 'endpoint_requests',
+            endpointSpecific: true,
+            defaultIntervalMs: input.defaultIntervalMs,
+            nowMs: input.nowMs
+        })
+    ]) {
+        if (!candidate) {
+            continue;
+        }
+        if (!selected || candidate.interval_ms > selected.interval_ms) {
+            selected = candidate;
+        }
+    }
+    return selected;
+}
+function resolveRequestBucketPollingHeadroomGuard(input) {
+    const bucket = input.bucket;
+    if (!bucket || bucket.remaining === null || bucket.remaining <= 0) {
+        return null;
+    }
+    const resetAtMs = parseIsoToMs(bucket.reset_at);
+    if (resetAtMs === null || resetAtMs <= input.nowMs) {
+        return null;
+    }
+    const reserve = resolveRequestPollingHeadroomReserve(bucket.limit, input.endpointSpecific);
+    const usableRemaining = Math.max(1, bucket.remaining - reserve);
+    const intervalFloorMs = Math.ceil((resetAtMs - input.nowMs) / usableRemaining);
+    if (!Number.isFinite(intervalFloorMs) || intervalFloorMs <= input.defaultIntervalMs) {
+        return null;
+    }
+    const lowIntervalMs = input.endpointSpecific
+        ? LINEAR_BUDGET_DEFAULT_ENDPOINT_LOW_POLL_INTERVAL_MS
+        : LINEAR_BUDGET_DEFAULT_LOW_POLL_INTERVAL_MS;
+    return {
+        interval_ms: intervalFloorMs,
+        suppression: intervalFloorMs >= lowIntervalMs ? 'low' : 'constrained',
+        reason: `linear_budget_${input.bucketKey}_reset_headroom`,
+        endpoint_specific: input.endpointSpecific
+    };
+}
+function resolveRequestPollingHeadroomReserve(limit, endpointSpecific) {
+    if (limit === null || limit <= 0) {
+        return 1;
+    }
+    const ratio = endpointSpecific
+        ? LINEAR_BUDGET_ENDPOINT_REQUEST_HEADROOM_RESERVE_RATIO
+        : LINEAR_BUDGET_REQUEST_HEADROOM_RESERVE_RATIO;
+    const maxReserve = endpointSpecific
+        ? LINEAR_BUDGET_ENDPOINT_REQUEST_HEADROOM_RESERVE_MAX
+        : LINEAR_BUDGET_REQUEST_HEADROOM_RESERVE_MAX;
+    return Math.max(1, Math.min(maxReserve, Math.floor(limit * ratio)));
+}
+function inferOperationComplexityFloor(requestComplexity, minimumRequestsRemaining) {
+    if (requestComplexity === null) {
+        return null;
+    }
+    return Math.max(1, requestComplexity * Math.max(1, minimumRequestsRemaining));
+}
+function resolveBucketShortfall(entries, requiredRemaining) {
+    for (const [bucketKey, bucket] of entries) {
+        if (bucket && bucket.remaining !== null && bucket.remaining < requiredRemaining) {
+            return {
+                bucket: bucketKey,
+                remaining: bucket.remaining
+            };
+        }
+    }
+    return null;
+}
+function resolveRequestReserveShortfall(entries, requiredRemaining) {
+    for (const [bucketKey, bucket] of entries) {
+        if (!bucket || bucket.remaining === null) {
+            continue;
+        }
+        const reserve = resolveRequestPollingHeadroomReserve(bucket.limit, bucketKey === 'endpoint_requests');
+        const usableRemaining = bucket.remaining - reserve;
+        if (usableRemaining < requiredRemaining) {
+            return {
+                bucket: bucketKey,
+                remaining: bucket.remaining,
+                reserve,
+                usable_remaining: usableRemaining
+            };
+        }
+    }
+    return null;
+}
+function findExhaustedLinearBudgetBucket(budget) {
+    for (const [bucketKey, bucket] of [
+        ['requests', budget.requests],
+        ['endpoint_requests', budget.endpoint_requests],
+        ['complexity', budget.complexity],
+        ['endpoint_complexity', budget.endpoint_complexity]
+    ]) {
+        if (bucket && bucket.remaining !== null && bucket.remaining <= 0) {
+            return bucketKey;
+        }
+    }
+    return null;
+}
+function parseLinearBudgetBucket(details, bucketKey) {
+    const limit = parseNumberLike(details[`${bucketKey}_limit`]);
+    const remaining = parseNumberLike(details[`${bucketKey}_remaining`]);
+    const resetAt = normalizeOptionalString(details[`${bucketKey}_reset_at`]);
+    if (limit === null && remaining === null && resetAt === null) {
+        return null;
+    }
+    return {
+        limit,
+        remaining,
+        reset_at: resetAt
+    };
+}
+function resolveCooldownUntil(input) {
+    const candidateMs = collectPersistedLinearBudgetCooldownCandidates({
+        persisted: input.persisted,
+        observedAt: input.observation.observed_at,
+        retryAfterSeconds: input.observation.retry_after_seconds
+    });
+    if (input.observation.assume_unknown_resets_exhausted) {
+        maybeCollectResetCandidate(candidateMs, input.observation.requests, true);
+        maybeCollectResetCandidate(candidateMs, input.observation.complexity, true);
+    }
+    return finalizeCooldownCandidateMs(candidateMs);
+}
+function resolvePersistedLinearBudgetCooldownUntil(input) {
+    return finalizeCooldownCandidateMs(collectPersistedLinearBudgetCooldownCandidates({
+        persisted: input.persisted,
+        observedAt: input.observedAt,
+        retryAfterSeconds: input.retryAfterSeconds
+    }));
+}
+function collectPersistedLinearBudgetCooldownCandidates(input) {
+    const candidateMs = [];
+    const observedAtMs = parseIsoToMs(input.observedAt);
+    if (observedAtMs !== null && input.retryAfterSeconds !== null && input.retryAfterSeconds >= 0) {
+        candidateMs.push(observedAtMs + input.retryAfterSeconds * 1000);
+    }
+    for (const bucket of [input.persisted.requests, input.persisted.complexity]) {
+        maybeCollectResetCandidate(candidateMs, bucket, false);
+    }
+    return candidateMs;
+}
+function finalizeCooldownCandidateMs(candidateMs) {
+    if (candidateMs.length === 0) {
+        return null;
+    }
+    const latestMs = Math.max(...candidateMs);
+    return Number.isFinite(latestMs) ? new Date(latestMs).toISOString() : null;
+}
+function maybeCollectResetCandidate(candidates, bucket, assumeUnknownRemainingExhausted) {
+    if (!bucket?.reset_at) {
+        return;
+    }
+    const resetAtMs = parseIsoToMs(bucket.reset_at);
+    if (resetAtMs === null) {
+        return;
+    }
+    const exhausted = bucket.remaining !== null ? bucket.remaining <= 0 : assumeUnknownRemainingExhausted;
+    if (exhausted) {
+        candidates.push(resetAtMs);
+    }
+}
+function serializeLinearBudgetBucketDetails(bucketKey, bucket) {
+    if (!bucket) {
+        return {};
+    }
+    return {
+        ...(bucket.limit !== null ? { [`${bucketKey}_limit`]: bucket.limit } : {}),
+        ...(bucket.remaining !== null ? { [`${bucketKey}_remaining`]: bucket.remaining } : {}),
+        ...(bucket.reset_at ? { [`${bucketKey}_reset_at`]: bucket.reset_at } : {})
+    };
+}
+function resolveLinearBudgetStatePaths(env) {
+    const tokenFingerprint = resolveLinearApiTokenFingerprint(env);
+    if (!tokenFingerprint) {
+        return null;
+    }
+    const isVitestRuntime = normalizeOptionalString(env.VITEST) === 'true' ||
+        normalizeOptionalString(process.env.VITEST) === 'true' ||
+        normalizeOptionalString(env.NODE_ENV) === 'test' ||
+        normalizeOptionalString(process.env.NODE_ENV) === 'test';
+    if (isVitestRuntime && !normalizeOptionalString(env.CODEX_HOME)) {
+        return null;
+    }
+    const directory = join(resolveCodexOrchestratorHome(env), LINEAR_BUDGET_STATE_DIRNAME);
+    return {
+        directory,
+        scopesDir: join(directory, LINEAR_BUDGET_SCOPE_DIRNAME),
+        aliasesDir: join(directory, LINEAR_BUDGET_ALIAS_DIRNAME),
+        legacyStatePath: join(directory, `${tokenFingerprint}.json`),
+        aliasPath: join(directory, LINEAR_BUDGET_ALIAS_DIRNAME, `${tokenFingerprint}.json`),
+        lockPath: join(directory, `${tokenFingerprint}.lock`),
+        tokenFingerprint
+    };
+}
+async function withLinearBudgetStateLock(paths, callback, lockScopeKey = paths.tokenFingerprint) {
+    const lock = await acquireLockWithRetry({
+        taskId: `linear-budget-${lockScopeKey.slice(0, 12)}`,
+        lockPath: resolveLinearBudgetLockPath(paths, lockScopeKey),
+        retry: LINEAR_BUDGET_LOCK_RETRY,
+        ensureDirectory: async () => {
+            await mkdir(dirname(resolveLinearBudgetLockPath(paths, lockScopeKey)), { recursive: true });
+        },
+        createError: (taskId, attempts) => new Error(`Failed to acquire Linear budget state lock for ${taskId} after ${attempts} attempts.`)
+    });
+    try {
+        return await callback();
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function resolveLinearBudgetLockScopeKey(paths, scopeHint = undefined) {
+    const normalizedHint = normalizeScopeHint(scopeHint);
+    if (normalizedHint?.viewer_id) {
+        return resolveUserScopeKey(normalizedHint.viewer_id, normalizedHint.workspace_id);
+    }
+    const alias = await readPersistedLinearBudgetAlias(paths.aliasPath, paths.tokenFingerprint);
+    if (alias?.scope_kind === 'user') {
+        return alias.scope_key;
+    }
+    return paths.tokenFingerprint;
+}
+function resolveLinearBudgetLockPath(paths, lockScopeKey) {
+    return join(paths.directory, `${lockScopeKey}.lock`);
+}
+async function readNewestPersistedLinearBudgetStatus(paths, scopeHint) {
+    const alias = await readPersistedLinearBudgetAlias(paths.aliasPath, paths.tokenFingerprint);
+    const candidatePaths = new Set([paths.legacyStatePath]);
+    if (alias) {
+        candidatePaths.add(resolveScopeStatePath(paths, alias.scope_key));
+    }
+    if (scopeHint?.viewer_id) {
+        candidatePaths.add(resolveScopeStatePath(paths, resolveUserScopeKey(scopeHint.viewer_id, scopeHint.workspace_id)));
+    }
+    const candidates = [];
+    for (const candidatePath of candidatePaths) {
+        const persisted = await readPersistedLinearBudgetStatus(candidatePath, paths.tokenFingerprint);
+        if (!persisted) {
+            continue;
+        }
+        candidates.push(persisted);
+    }
+    return mergePersistedLinearBudgetCandidates(candidates);
+}
+function mergePersistedLinearBudgetCandidates(candidates) {
+    if (candidates.length === 0) {
+        return null;
+    }
+    const sorted = [...candidates].sort(comparePersistedLinearBudgetObservedAt);
+    const preferredUserScope = [...sorted]
+        .reverse()
+        .find((candidate) => candidate.scope_kind === 'user' && candidate.viewer_id) ?? null;
+    let merged = clonePersistedLinearBudgetStatus(sorted[0]);
+    for (const candidate of sorted.slice(1)) {
+        merged = mergePersistedLinearBudgetCandidate(merged, candidate);
+    }
+    if (!preferredUserScope) {
+        return merged;
+    }
+    return {
+        ...merged,
+        scope_kind: preferredUserScope.scope_kind,
+        scope_key: preferredUserScope.scope_key,
+        viewer_id: preferredUserScope.viewer_id,
+        workspace_id: preferredUserScope.workspace_id
+    };
+}
+function comparePersistedLinearBudgetObservedAt(left, right) {
+    const leftObservedAtMs = parseIsoToMs(left.observed_at) ?? Number.NEGATIVE_INFINITY;
+    const rightObservedAtMs = parseIsoToMs(right.observed_at) ?? Number.NEGATIVE_INFINITY;
+    return leftObservedAtMs - rightObservedAtMs;
+}
+function mergePersistedLinearBudgetCandidate(existing, candidate) {
+    const endpoints = clonePersistedEndpoints(existing.endpoints);
+    for (const [key, endpoint] of Object.entries(candidate.endpoints)) {
+        upsertPersistedEndpointObservation(endpoints, {
+            key,
+            endpoint_name: endpoint.endpoint_name,
+            aliases: [...endpoint.aliases],
+            observed_at: endpoint.observed_at,
+            requests: cloneBucket(endpoint.requests),
+            complexity: cloneBucket(endpoint.complexity),
+            request_complexity: endpoint.request_complexity,
+            assume_unknown_resets_exhausted: false
+        });
+    }
+    const selectedEndpointKey = candidate.selected_endpoint_key ?? existing.selected_endpoint_key;
+    const merged = {
+        ...clonePersistedLinearBudgetStatus(existing),
+        observed_at: maxIsoTimestamp(existing.observed_at, candidate.observed_at) ?? candidate.observed_at,
+        source: candidate.source,
+        request_id: candidate.request_id ?? existing.request_id,
+        retry_after_seconds: candidate.retry_after_seconds,
+        cooldown_until: null,
+        requests: mergeLinearBudgetBucket(existing.requests, candidate.requests),
+        complexity: mergeLinearBudgetBucket(existing.complexity, candidate.complexity),
+        request_complexity: candidate.request_complexity ?? existing.request_complexity,
+        selected_endpoint_key: selectedEndpointKey && !endpoints[selectedEndpointKey] ? null : selectedEndpointKey,
+        token_fingerprints: uniqueStrings([...existing.token_fingerprints, ...candidate.token_fingerprints]),
+        endpoints,
+        reservations: mergePersistedLinearBudgetReservations(existing, candidate),
+        request_burn_history: mergePersistedLinearBudgetRequestBurnHistory(existing.request_burn_history, candidate.request_burn_history)
+    };
+    merged.cooldown_until = resolvePersistedLinearBudgetCooldownUntil({
+        persisted: merged,
+        observedAt: candidate.observed_at,
+        retryAfterSeconds: candidate.retry_after_seconds
+    });
+    return merged;
+}
+async function readPersistedLinearBudgetStatus(statePath, tokenFingerprint) {
+    try {
+        const parsed = JSON.parse(await readFile(statePath, 'utf8'));
+        return parsePersistedLinearBudgetStatus(parsed, tokenFingerprint);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return null;
+        }
+        return null;
+    }
+}
+function parsePersistedLinearBudgetStatus(value, tokenFingerprint) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    if (record.schema_version === LINEAR_BUDGET_STATE_SCHEMA_VERSION) {
+        return parseSchemaV2LinearBudgetStatus(record, tokenFingerprint);
+    }
+    if (record.schema_version === 1) {
+        return parseLegacySchemaV1LinearBudgetStatus(record, tokenFingerprint);
+    }
+    return null;
+}
+function parseSchemaV2LinearBudgetStatus(record, tokenFingerprint) {
+    const scopeKind = normalizeOptionalString(record.scope_kind);
+    const scopeKey = normalizeOptionalString(record.scope_key);
+    const observedAt = normalizeOptionalString(record.observed_at);
+    const source = normalizeOptionalString(record.source);
+    if ((scopeKind !== 'user' && scopeKind !== 'token') || !scopeKey || !observedAt || !source) {
+        return null;
+    }
+    const tokenFingerprints = Array.isArray(record.token_fingerprints)
+        ? record.token_fingerprints
+            .map((entry) => normalizeOptionalString(entry))
+            .filter((entry) => entry !== null)
+        : [];
+    if (tokenFingerprints.length === 0) {
+        tokenFingerprints.push(tokenFingerprint);
+    }
+    const endpoints = record.endpoints && typeof record.endpoints === 'object'
+        ? Object.fromEntries(Object.entries(record.endpoints)
+            .map(([key, value]) => [key, parsePersistedLinearBudgetEndpointStatus(value)])
+            .filter((entry) => entry[1] !== null))
+        : {};
+    const reservations = Array.isArray(record.reservations)
+        ? record.reservations
+            .map((entry) => parsePersistedLinearBudgetReservation(entry))
+            .filter((entry) => entry !== null)
+        : [];
+    const requestBurnHistory = Array.isArray(record.request_burn_history)
+        ? record.request_burn_history
+            .map((entry) => parsePersistedLinearBudgetRequestBurnHistoryEntry(entry))
+            .filter((entry) => entry !== null)
+        : [];
+    return {
+        schema_version: 2,
+        scope_kind: scopeKind,
+        scope_key: scopeKey,
+        viewer_id: normalizeOptionalString(record.viewer_id),
+        workspace_id: normalizeOptionalString(record.workspace_id),
+        token_fingerprints: uniqueStrings(tokenFingerprints),
+        observed_at: observedAt,
+        source,
+        request_id: normalizeOptionalString(record.request_id),
+        retry_after_seconds: parseNumberLike(record.retry_after_seconds),
+        cooldown_until: normalizeOptionalString(record.cooldown_until),
+        requests: parsePersistedLinearBudgetBucket(record.requests),
+        complexity: parsePersistedLinearBudgetBucket(record.complexity),
+        request_complexity: parseNumberLike(record.request_complexity),
+        selected_endpoint_key: normalizeOptionalString(record.selected_endpoint_key),
+        endpoints,
+        reservations,
+        request_burn_history: requestBurnHistory
+    };
+}
+function parseLegacySchemaV1LinearBudgetStatus(record, tokenFingerprint) {
+    if (normalizeOptionalString(record.token_fingerprint) !== tokenFingerprint) {
+        return null;
+    }
+    const observedAt = normalizeOptionalString(record.observed_at);
+    const source = normalizeOptionalString(record.source);
+    if (!observedAt || !source) {
+        return null;
+    }
+    const legacyEndpointRequests = parsePersistedLinearBudgetBucket(record.endpoint_requests);
+    const legacyEndpointComplexity = parsePersistedLinearBudgetBucket(record.endpoint_complexity);
+    const selectedEndpointKey = legacyEndpointRequests || legacyEndpointComplexity ? buildEndpointKey(null, source) : null;
+    return {
+        schema_version: 2,
+        scope_kind: 'token',
+        scope_key: tokenFingerprint,
+        viewer_id: null,
+        workspace_id: null,
+        token_fingerprints: [tokenFingerprint],
+        observed_at: observedAt,
+        source,
+        request_id: normalizeOptionalString(record.request_id),
+        retry_after_seconds: parseNumberLike(record.retry_after_seconds),
+        cooldown_until: normalizeOptionalString(record.cooldown_until),
+        requests: parsePersistedLinearBudgetBucket(record.requests),
+        complexity: parsePersistedLinearBudgetBucket(record.complexity),
+        request_complexity: null,
+        selected_endpoint_key: selectedEndpointKey,
+        endpoints: selectedEndpointKey === null
+            ? {}
+            : {
+                [selectedEndpointKey]: {
+                    endpoint_name: null,
+                    aliases: [source],
+                    observed_at: observedAt,
+                    requests: legacyEndpointRequests,
+                    complexity: legacyEndpointComplexity,
+                    request_complexity: null
+                }
+            },
+        reservations: [],
+        request_burn_history: []
+    };
+}
+function parsePersistedLinearBudgetEndpointStatus(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    const observedAt = normalizeOptionalString(record.observed_at);
+    if (!observedAt) {
+        return null;
+    }
+    const aliases = Array.isArray(record.aliases)
+        ? record.aliases
+            .map((entry) => normalizeOptionalString(entry))
+            .filter((entry) => entry !== null)
+        : [];
+    return {
+        endpoint_name: normalizeOptionalString(record.endpoint_name),
+        aliases: uniqueStrings(aliases),
+        observed_at: observedAt,
+        requests: parsePersistedLinearBudgetBucket(record.requests),
+        complexity: parsePersistedLinearBudgetBucket(record.complexity),
+        request_complexity: parseNumberLike(record.request_complexity)
+    };
+}
+function parsePersistedLinearBudgetReservation(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    const id = normalizeRequiredString(record.id);
+    const operation = normalizeRequiredString(record.operation);
+    const createdAt = normalizeOptionalString(record.created_at);
+    const expiresAt = normalizeOptionalString(record.expires_at);
+    const requests = normalizePositiveInteger(record.requests);
+    const complexity = normalizePositiveInteger(record.complexity);
+    if (!id || !operation || !createdAt || !expiresAt || requests === null) {
+        return null;
+    }
+    return {
+        id,
+        operation,
+        endpoint_key: normalizeOptionalString(record.endpoint_key),
+        requests,
+        complexity,
+        created_at: createdAt,
+        expires_at: expiresAt
+    };
+}
+function parsePersistedLinearBudgetRequestBurnHistoryEntry(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    const recordedAt = normalizeOptionalString(record.recorded_at);
+    const observedAt = normalizeOptionalString(record.observed_at);
+    const source = normalizeRequiredString(record.source);
+    const requestBucket = normalizeOptionalString(record.request_bucket);
+    if (!recordedAt || !observedAt || !source) {
+        return null;
+    }
+    const operation = normalizeRequiredString(record.operation) ?? source;
+    return {
+        recorded_at: recordedAt,
+        observed_at: observedAt,
+        source,
+        operation,
+        run_id: normalizeOptionalString(record.run_id),
+        process_pid: parseNumberLike(record.process_pid),
+        process_title: normalizeOptionalString(record.process_title),
+        request_id: normalizeOptionalString(record.request_id),
+        request_bucket: requestBucket === 'requests' || requestBucket === 'endpoint_requests'
+            ? requestBucket
+            : null,
+        remaining: parseNumberLike(record.remaining),
+        remaining_delta: parseSignedInteger(record.remaining_delta),
+        reset_at: normalizeOptionalString(record.reset_at),
+        suppression_reason: normalizeOptionalString(record.suppression_reason),
+        cooldown_reason: normalizeOptionalString(record.cooldown_reason)
+    };
+}
+function parsePersistedLinearBudgetBucket(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    const limit = parseNumberLike(record.limit);
+    const remaining = parseNumberLike(record.remaining);
+    const resetAt = normalizeOptionalString(record.reset_at);
+    if (limit === null && remaining === null && resetAt === null) {
+        return null;
+    }
+    return {
+        limit,
+        remaining,
+        reset_at: resetAt
+    };
+}
+async function writePersistedLinearBudgetStatus(paths, persisted) {
+    const statePath = resolvePersistedStatePath(paths, persisted);
+    await mkdir(dirname(statePath), { recursive: true });
+    await writeJsonAtomic(statePath, persisted);
+}
+async function writePersistedLinearBudgetAlias(paths, scope) {
+    const aliasRecord = {
+        schema_version: LINEAR_BUDGET_ALIAS_SCHEMA_VERSION,
+        token_fingerprint: paths.tokenFingerprint,
+        scope_kind: scope.kind,
+        scope_key: scope.key,
+        viewer_id: scope.viewer_id,
+        workspace_id: scope.workspace_id,
+        updated_at: new Date().toISOString()
+    };
+    await mkdir(dirname(paths.aliasPath), { recursive: true });
+    await writeJsonAtomic(paths.aliasPath, aliasRecord);
+}
+async function readPersistedLinearBudgetAlias(aliasPath, tokenFingerprint) {
+    try {
+        const parsed = JSON.parse(await readFile(aliasPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        const record = parsed;
+        if (record.schema_version !== LINEAR_BUDGET_ALIAS_SCHEMA_VERSION) {
+            return null;
+        }
+        if (normalizeOptionalString(record.token_fingerprint) !== tokenFingerprint) {
+            return null;
+        }
+        const scopeKind = normalizeOptionalString(record.scope_kind);
+        const scopeKey = normalizeOptionalString(record.scope_key);
+        const updatedAt = normalizeOptionalString(record.updated_at);
+        if ((scopeKind !== 'user' && scopeKind !== 'token') || !scopeKey || !updatedAt) {
+            return null;
+        }
+        return {
+            schema_version: 1,
+            token_fingerprint: tokenFingerprint,
+            scope_kind: scopeKind,
+            scope_key: scopeKey,
+            viewer_id: normalizeOptionalString(record.viewer_id),
+            workspace_id: normalizeOptionalString(record.workspace_id),
+            updated_at: updatedAt
+        };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return null;
+        }
+        return null;
+    }
+}
+async function resolveWriteScope(paths, scopeHint, existing) {
+    const normalizedHint = normalizeScopeHint(scopeHint);
+    if (normalizedHint?.viewer_id) {
+        return {
+            kind: 'user',
+            key: resolveUserScopeKey(normalizedHint.viewer_id, normalizedHint.workspace_id),
+            viewer_id: normalizedHint.viewer_id,
+            workspace_id: normalizedHint.workspace_id,
+            token_fingerprint: paths.tokenFingerprint
+        };
+    }
+    if (existing?.scope_kind === 'user' && existing.viewer_id) {
+        return {
+            kind: 'user',
+            key: existing.scope_key,
+            viewer_id: existing.viewer_id,
+            workspace_id: existing.workspace_id,
+            token_fingerprint: paths.tokenFingerprint
+        };
+    }
+    const alias = await readPersistedLinearBudgetAlias(paths.aliasPath, paths.tokenFingerprint);
+    if (alias?.scope_kind === 'user' && alias.viewer_id) {
+        return {
+            kind: 'user',
+            key: alias.scope_key,
+            viewer_id: alias.viewer_id,
+            workspace_id: alias.workspace_id,
+            token_fingerprint: paths.tokenFingerprint
+        };
+    }
+    return {
+        kind: 'token',
+        key: paths.tokenFingerprint,
+        viewer_id: null,
+        workspace_id: normalizedHint?.workspace_id ?? existing?.workspace_id ?? alias?.workspace_id ?? null,
+        token_fingerprint: paths.tokenFingerprint
+    };
+}
+function normalizeScopeHint(value) {
+    if (!value) {
+        return null;
+    }
+    const viewerId = normalizeOptionalString(value.viewerId);
+    const workspaceId = normalizeOptionalString(value.workspaceId);
+    if (!viewerId && !workspaceId) {
+        return null;
+    }
+    return {
+        viewer_id: viewerId,
+        workspace_id: workspaceId
+    };
+}
+function resolvePersistedStatePath(paths, persisted) {
+    return persisted.scope_kind === 'user'
+        ? resolveScopeStatePath(paths, persisted.scope_key)
+        : paths.legacyStatePath;
+}
+function resolveScopeStatePath(paths, scopeKey) {
+    return join(paths.scopesDir, `${scopeKey}.json`);
+}
+function resolveUserScopeKey(viewerId, workspaceId) {
+    return createHash('sha256')
+        .update(`linear-user:${workspaceId ?? 'unknown-workspace'}:${viewerId}`)
+        .digest('hex');
+}
+function buildEndpointKey(endpointName, source) {
+    if (endpointName) {
+        return `endpoint:${normalizeKeyFragment(endpointName)}`;
+    }
+    return `source:${normalizeKeyFragment(source)}`;
+}
+function normalizeKeyFragment(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9]+/gu, '-').replace(/^-+|-+$/gu, '') || 'unknown';
+}
+function cloneBucket(bucket) {
+    return bucket
+        ? {
+            limit: bucket.limit,
+            remaining: bucket.remaining,
+            reset_at: bucket.reset_at
+        }
+        : null;
+}
+function mergeLinearBudgetBucket(existing, observation) {
+    if (!existing) {
+        return cloneBucket(observation);
+    }
+    if (!observation) {
+        return cloneBucket(existing);
+    }
+    return {
+        limit: observation.limit ?? existing.limit,
+        remaining: observation.remaining ?? existing.remaining,
+        reset_at: observation.reset_at ?? existing.reset_at
+    };
+}
+function subtractReservationFromBucket(bucket, reservedAmount) {
+    if (!bucket || bucket.remaining === null || reservedAmount <= 0) {
+        return bucket;
+    }
+    return {
+        limit: bucket.limit,
+        remaining: bucket.remaining - reservedAmount,
+        reset_at: bucket.reset_at
+    };
+}
+function normalizeExpiredLinearBudgetBucket(bucket, observedAt, options = {}) {
+    if (!bucket) {
+        return null;
+    }
+    const resetAtMs = parseIsoToMs(bucket.reset_at);
+    if (resetAtMs === null) {
+        const observedAtMs = parseIsoToMs(observedAt);
+        if (observedAtMs !== null &&
+            bucket.remaining !== null &&
+            bucket.remaining <= 0 &&
+            observedAtMs + LINEAR_BUDGET_UNKNOWN_RESET_EXHAUSTED_GRACE_MS <= Date.now()) {
+            if (bucket.limit === null) {
+                return null;
+            }
+            return {
+                limit: bucket.limit,
+                remaining: null,
+                reset_at: null
+            };
+        }
+        const requestReserveBucket = options.requestReserveBucket;
+        if (requestReserveBucket) {
+            const reserve = resolveRequestPollingHeadroomReserve(bucket.limit, requestReserveBucket === 'endpoint_requests');
+            if (observedAtMs !== null &&
+                bucket.remaining !== null &&
+                bucket.remaining <= reserve &&
+                observedAtMs + LINEAR_BUDGET_UNKNOWN_RESET_EXHAUSTED_GRACE_MS <= Date.now()) {
+                return {
+                    limit: bucket.limit,
+                    remaining: null,
+                    reset_at: null
+                };
+            }
+        }
+        return bucket;
+    }
+    if (resetAtMs > Date.now()) {
+        return bucket;
+    }
+    if (bucket.limit === null) {
+        return null;
+    }
+    return {
+        limit: bucket.limit,
+        remaining: null,
+        reset_at: null
+    };
+}
+function pruneExpiredReservations(persisted) {
+    const reservations = persisted.reservations.filter((entry) => isFutureIsoTimestamp(entry.expires_at));
+    return reservations.length === persisted.reservations.length
+        ? persisted
+        : {
+            ...persisted,
+            reservations
+        };
+}
+function applyDeterministicPositiveJitter(baseIntervalMs, seed, nowMs) {
+    if (baseIntervalMs <= 0) {
+        return baseIntervalMs;
+    }
+    const maxJitterMs = Math.min(LINEAR_BUDGET_POLL_JITTER_MAX_MS, Math.max(1_000, Math.floor(baseIntervalMs * LINEAR_BUDGET_POLL_JITTER_RATIO)));
+    const timeBucket = Math.floor(nowMs / Math.max(baseIntervalMs, 1));
+    const hash = stableHash(`${seed}|${timeBucket}`);
+    return baseIntervalMs + (hash % (maxJitterMs + 1));
+}
+function stableHash(value) {
+    let hash = 0;
+    for (const character of value) {
+        hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
+    }
+    return hash;
+}
+function maxIsoTimestamp(left, right) {
+    const leftMs = parseIsoToMs(left);
+    const rightMs = parseIsoToMs(right);
+    if (leftMs === null) {
+        return right;
+    }
+    if (rightMs === null) {
+        return left;
+    }
+    return rightMs >= leftMs ? right : left;
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => value.trim().length > 0))];
+}
+function normalizePositiveInteger(value) {
+    const parsed = parseNumberLike(value);
+    return parsed !== null && parsed > 0 ? parsed : null;
+}
+function parseSignedInteger(value) {
+    return parseNumberLike(value);
+}
+function parseNumberLike(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) ? parsed : null;
+}
+function parseIsoToMs(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return null;
+    }
+    const parsed = Date.parse(normalized);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function isFutureIsoTimestamp(value) {
+    const parsed = parseIsoToMs(value);
+    return parsed !== null && parsed > Date.now();
+}
+function normalizeOptionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function normalizeRequiredString(value) {
+    return normalizeOptionalString(value);
+}
+function hasRecordableLinearBudgetDetails(details) {
+    return Object.keys(details).some((key) => key !== 'request_id' && key !== 'errors');
+}