codex-multi-auth 2.22.0 → 2.24.0

package/dist/lib/runtime-rotation-proxy.js

@@ -2,14 +2,15 @@ import { createAutomaticApiCheck, startAutomaticApiChecks } from "./runtime/auto
 import { startAutomaticAccountChecks } from "./runtime/automatic-account-checks.js";
 import { createAutomaticSubscriptionCheck } from "./runtime/automatic-subscription-checks.js";
 import { ClientCancellationError } from "./request/client-cancellation.js";
+import { fetchWithProxy } from "./request/proxy-fetch.js";
 import { createNativeAccountStorageReader } from "./runtime/native-account-storage.js";
 import { resetSnapshotQuota } from "./runtime/reset-credits.js";
 import { createResetCreditService, loadResetCreditState } from "./runtime/account-reset-credits.js";
-import { recoverResetQuota, applyConfirmedReset } from "./runtime/reset-credit-routing.js";
+import { recoverResetQuota, applyConfirmedReset, primaryPoolFullyExhausted } from "./runtime/reset-credit-routing.js";
 import { readSubscriptionQuotaEvent } from "./runtime/subscription-quota-event.js";
 import { loadQuotaCache } from "./quota-cache.js";
 import { findQuotaCacheEntryForAccount } from "./quota-readiness.js";
-import { subscriptionQuotaPreference, compareSubscriptionQuota } from "./runtime/subscription-quota-order.js";
+import { hasFreshOrdinaryUsagePermission, subscriptionQuotaPreference, compareSubscriptionQuota } from "./runtime/subscription-quota-order.js";
 import { inferenceAccountKey } from "./runtime/inference-activity.js";
 import { modelScopeId, workspaceModelScopes } from "./runtime/workspace-model-scopes.js";
 import { RuntimeCapabilityFailures, classifyCapabilityFailure } from "./runtime/runtime-capability-failures.js";
@@ -32,7 +33,7 @@ import { AccountManager, AUTH_INVALIDATION_MARKER, extractAccountId, } from "./a
 import { withRoutingMutex } from "./routing-mutex.js";
 import { getQuotaKey } from "./accounts/rate-limits.js";
 import { getFetchTimeoutMs, getNetworkErrorCooldownMs, getRetryAllAccountsMaxRetries, getServerErrorCooldownMs, getSessionAffinity, getSessionAffinityMaxEntries, getSessionAffinityTtlMs, getStreamStallTimeoutMs, getMinRotationIntervalMs, getTokenInvalidationCooldownMs, getTokenRefreshSkewMs, getPidOffsetEnabled, getPreemptiveQuotaEnabled, getPreemptiveQuotaMaxDeferralMs, getPreemptiveQuotaRemainingPercent5h, getPreemptiveQuotaRemainingPercent7d, getContextBudgetGuardEnabled, getContextBudgetGuardSoftPercent, getContextBudgetGuardHardPercent, getContextBudgetGuardModelWindowOverrides, getRoutingMutexMode, getSchedulingStrategy, loadPluginConfig, } from "./config.js";
-import { CODEX_BASE_URL, HTTP_STATUS, LUNA_RESERVE_MODEL, MAX_RATE_LIMIT_DELAY_MS, OPENAI_HEADERS, OPENAI_HEADER_VALUES, URL_PATHS, } from "./constants.js";
+import { CODEX_BASE_URL, HTTP_STATUS, LUNA_RESERVE_MODEL, MAX_RATE_LIMIT_DELAY_MS, RATE_LIMIT_CACHE_TTL_MS, OPENAI_HEADERS, OPENAI_HEADER_VALUES, URL_PATHS, } from "./constants.js";
 import { getModelFamily } from "./prompts/codex.js";
 import { CURRENT_CODEX_MODEL } from "./request/helpers/model-map.js";
 import { recordRuntimeInferenceRequest, flushRuntimeInferenceActivity, mutateRuntimeObservabilitySnapshot, recordRuntimeAccountRecovery, recordRuntimePoolExhaustion, } from "./runtime/runtime-observability.js";
@@ -829,7 +830,8 @@ function writeUnauthorized(res) {
 }
 function writePoolExhausted(params) {
     const { res, accountManager, family, model, reason } = params;
-    const waitMs = params.retryAfterMs ?? accountManager.getMinWaitTimeForFamily(family, model);
+    const waitMs = params.retryAfterMs ??
+        accountManager.getMinWaitTimeForFamily(family, model, params.ineligibleAccountIndexes);
     const accountCount = accountManager.getAccountCount();
     const accountSkipReasons = params.accountSkipReasons ?? {};
     recordRuntimePoolExhaustion({
@@ -879,7 +881,7 @@ export async function startRuntimeRotationProxy(options) {
     const routingMutexMode = getRoutingMutexMode(pluginConfig);
     activeAccountManager.setRoutingMutexMode(routingMutexMode);
     const schedulingStrategy = getSchedulingStrategy(pluginConfig);
-    const fetchImpl = options.fetchImpl ?? fetch;
+    const fetchImpl = options.fetchImpl ?? fetchWithProxy;
     const host = options.host ?? DEFAULT_HOST;
     // Defense in depth (runtime-proxy-01): the proxy presents managed OAuth tokens
     // and must never be reachable off-box. It is loopback-only with NO opt-out —
@@ -1045,6 +1047,7 @@ export async function startRuntimeRotationProxy(options) {
             await Promise.all([automaticChecks?.stop(), automaticApiChecks?.stop()]);
             websocketGateway.close();
             await closeServer(server, sockets);
+            state.subscriptionQuotaRejections?.clear();
             await flushRuntimeInferenceActivity();
             await state.activeAccountManager.flushPendingSave();
         },
@@ -1057,6 +1060,9 @@ export async function startRuntimeRotationProxy(options) {
             schedulingStrategy: state.schedulingStrategy,
             websocketConnections: websocketGateway.stats.connections,
             websocketUpstreamRequests: websocketGateway.stats.upstreamRequests,
+            websocketActiveConnections: websocketGateway.stats.activeConnections,
+            websocketCapacityReclaims: websocketGateway.stats.capacityReclaims,
+            lastWebsocketUpgradeRejection: websocketGateway.stats.lastUpgradeRejection,
             lastWebsocketDisconnect: websocketGateway.stats.lastDisconnect,
             // Redact any email/token material that leaked into a raw upstream or
             // refresh error string before exposing it to status/report consumers
@@ -1603,7 +1609,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 }
             }
         };
-        const resetCreditState = state.nativeOpenai && isResponsesRequest ? await cachedRead(state, "reset-credits", loadResetCreditState).catch(() => null) : null;
+        let resetCreditState = state.nativeOpenai && isResponsesRequest ? await cachedRead(state, "reset-credits", loadResetCreditState).catch(() => null) : null;
         const quotaForScope = (account, scope) => {
             // Scoped observations belong to this credential and workspace; legacy entries only describe the binding.
             const cached = findQuotaCacheEntryForAccount(subscriptionQuotaCache, account, accountManager.getAccountsSnapshot(), undefined, scope.accountId);
@@ -1723,7 +1729,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 if (retryAt > state.now())
                     throw new CatalogRetryError(retryAt - state.now());
                 backoff.delete(key);
-                const scope = state.activeAccountManager.getAccountsSnapshot().flatMap(workspaceModelScopes).find(s => s.id === key && s.enabled);
+                const scope = state.activeAccountManager.getAccountsSnapshot().flatMap(workspaceModelScopes).find(s => s.id === key && s.routable);
                 const account = scope ? state.activeAccountManager.getAccountByIndex(scope.accountIndex) : null;
                 if (!account || account.enabled === false || account.authInvalidatedAt ||
                     (account.cooldownReason === "auth-failure" && (account.coolingDownUntil ?? 0) > state.now()))
@@ -1796,7 +1802,7 @@ async function handleRequestInner(state, req, res, traceId) {
                         a.email === reference.email &&
                         a.accountId === reference.accountId)));
                 const scopes = discovery.flatMap(workspaceModelScopes);
-                const enabledKeys = scopes.filter(scope => scope.enabled).map(scope => scope.id);
+                const enabledKeys = scopes.filter(scope => scope.routable).map(scope => scope.id);
                 const routableKeys = scopes.filter(scope => scope.routable).map(scope => scope.id);
                 const oauthRefresh = modelCatalog.list(enabledKeys);
                 // Explicit check waits for all workspaces; picker discovery runs API and OAuth in parallel.
@@ -1875,13 +1881,23 @@ async function handleRequestInner(state, req, res, traceId) {
                     models = await refresh;
                 else {
                     const cached = pickerSnapshot();
-                    if (cached.length)
+                    // An API cache can be warm while this client-version's OAuth
+                    // catalog is still cold. Give subscription discovery the same
+                    // bounded opportunity as an entirely empty picker.
+                    const oauthReady = modelCatalog.cachedList(routableKeys).length > 0 ||
+                        routableKeys.every(key => modelCatalog.hasUsablePickerSnapshot(key));
+                    if (cached.length && oauthReady)
                         models = cached;
                     else {
                         let timer;
                         try {
                             models = await Promise.race([refresh, new Promise(resolve => {
-                                    timer = setTimeout(() => resolve(pickerSnapshot()), 2000);
+                                    timer = setTimeout(() => {
+                                        // Do not let an incomplete API-only success replace the
+                                        // native client's complete cached catalog for minutes.
+                                        const missingSubscription = routableKeys.length > 0 && !modelCatalog.cachedList(routableKeys).length;
+                                        resolve(missingSubscription && routableKeys.some(key => !modelCatalog.hasUsablePickerSnapshot(key)) ? [] : pickerSnapshot());
+                                    }, 2000);
                                 })]);
                         }
                         finally {
@@ -1890,6 +1906,12 @@ async function handleRequestInner(state, req, res, traceId) {
                         }
                     }
                 }
+                // A completed failed fetch is still unknown, not a successful
+                // empty catalog. Never replace native subscription entries with
+                // an API-only success while a routable catalog is unknown.
+                if (!forceCatalogRefresh && !models.some(model => !/^(api|zdr)\//.test(model.slug)) &&
+                    routableKeys.some(key => !modelCatalog.hasUsablePickerSnapshot(key)))
+                    models = [];
                 res.setHeader("etag", setCatalogEtag(state, models));
                 writeJson(res, models.length ? 200 : 503, models.length
                     ? { models }
@@ -1948,20 +1970,45 @@ async function handleRequestInner(state, req, res, traceId) {
                         observations: state.subscriptionQuotaObservations ??= new Map(), now: state.now(), clearQuotaScheduler: a => state.preemptiveQuotaScheduler.clear(buildQuotaScheduleKey(a, context.family, context.model)) });
             }
         }
-        if (state.nativeOpenai && isResponsesRequest && context.model && context.model !== LUNA_RESERVE_MODEL && !isPinned) {
+        const primaryWorkspaceCandidates = () => new Map([...workspaceCandidates].filter(([index]) => {
+            const account = accountManager.getAccountByIndex(index);
+            // Catalog candidates can outlive credential invalidation while preparing a request.
+            return account && account.enabled !== false && !account.authInvalidatedAt &&
+                !policyDecision?.emergencyAccountIndexes?.has(index) && !policyDecision?.blockedAccountIndexes.has(index);
+        }));
+        const emergencyBackupsAllowed = () => state.nativeOpenai && isResponsesRequest &&
+            context.model !== LUNA_RESERVE_MODEL && primaryPoolFullyExhausted(primaryWorkspaceCandidates(), resetCreditState, state.now(), (index, scope) => {
+            const account = accountManager.getAccountByIndex(index);
+            return account ? quotaForScope(account, scope) : undefined;
+        });
+        const recoverPrimaryQuota = async () => {
+            if (!state.nativeOpenai || !isResponsesRequest || !context.model || context.model === LUNA_RESERVE_MODEL || isPinned)
+                return false;
             try {
-                await recoverResetQuota({ model: context.model, family: context.family, native: true, pinned: false, manager: accountManager,
-                    scopes: workspaceCandidates, quotaForScope, priorityByAccount: policyDecision?.priorityByAccount, preferredIndex: storageMeta.pinnedAccountIndex, service: createResetCreditService(accountManager),
-                    observations: state.subscriptionQuotaObservations ??= new Map(), now: state.now,
+                const observations = state.subscriptionQuotaObservations ??= new Map();
+                const recovered = await recoverResetQuota({ model: context.model, family: context.family, native: true, pinned: false, manager: accountManager,
+                    scopes: primaryWorkspaceCandidates(), quotaForScope, priorityByAccount: policyDecision?.priorityByAccount, preferredIndex: storageMeta.pinnedAccountIndex, service: createResetCreditService(accountManager),
+                    observations, quotaRejections: state.subscriptionQuotaRejections, now: state.now,
                     clearQuotaScheduler: account => state.preemptiveQuotaScheduler.clear(buildQuotaScheduleKey(account, context.family, context.model)),
                 });
+                try {
+                    resetCreditState = await loadResetCreditState();
+                }
+                catch {
+                    resetCreditState = null;
+                }
+                return recovered;
             }
             catch {
+                resetCreditState = null;
                 state.status.lastError = "Subscription reset recovery could not be confirmed; no further automatic redemption attempted.";
+                return false;
             }
-            // Recovery may have redeemed and written new reset state; the next request re-reads it.
-            state.readCache?.delete("reset-credits");
-        }
+            finally {
+                state.readCache?.delete("reset-credits");
+            }
+        };
+        await recoverPrimaryQuota();
         // A pinned Luna request can arrive after an earlier turn already proved
         // ordinary subscription quota exhausted. That persisted family marker
         // would make chooseAccount reject the hard pin before any upstream call,
@@ -2012,8 +2059,10 @@ async function handleRequestInner(state, req, res, traceId) {
         // alternative account, so exhausting that local heuristic can only reject a
         // request that the pinned account could serve. Transcription is not inference
         // and must not debit the Codex model pool or claim its inference circuit probe.
+        // Native subscriptions use upstream quota for admission; local scoring must
+        // not synthesize a 429 while actual subscription capacity remains.
         // Transcription uses credential-only admission below.
-        const bypassPoolTokenBucket = isPinned || isTranscribeRequest;
+        const bypassPoolTokenBucket = isPinned || isTranscribeRequest || (state.nativeOpenai && isResponsesRequest);
         const refundConsumedPoolToken = (account) => {
             if (!bypassPoolTokenBucket) {
                 accountManager.refundToken(account, context.family, context.model);
@@ -2105,8 +2154,10 @@ async function handleRequestInner(state, req, res, traceId) {
             return "retry";
         };
         let runtimeSelectionIterations = 0;
+        let recoveryRetriedAfterExhaustion = false;
         while ((isPinned ||
             attemptedIndexes.size < accountCount ||
+            (!isPinned && !recoveryRetriedAfterExhaustion) ||
             (isTranscribeRequest && !state.nativeOpenai && accountCount === 0 && !reloadedAfterNoAccount)) &&
             transientAttempts < transientAttemptLimit &&
             (!isPinned ||
@@ -2157,6 +2208,14 @@ async function handleRequestInner(state, req, res, traceId) {
                     }
                 }
                 const attemptedForSelection = new Set([...attemptedIndexes, ...catalogExcludedIndexes()]);
+                if (!isPinned && policyDecision?.emergencyAccountIndexes?.size) {
+                    const backupsAllowed = emergencyBackupsAllowed();
+                    if (!backupsAllowed)
+                        for (const index of policyDecision.emergencyAccountIndexes) {
+                            attemptedForSelection.add(index);
+                            accountSkipReasons.set(index, "policy: emergency backup reserved");
+                        }
+                }
                 if (isTranscribeRequest) {
                     const candidate = chooseTranscriptionAccount({
                         accountManager,
@@ -2194,12 +2253,13 @@ async function handleRequestInner(state, req, res, traceId) {
                     stickyBoostByAccount: rotationStickyBoost,
                     pidOffsetEnabled: state.pidOffsetEnabled,
                     schedulingStrategy: state.schedulingStrategy,
-                    // Only on a RETRY pass. The first pass still honors a cooldown
-                    // another request left on the pin, so an already-cooling pinned
-                    // account 503s immediately as before; from the second pass on,
-                    // this request's own retry budget outranks the cooldown it just
-                    // created for itself.
-                    allowPinnedCooldown: isPinned && transientAttempts > 0,
+                    // A shared network cooldown is not evidence that the pinned
+                    // credentials cannot serve independent concurrent work. Let each
+                    // new request try; its own retries remain bounded and backed off.
+                    // Other initial cooldowns still block, as do quota/auth/policy
+                    // checks and the circuit admission immediately after selection.
+                    allowPinnedCooldown: isPinned && (transientAttempts > 0 ||
+                        (typeof pinnedIndex === "number" && accountManager.getAccountByIndex(pinnedIndex)?.cooldownReason === "network-error")),
                 });
                 return result;
             };
@@ -2227,6 +2287,20 @@ async function handleRequestInner(state, req, res, traceId) {
             for (const index of catalogExcludedIndexes())
                 accountSkipReasons.set(index, "model-not-supported");
             if (!selected) {
+                // A 429 can be the first evidence that cached ordinary capacity is gone.
+                // Recheck once before failing; only an explicit pre-inference rejection
+                // reaches this path, never an ambiguous or already-streaming generation.
+                if (!isPinned && !recoveryRetriedAfterExhaustion) {
+                    recoveryRetriedAfterExhaustion = true;
+                    const backupsWereAllowed = emergencyBackupsAllowed();
+                    if (await recoverPrimaryQuota()) {
+                        attemptedIndexes.clear();
+                        accountSkipReasons.clear();
+                        continue;
+                    }
+                    if (!backupsWereAllowed && emergencyBackupsAllowed())
+                        continue;
+                }
                 if (isTranscribeRequest &&
                     !state.nativeOpenai &&
                     !reloadedAfterNoAccount) {
@@ -2326,10 +2400,12 @@ async function handleRequestInner(state, req, res, traceId) {
             }
             attemptedIndexes.add(selected.index);
             const quotaScheduleKey = buildQuotaScheduleKey(selected, context.family, context.model);
+            const selectedScope = workspaceCandidates.get(selected.index)?.[0];
+            const nativePermission = selectedScope && hasFreshOrdinaryUsagePermission(quotaForScope(selected, selectedScope), state.now());
             const preemptiveDeferral = state.preemptiveQuotaScheduler.getDeferral(quotaScheduleKey, state.now());
             if (!isTranscribeRequest &&
                 context.model !== LUNA_RESERVE_MODEL &&
-                preemptiveDeferral.defer &&
+                !nativePermission && preemptiveDeferral.defer &&
                 preemptiveDeferral.waitMs > 0) {
                 accountSkipReasons.set(selected.index, preemptiveDeferral.reason ?? "quota-near-exhaustion");
                 exhaustionReason = "rate-limit";
@@ -2474,7 +2550,8 @@ async function handleRequestInner(state, req, res, traceId) {
                 continue;
             }
             let pendingScopes = workspaceCandidates.get(refreshed.account.index);
-            if (isTranscribeRequest) {
+            // Routes without model-catalog preparation still use the selected enabled workspace.
+            if (isImageRequest || isTranscribeRequest || isThreadGoalRequest) {
                 pendingScopes = workspaceModelScopes(refreshed.account)
                     .filter((scope) => scope.routable)
                     .sort((a, b) => Number(b.selected) - Number(a.selected) || Number(b.bound) - Number(a.bound));
@@ -2531,14 +2608,10 @@ async function handleRequestInner(state, req, res, traceId) {
                     : undefined;
                 const disk = latest?.accounts.find(item => item.recordId && item.recordId === refreshed.account.recordId)
                     ?? latest?.accounts.find(item => item.accountId === refreshed.account.accountId && sanitizeEmail(item.email) === sanitizeEmail(refreshed.account.email)) ?? retained;
-                const workspace = disk?.workspaces?.find(item => item.id.trim() === accountId);
-                // Derive the stored binding exactly as workspaceModelScopes does: trimmed,
-                // falling back to the token's workspace claim when no id was stored.
-                // A stored record carries accessToken; the transient-grace fallback is a live account (access).
                 const diskToken = disk?.accessToken ?? disk?.access;
-                const diskBoundId = disk ? disk.accountId?.trim() || extractAccountId(diskToken)?.trim() : undefined;
                 const stillEligible = disk && disk.enabled !== false && !disk.authInvalidatedAt &&
-                    (workspace ? workspace.enabled !== false : accountId === diskBoundId);
+                    workspaceModelScopes({ ...disk, index: refreshed.account.index, access: diskToken })
+                        .some(scope => scope.routable && scope.accountId === accountId);
                 if (!stillEligible) {
                     writeJson(res, 503, { error: { code: "routing_configuration_changed", message: "Routing eligibility changed while preparing the request. Retry with the current configuration." } });
                     return;
@@ -2711,7 +2784,9 @@ async function handleRequestInner(state, req, res, traceId) {
                     const key = JSON.stringify([requestScope.id, context.model]);
                     if (observations.size >= 1000 && !observations.has(key))
                         observations.delete(observations.keys().next().value ?? "");
-                    observations.set(key, { ...merged, model: context.model ?? "unknown", planType: planType ?? previous?.planType });
+                    observations.set(key, { ...merged, model: context.model ?? "unknown", planType: planType ?? previous?.planType,
+                        ...(snapshot.status === 200 && hasFreshOrdinaryUsagePermission(previous, state.now()) ? { ordinaryUsageAllowed: true, ordinaryUsageCheckedAt: previous?.ordinaryUsageCheckedAt ?? previous?.updatedAt } : {}),
+                    });
                 }
             };
             const quotaSnapshot = readQuotaSchedulerSnapshot(upstream.headers, upstream.status, state.now());
@@ -2812,6 +2887,17 @@ async function handleRequestInner(state, req, res, traceId) {
                     if (outcome === "retry")
                         continue;
                 }
+                if (state.nativeOpenai && isResponsesRequest && requestScope && context.model !== LUNA_RESERVE_MODEL && subscriptionQuotaExceeded && !modelAtCapacity) {
+                    // A body-only quota rejection is newer evidence than an earlier
+                    // native permission. Record no invented quota percentage or permission.
+                    // An older in-flight success cannot clear this hint; newer native
+                    // permission checks or its bounded lifetime invalidate it during recovery.
+                    const rejections = state.subscriptionQuotaRejections ??= new Map();
+                    const key = JSON.stringify([requestScope.id, context.model]);
+                    if (rejections.size >= 1000 && !rejections.has(key))
+                        rejections.delete(rejections.keys().next().value ?? "");
+                    rejections.set(key, { key: requestScope.id, accountId: requestScope.accountId, observedAt: state.now() });
+                }
                 if (context.model !== LUNA_RESERVE_MODEL && subscriptionQuotaExceeded) {
                     state.preemptiveQuotaScheduler.markRateLimited(quotaScheduleKey, retryAfterMs, state.now());
                 }
@@ -2824,7 +2910,7 @@ async function handleRequestInner(state, req, res, traceId) {
                     (context.model === "gpt-6-luna" || context.model === "gpt-5.6-luna")) {
                     const confirmedKey = confirmedQuotaExhaustionKey(context.family, context.model);
                     const confirmedResetAt = state.now() +
-                        Math.min(Math.max(0, Math.floor(retryAfterMs)), MAX_RATE_LIMIT_DELAY_MS);
+                        Math.min(Math.max(0, Math.floor(retryAfterMs)), RATE_LIMIT_CACHE_TTL_MS);
                     rateLimitState.account.rateLimitResetTimes[confirmedKey] = Math.max(rateLimitState.account.rateLimitResetTimes[confirmedKey] ?? 0, confirmedResetAt);
                 }
                 rateLimitState.accountManager.saveToDiskDebounced();
@@ -2864,7 +2950,11 @@ async function handleRequestInner(state, req, res, traceId) {
                 }
                 exhaustionReason = "rate-limit";
                 capabilityRejectionIsLatest = false;
-                transientAttempts += 1;
+                // Account-local throttles are bounded by distinct accounts/workspaces.
+                // They must not spend the network/server budget before a usable sibling.
+                // Pins and model-wide capacity failures retain the transient bound.
+                if (isPinned || modelAtCapacity)
+                    transientAttempts += 1;
                 transientExhaustionReason = "rate-limit";
                 state.status.retries += 1;
                 noteRotation();
@@ -2874,9 +2964,9 @@ async function handleRequestInner(state, req, res, traceId) {
                 const bodyText = await readErrorBody(upstream, state.streamStallTimeoutMs);
                 const errorCode = extractErrorCodeFromBody(bodyText);
                 if (isWorkspaceDisabledError(upstream.status, errorCode, bodyText)) {
-                    if (requestScope && refreshed.account.workspaces?.length) {
+                    if (requestScope?.storedWorkspaceId !== undefined) {
                         const workspaceState = responseStateTarget();
-                        if (workspaceState.accountManager.disableWorkspace(workspaceState.account, requestScope.accountId))
+                        if (workspaceState.accountManager.disableWorkspace(workspaceState.account, requestScope.storedWorkspaceId))
                             workspaceState.accountManager.saveToDiskDebounced();
                         pendingScopes?.shift();
                         refundConsumedPoolToken(refreshed.account);
@@ -3111,7 +3201,7 @@ async function handleRequestInner(state, req, res, traceId) {
             // No-op when no reason is recorded, so the hot path stays write-free.
             if (!isTranscribeRequest) {
                 const quotaDeferral = state.preemptiveQuotaScheduler.getDeferral(quotaScheduleKey, state.now());
-                const nearExhaustionWaitMs = context.model === LUNA_RESERVE_MODEL
+                const nearExhaustionWaitMs = (context.model === LUNA_RESERVE_MODEL || (requestScope && hasFreshOrdinaryUsagePermission(quotaForScope(refreshed.account, requestScope), state.now())))
                     ? 0
                     : quotaDeferral.defer
                         ? quotaDeferral.waitMs
@@ -3382,9 +3472,13 @@ async function handleRequestInner(state, req, res, traceId) {
                     // Read live account state, not only selection skip reasons. The final
                     // refresh attempt can install an auth cooldown after the last selection
                     // pass, so that blocker may never have been written to accountSkipReasons.
+                    const backupsReserved = !isPinned && !emergencyBackupsAllowed();
                     for (const account of accountManager.getAccountsSnapshot()) {
                         if (policyDecision?.blockedAccountIndexes.has(account.index))
                             continue;
+                        // Selection never offers a reserved backup, so it is not ready capacity.
+                        if (backupsReserved && policyDecision?.emergencyAccountIndexes?.has(account.index))
+                            continue;
                         if (account.enabled === false)
                             continue;
                         if (!accountManager.hasEnabledWorkspaces(account))
@@ -3409,6 +3503,11 @@ async function handleRequestInner(state, req, res, traceId) {
                     return minWaitMs ?? 0;
                 })()
                 : undefined;
+            const ineligibleAccountIndexes = new Set(policyDecision?.blockedAccountIndexes ?? []);
+            if (!isPinned && !emergencyBackupsAllowed()) {
+                for (const index of policyDecision?.emergencyAccountIndexes ?? [])
+                    ineligibleAccountIndexes.add(index);
+            }
             writePoolExhausted({
                 res,
                 accountManager,
@@ -3416,6 +3515,7 @@ async function handleRequestInner(state, req, res, traceId) {
                 model: context.model,
                 reason: exhaustionReason,
                 retryAfterMs: transcriptionRetryAfterMs,
+                ineligibleAccountIndexes,
                 accountSkipReasons: Object.fromEntries([...accountSkipReasons.entries()].map(([index, reason]) => [
                     String(index),
                     reason,

package/dist/lib/schemas.d.ts

@@ -5,6 +5,11 @@
  */
 import { z } from "zod";
 export declare const PluginConfigSchema: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        en: "en";
+        zh: "zh";
+    }>>;
     codexMode: z.ZodOptional<z.ZodBoolean>;
     codexRuntimeRotationProxy: z.ZodOptional<z.ZodBoolean>;
     codexTuiV2: z.ZodOptional<z.ZodBoolean>;

package/dist/lib/schemas.js

@@ -22,6 +22,7 @@ function schemaLog() {
 // Plugin Configuration Schema
 // ============================================================================
 export const PluginConfigSchema = z.object({
+    locale: z.enum(["auto", "en", "zh"]).optional(),
     codexMode: z.boolean().optional(),
     codexRuntimeRotationProxy: z.boolean().optional(),
     codexTuiV2: z.boolean().optional(),

package/dist/lib/storage/snapshot-merge.js

@@ -26,7 +26,9 @@ const byId = (rows) => new Map((rows ?? []).map(row => [row.id, row]));
 /**
  * Merge workspaces by id, never by array position. Fields changed on one side
  * win; enabled/disabledAt move as one unit, and when both sides changed it an
- * intentional re-enable wins over a disable. Other two-sided edits conflict.
+ * intentional re-enable wins over a disable. Concurrent disables preserve an
+ * operator exclusion (no disabledAt) over a recoverable runtime health marker.
+ * Other two-sided edits conflict.
  * Removal follows the account rule: a record removed on either side stays
  * removed.
  */
@@ -44,7 +46,13 @@ function mergeWorkspaces(base, disk, local) {
             continue;
         }
         const state = (row) => ({ enabled: row?.enabled, disabledAt: row?.disabledAt });
-        const stateSource = equal(state(b), state(l)) ? d : equal(state(b), state(d)) ? l : d.enabled !== false ? d : l.enabled !== false ? l : (d.disabledAt ?? 0) >= (l.disabledAt ?? 0) ? d : l;
+        const stateSource = equal(state(b), state(l)) ? d
+            : equal(state(b), state(d)) ? l
+                : d.enabled !== false ? d
+                    : l.enabled !== false ? l
+                        : d.disabledAt === undefined ? d
+                            : l.disabledAt === undefined ? l
+                                : d.disabledAt >= l.disabledAt ? d : l;
         const pick = (row) => ({ ...row, enabled: stateSource.enabled, disabledAt: stateSource.disabledAt });
         const merged = mergeValue(b ? pick(b) : undefined, pick(d), pick(l));
         if (merged.disabledAt === undefined)
@@ -54,7 +62,7 @@ function mergeWorkspaces(base, disk, local) {
     const currentId = (row) => row.workspaces?.[row.currentWorkspaceIndex ?? 0]?.id;
     const chosen = currentId(local) !== currentId(base) ? currentId(local) : currentId(disk);
     let index = workspaces.findIndex(row => row.id === chosen);
-    if (index < 0 || workspaces[index]?.enabled === false) {
+    if (index < 0) {
         const enabled = workspaces.findIndex(row => row.enabled !== false);
         index = enabled >= 0 ? enabled : Math.max(index, 0);
     }
@@ -86,7 +94,10 @@ function mergeRuntimeAccount(base, disk, local) {
         const before = base.rateLimitResetTimes?.[key], a = disk.rateLimitResetTimes?.[key], b = local.rateLimitResetTimes?.[key];
         // An explicit clear is an operation, not a new observation.
         const clear = before !== undefined && ((a === undefined && b === before) || (b === undefined && a === before) || (a === undefined && b === undefined));
-        const value = clear ? undefined : Math.max(a ?? 0, b ?? 0);
+        // A side that kept the baseline made no observation, so the other side's
+        // value wins even when lower (e.g. a load-time revalidation bound).
+        // Only two concurrent observations keep the later deadline.
+        const value = clear ? undefined : a === before ? b : b === before ? a : Math.max(a ?? 0, b ?? 0);
         if (value !== undefined)
             limits[key] = value;
     }

package/dist/lib/web-dashboard-html.d.ts

@@ -0,0 +1 @@
+export declare function renderDashboardHtml(token: string | null, locale?: "en" | "zh"): string;

package/dist/lib/web-dashboard-html.js

@@ -0,0 +1,66 @@
+const DASHBOARD_HTML = `
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Codex Multi-Auth · 号池监控</title>
+<style>
+:root{color-scheme:dark;--bg:#09111f;--panel:#101c2f;--panel2:#14243b;--line:#223653;--text:#edf5ff;--muted:#8ea5c2;--green:#36d399;--amber:#f7c95c;--red:#fb7185;--blue:#65a8ff;--shadow:0 14px 40px rgba(0,0,0,.25)}
+*{box-sizing:border-box}body{margin:0;background:radial-gradient(circle at 20% 0,#17345a 0,transparent 38%),var(--bg);color:var(--text);font:14px/1.5 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+.shell{max-width:1440px;margin:0 auto;padding:28px 26px 48px}.top{display:flex;justify-content:space-between;align-items:flex-start;gap:18px;margin-bottom:26px}.brand{display:flex;gap:14px;align-items:center}.mark{width:44px;height:44px;border-radius:13px;display:grid;place-items:center;background:linear-gradient(135deg,#4b8dff,#55d6ae);color:#07111f;font-weight:900;font-size:18px;box-shadow:0 8px 24px #3b82f655}.eyebrow{color:var(--blue);font-size:12px;letter-spacing:.12em;text-transform:uppercase}.title{font-size:28px;font-weight:800;letter-spacing:-.03em}.subtitle{color:var(--muted);margin-top:2px}.actions{display:flex;gap:10px;align-items:center}.button{border:1px solid var(--line);background:var(--panel);color:var(--text);border-radius:9px;padding:9px 13px;cursor:pointer}.button:hover{border-color:var(--blue);background:var(--panel2)}.live{display:flex;gap:7px;align-items:center;color:var(--muted);font-size:12px}.dot{width:8px;height:8px;border-radius:50%;background:var(--green);box-shadow:0 0 10px var(--green)}.dot.off{background:var(--red);box-shadow:0 0 10px var(--red)}
+.summary{display:grid;grid-template-columns:repeat(5,minmax(0,1fr));gap:12px;margin-bottom:22px}.card,.panel{background:linear-gradient(145deg,#122139dd,#0e192add);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow)}.card{padding:17px}.label{color:var(--muted);font-size:12px}.value{font-size:26px;font-weight:800;margin-top:7px}.value.green{color:var(--green)}.value.amber{color:var(--amber)}.value.red{color:var(--red)}.value.blue{color:var(--blue)}
+.grid{display:grid;grid-template-columns:minmax(0,1.7fr) minmax(280px,.7fr);gap:18px;align-items:start}.panel{padding:18px}.panel-head{display:flex;justify-content:space-between;align-items:center;margin-bottom:12px}.panel-title{font-size:16px;font-weight:750}.panel-meta{color:var(--muted);font-size:12px}.accounts{display:grid;gap:10px}.account{padding:15px;border:1px solid var(--line);border-radius:11px;background:#0e1a2caa}.account-head{display:flex;justify-content:space-between;gap:12px;align-items:flex-start}.account-name{font-weight:700;overflow-wrap:anywhere}.account-meta{color:var(--muted);font-size:12px;margin-top:3px}.badge{border-radius:99px;padding:3px 9px;font-size:11px;white-space:nowrap;border:1px solid #ffffff18}.badge.ready{color:var(--green);background:#36d39918}.badge.login{color:var(--red);background:#fb718518}.badge.disabled{color:var(--muted);background:#8ea5c218}.badge.current{color:var(--blue);background:#65a8ff18}.account-stats{display:grid;grid-template-columns:1fr 1fr 120px;gap:15px;margin-top:14px}.quota{min-width:0}.quota-row{display:flex;justify-content:space-between;gap:7px;color:var(--muted);font-size:11px;margin-top:8px}.bar{height:8px;border-radius:99px;background:#243752;overflow:hidden;margin-top:5px}.fill{height:100%;border-radius:99px;background:linear-gradient(90deg,var(--green),#7de2ab)}.fill.warn{background:linear-gradient(90deg,var(--amber),#ff9e5c)}.fill.danger{background:linear-gradient(90deg,var(--red),#ffadad)}.risk{text-align:right}.risk-num{font-size:23px;font-weight:800}.risk-low{color:var(--green)}.risk-medium{color:var(--amber)}.risk-high{color:var(--red)}.reason{color:var(--muted);font-size:12px;margin-top:8px;overflow-wrap:anywhere}.empty{padding:35px;text-align:center;color:var(--muted)}.subhead{margin:14px 0 4px;color:var(--muted);font-size:11px;letter-spacing:.1em;text-transform:uppercase}.side{display:grid;gap:18px}.kv{display:flex;justify-content:space-between;gap:12px;padding:9px 0;border-bottom:1px solid #ffffff0d}.kv:last-child{border-bottom:0}.kv b{font-weight:650;text-align:right;overflow-wrap:anywhere}.notice{padding:12px;border-radius:10px;background:#f7c95c13;border:1px solid #f7c95c3d;color:#fbe6a2;font-size:12px}.error{padding:12px;border-radius:10px;background:#fb718513;border:1px solid #fb71853d;color:#ffc2cb;font-size:12px}.foot{color:var(--muted);font-size:12px;margin-top:20px;text-align:center}
+@media(max-width:1050px){.summary{grid-template-columns:repeat(3,minmax(0,1fr))}.grid{grid-template-columns:1fr}.side{grid-template-columns:repeat(2,minmax(0,1fr))}}@media(max-width:680px){.shell{padding:18px 13px 36px}.top{display:block}.actions{margin-top:15px;justify-content:space-between}.summary{grid-template-columns:repeat(2,minmax(0,1fr))}.account-stats{grid-template-columns:1fr 1fr}.risk{text-align:left}.side{grid-template-columns:1fr}.title{font-size:23px}}
+</style>
+</head>
+<body>
+<main class="shell">
+<header class="top"><div class="brand"><div class="mark">MA</div><div><div class="eyebrow">Codex Multi-Auth</div><div class="title" data-i18n="title">号池实时监控</div><div class="subtitle" data-i18n="subtitle">账号、配额与轮换状态</div></div></div><div class="actions"><div class="live"><span id="dot" class="dot"></span><span id="connection" data-i18n="connecting">连接中…</span></div><button id="lang" class="button">EN</button><button id="refresh" class="button" data-i18n="refresh">刷新</button></div></header>
+<section id="summary" class="summary"></section>
+<div id="error" class="error" hidden></div>
+<section class="grid"><section class="panel"><div class="panel-head"><div class="panel-title" data-i18n="accounts">账号池</div><div id="updated" class="panel-meta">—</div></div><div id="accounts" class="accounts"></div></section><aside class="side"><section class="panel"><div class="panel-head"><div class="panel-title" data-i18n="routing">路由</div></div><div id="routing"></div></section><section class="panel"><div class="panel-head"><div class="panel-title" data-i18n="runtime">运行时</div></div><div id="runtime"></div></section></aside></section>
+<div class="foot" data-i18n="foot">数据来自本机号池；页面默认仅监听回环地址，按 Ctrl-C 停止服务。</div>
+</main>
+<script>
+(function(){
+  var token="__CMA_TOKEN__";
+  var lang="__CMA_LANG__";
+  var text={zh:{title:"号池实时监控",subtitle:"账号、配额与轮换状态",connecting:"连接中…",connected:"实时连接",offline:"连接中断",refresh:"刷新",accounts:"账号池",apiAccounts:"API/ZDR 账号",routing:"路由",runtime:"运行时",total:"总账号",ready:"可用",login:"需重新登录",disabled:"已禁用",enabled:"已启用",recommend:"推荐账号",active:"当前账号",requests:"请求",success:"成功",failed:"失败",last:"最近请求",quota:"配额",risk:"风险",unknown:"未知",reason:"原因",primary:"主窗口",secondary:"次窗口",priority:"优先级",models:"可见模型",foot:"数据来自本机号池；页面默认仅监听回环地址，按 Ctrl-C 停止服务。"},en:{title:"Pool live monitor",subtitle:"Accounts, quota and routing",connecting:"Connecting…",connected:"Live",offline:"Disconnected",refresh:"Refresh",accounts:"Account pool",apiAccounts:"API/ZDR accounts",routing:"Routing",runtime:"Runtime",total:"Accounts",ready:"Ready",login:"Re-login needed",disabled:"Disabled",enabled:"Enabled",recommend:"Recommended",active:"Current",requests:"Requests",success:"Success",failed:"Failed",last:"Last request",quota:"Quota",risk:"Risk",unknown:"Unknown",reason:"Reason",primary:"primary",secondary:"secondary",priority:"priority",models:"visible models",foot:"Data comes from the local pool; the server listens on loopback by default. Ctrl-C stops it."}};
+  function t(k){return text[lang][k]||k}
+  function label(v){var s=String(v==null?"":v);return lang==="zh"?s.replace(/^Account /,"账号 ").replace(/Token account/g,"令牌账号").replace(/, id:/g,"，ID:").replace(/, /g,"，"):s}
+  function reasonText(v){var s=String(v==null?"—":v);if(lang!=="zh")return s;return s.replace("token-invalid — re-login needed","令牌无效——需要重新登录").replace("primary quota ","主窗口配额 ").replace(" secondary quota "," 次窗口配额 ").replace(" used","已使用").replace("account is disabled","账号已禁用").replace("quota cache exhausted","配额缓存已用尽")}
+  function esc(v){return String(v==null?"":v).replace(/[&<>"']/g,function(c){return({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"})[c]})}
+  function api(path){return path+(path.indexOf("?")>=0?"&":"?")+"token="+encodeURIComponent(token)}
+  function ago(ms){if(typeof ms!=="number"||!isFinite(ms))return "—";var s=Math.max(0,Math.round(ms/1000));if(s<60)return s+"s";if(s<3600)return Math.floor(s/60)+"m";if(s<86400)return Math.floor(s/3600)+"h";return Math.floor(s/86400)+"d"}
+  function statusClass(a){var m=(a.markers||[]).join(" ");if(a.enabled===false)return "disabled";if(/invalid|sign-in|re-login/i.test(m))return "login";return "ready"}
+  function winLabel(w,key){var m=w&&w.windowMinutes;if(typeof m==="number"&&isFinite(m)&&m>0){var zh=lang==="zh";if(m%1440===0)return (m/1440)+(zh?"天":"d");if(m%60===0)return (m/60)+(zh?"小时":"h");return m+(zh?"分钟":"m")}return t(key)}
+  function bar(window,key){if(!window||typeof window.usedPercent!=="number")return '<div class="label">'+t("unknown")+"</div>";var p=Math.max(0,Math.min(100,Math.round(window.usedPercent)));var cls=p>=90?" danger":p>=75?" warn":"";return '<div class="quota-row"><span>'+esc(winLabel(window,key))+" "+t("quota")+'</span><span>'+p+"% / "+(100-p)+"%</span></div><div class="bar"><div class="fill'+cls+'" style="width:'+p+'%"></div></div>'}
+  function draw(data){window.__data=data;var all=data.accounts||[];var ready=all.filter(function(a){return a.enabled!==false&&statusClass(a)==="ready"}).length;var login=all.filter(function(a){return statusClass(a)==="login"}).length;var disabled=all.filter(function(a){return a.enabled===false}).length;var rec=data.recommendedIndex==null?"—":"#"+(data.recommendedIndex+1);var rt=data.runtime||{};document.getElementById("summary").innerHTML='<div class="card"><div class="label">'+t("total")+'</div><div class="value blue">'+(data.totalAccountCount||all.length)+'</div></div><div class="card"><div class="label">'+t("ready")+'</div><div class="value green">'+ready+'</div></div><div class="card"><div class="label">'+t("login")+'</div><div class="value red">'+login+'</div></div><div class="card"><div class="label">'+t("disabled")+'</div><div class="value">'+disabled+'</div></div><div class="card"><div class="label">'+t("recommend")+'</div><div class="value amber">'+rec+'</div></div>';
+    document.getElementById("accounts").innerHTML=all.length?all.map(function(a){var sub=a.subscription||{};var q=a.quota||{};var risk=a.forecastRiskScore==null?"—":a.forecastRiskScore+"/100";var rl=a.forecastRiskLevel||"low";var badges=(a.markers||[]).map(function(m){return '<span class="badge '+(/current/.test(m)?"current":statusClass(a))+'">'+esc(label(m))+'</span>'}).join(" ");return '<article class="account"><div class="account-head"><div><div class="account-name">'+esc(label(a.label||("Account "+(a.index+1))))+'</div><div class="account-meta">'+esc(sub.planLabel||t("unknown"))+" · "+esc(label(sub.selectedWorkspace||""))+'</div></div><div>'+badges+' <span class="badge '+statusClass(a)+'">'+(statusClass(a)==="ready"?t("ready"):statusClass(a)==="login"?t("login"):t("disabled"))+'</span></div></div><div class="account-stats"><div class="quota">'+bar(q.primary,"primary")+bar(q.secondary,"secondary")+'</div><div><div class="label">'+t("last")+'</div><div class="value" style="font-size:18px">'+ago(a.lastInferenceRequestAt?Date.now()-a.lastInferenceRequestAt:null)+'</div><div class="reason">'+t("reason")+": "+esc(reasonText(a.reason||"—"))+'</div></div><div class="risk"><div class="label">'+t("risk")+'</div><div class="risk-num risk-'+esc(rl)+'">'+esc(risk)+"</div></div></div></article>"}).join(""):'<div class="empty">'+t("unknown")+"</div>";
+    var apis=(data.apiAccounts||[]).map(function(a){return '<article class="account"><div class="account-head"><div><div class="account-name">'+esc(label(a.label||"API"))+'</div><div class="account-meta">'+esc(a.kind||"api")+" · "+t("priority")+" "+esc(a.priority==null?"—":a.priority)+'</div></div><div><span class="badge '+(a.enabled===false?"disabled":"ready")+'">'+(a.enabled===false?t("disabled"):t("enabled"))+'</span></div></div><div class="account-meta">'+t("models")+": "+esc((a.visibleModels||[]).length||"—")+" · "+t("last")+": "+ago(a.lastInferenceRequestAt?Date.now()-a.lastInferenceRequestAt:null)+'</div></article>'}).join("");
+    if(apis)document.getElementById("accounts").innerHTML+='<div class="subhead">'+t("apiAccounts")+"</div>"+apis;
+    var recReason=data.recommendationReason||"—";document.getElementById("routing").innerHTML='<div class="kv"><span>'+t("active")+'</span><b>'+esc(data.activeIndex==null?"—":"#"+(data.activeIndex+1))+'</b></div><div class="kv"><span>'+t("recommend")+'</span><b>'+esc(rec)+"</b></div><div class="kv"><span>'+t("reason")+'</span><b>'+esc(recReason)+'</b></div>';
+    document.getElementById("runtime").innerHTML='<div class="kv"><span>'+t("requests")+'</span><b>'+esc(rt.responsesRequests==null?"—":rt.responsesRequests)+'</b></div><div class="kv"><span>'+t("success")+'</span><b>'+esc(rt.successfulRequests==null?"—":rt.successfulRequests)+'</b></div><div class="kv"><span>'+t("failed")+'</span><b>'+esc(rt.failedRequests==null?"—":rt.failedRequests)+'</b></div><div class="kv"><span>'+t("last")+'</span><b>'+esc(data.runtimeInUseIndex==null?"—":"#"+(data.runtimeInUseIndex+1))+'</b></div>';
+    document.getElementById("updated").textContent=new Date().toLocaleTimeString();document.getElementById("error").hidden=true;document.getElementById("dot").className="dot";document.getElementById("connection").textContent=t("connected")
+  }
+  function setLang(){document.documentElement.lang=lang==="zh"?"zh-CN":"en";document.querySelectorAll("[data-i18n]").forEach(function(e){e.textContent=t(e.getAttribute("data-i18n"))});document.getElementById("lang").textContent=lang==="zh"?"EN":"中文";if(window.__data)draw(window.__data)}
+  function failed(e){document.getElementById("error").hidden=false;document.getElementById("error").textContent=e&&e.message?e.message:"Request failed";document.getElementById("dot").className="dot off";document.getElementById("connection").textContent=t("offline")}
+  function load(){fetch(api("/api/status"),{cache:"no-store"}).then(function(r){if(!r.ok)throw Error("HTTP "+r.status);return r.json()}).then(draw).catch(failed)}
+  document.getElementById("refresh").onclick=load;document.getElementById("lang").onclick=function(){lang=lang==="zh"?"en":"zh";setLang()};setLang();load();try{var es=new EventSource(api("/events"));es.onmessage=function(e){try{draw(JSON.parse(e.data))}catch(_){}};es.onerror=function(){document.getElementById("dot").className="dot off";document.getElementById("connection").textContent=t("offline")}}catch(_){setInterval(load,5000)}
+})();
+</script>
+</body>
+</html>`;
+export function renderDashboardHtml(token, locale = "zh") {
+    const safeToken = JSON.stringify(token ?? "")
+        .slice(1, -1)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+    return DASHBOARD_HTML
+        .replace("__CMA_TOKEN__", safeToken)
+        .replace("__CMA_LANG__", locale === "zh" ? "zh" : "en");
+}

package/dist/lib/web-dashboard.d.ts

@@ -0,0 +1,36 @@
+import { type Server, type ServerResponse } from "node:http";
+import { type OutputLocale } from "./locale.js";
+export interface WebStatusSnapshot {
+    [key: string]: unknown;
+}
+export interface WebServerOptions {
+    host?: string;
+    port?: number;
+    token?: string | null;
+    refreshMs?: number;
+    getStatus: () => Promise<WebStatusSnapshot>;
+    openBrowser?: (url: string) => void;
+    locale?: OutputLocale;
+    /** Called when an SSE client is dropped for falling behind on broadcasts. */
+    onSseClientDrop?: (client: ServerResponse) => void;
+}
+export interface WebServerHandle {
+    server: Server;
+    url: string;
+    token: string | null;
+    close: () => Promise<void>;
+}
+export declare function startWebServer(options: WebServerOptions): Promise<WebServerHandle>;
+export declare function runWebCommand(args: string[], deps: {
+    getStatus: () => Promise<WebStatusSnapshot>;
+    logInfo?: (message: string) => void;
+    openBrowser?: (url: string) => void;
+    locale?: OutputLocale;
+}): Promise<number>;
+export declare function parseWebCommandArgs(args: string[]): {
+    host: string;
+    port: number;
+    token: string | null;
+    refreshMs: number;
+    openBrowser: boolean;
+};