@foxden-app/foxclaw 0.5.21 → 0.5.23

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.23 - 2026-06-09
+
+### 中文
+- 补齐切换后验证路径：如果目标候选在验证 rate-limit usage 时返回 usage/rate/quota/billing/credits limit，FoxClaw 会恢复到原 auth，但不会把目标候选标记为 `?`，也不会触发自动剔除。
+- 这让额度耗尽在自动轮换、手动切换和验证失败提示里都保持同一语义：它只是暂时没额度，不是凭据失效。
+
+### English
+- Completed the post-switch validation path: if the selected candidate returns a usage/rate/quota/billing/credits limit while validating rate-limit usage, FoxClaw restores the previous auth but does not mark the selected candidate `?` or auto-delete it.
+- Quota exhaustion now has the same meaning across automatic rotation, manual switching, and validation failure messages: temporarily out of quota, not an invalid credential.
+
+## 0.5.22 - 2026-06-09
+
+### 中文
+- Codex 报 `usageLimitExceeded`、`You've hit your usage limit`、usage/rate/quota/billing/credits limit 这类额度耗尽时，不再把当前 auth 候选标记为需要修复，也不会触发 `AUTH_AUTO_DELETE_NEEDS_REPAIR` 的自动剔除和跨节点删除。
+- 额度耗尽仍会临时避开当前候选，切到另一个维护中的候选重试；提示文案改为“Codex 额度限制”，不再误写成 “Codex auth 问题”。
+
+### English
+- Codex quota exhaustion such as `usageLimitExceeded`, `You've hit your usage limit`, usage/rate/quota/billing/credits limit is no longer treated as an invalid auth candidate, so it does not mark `needs_repair` or trigger `AUTH_AUTO_DELETE_NEEDS_REPAIR` auto-delete / cross-node delete.
+- Quota exhaustion still temporarily skips the current candidate and retries with another maintained candidate; notifications now call this a Codex usage limit instead of an auth problem.
+
 ## 0.5.21 - 2026-06-09
 
 ### 中文

package/dist/controller/controller.js

@@ -1390,7 +1390,8 @@ export class BridgeSessionCore {
             : threadId
                 ? this.findActiveTurnsByThreadId(threadId)
                 : [];
-        const isAuthRotationError = isCodexAuthRotationError(params);
+        const authRotationReason = classifyCodexAuthRotationError(params);
+        const isAuthRotationError = authRotationReason !== null;
         const willRetry = params?.willRetry === true;
         const active = isAuthRotationError
             ? activeTurns.find(turn => turn.authRetry !== null) ?? activeTurns.find(turn => !turn.isObserved) ?? activeTurns[0] ?? null
@@ -1403,12 +1404,13 @@ export class BridgeSessionCore {
         else if (turnId) {
             this.pendingTurnErrors.set(turnId, message);
         }
-        if (isAuthRotationError && !willRetry && active?.authRetry) {
+        if (authRotationReason && !willRetry && active?.authRetry) {
             const scopeId = active.scopeId;
             if (scopeId) {
                 this.pendingAuthRotation = {
                     scopeId,
                     reason: message,
+                    reasonKind: authRotationReason,
                     retry: cloneAuthRetryContext(active.authRetry),
                 };
             }
@@ -5504,7 +5506,7 @@ export class BridgeSessionCore {
             const failedTargets = rotation.retry?.failedAuthTargets ?? this.authRotationFailedTargets;
             const locale = this.localeForChat(rotation.scopeId);
             const current = (await this.listCodexAuthState()).candidates.find(candidate => candidate.isCurrent) ?? null;
-            if (current) {
+            if (current && rotation.reasonKind === 'auth_invalid') {
                 const recoveredCurrent = await this.recoverCodexAuthCandidate(current.name);
                 if (recoveredCurrent) {
                     await this.sendMessage(rotation.scopeId, t(locale, 'auth_auto_recovered_current', {
@@ -5528,19 +5530,22 @@ export class BridgeSessionCore {
             }
             const selection = await this.selectNextCodexAuthCandidate(failedTargets);
             if (!selection) {
-                await this.sendMessage(rotation.scopeId, t(locale, 'auth_auto_no_candidate', {
+                await this.sendMessage(rotation.scopeId, t(locale, rotation.reasonKind === 'quota_limited' ? 'auth_quota_no_candidate' : 'auth_auto_no_candidate', {
                     error: formatShortStatusError(rotation.reason),
                 }));
                 return false;
             }
             const { candidate, fromLabel, toLabel } = selection;
+            const switchingKey = rotation.reasonKind === 'quota_limited'
+                ? (this.config.authAutoDeleteNeedsRepair ? 'auth_quota_switching_quiet' : 'auth_quota_switching')
+                : (this.config.authAutoDeleteNeedsRepair ? 'auth_auto_switching_quiet' : 'auth_auto_switching');
             await this.sendMessage(rotation.scopeId, this.config.authAutoDeleteNeedsRepair
-                ? t(locale, 'auth_auto_switching_quiet', { error: formatShortStatusError(rotation.reason) })
-                : t(locale, 'auth_auto_switching', {
+                ? t(locale, switchingKey, { error: formatShortStatusError(rotation.reason) })
+                : t(locale, switchingKey, {
                     ...this.codexAuthSwitchParams(locale, fromLabel, toLabel),
                     error: formatShortStatusError(rotation.reason),
                 }));
-            const outcome = await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true);
+            const outcome = await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true, true, rotation.reasonKind);
             if (!outcome.ok) {
                 return false;
             }
@@ -5659,7 +5664,7 @@ export class BridgeSessionCore {
             to: toLabel,
         };
     }
-    async switchCodexAuthAndRestart(scopeId, locale, candidate, automatic, sendResult = true) {
+    async switchCodexAuthAndRestart(scopeId, locale, candidate, automatic, sendResult = true, automaticReason = 'auth_invalid') {
         const authDir = this.resolveAuthDir();
         const initialState = await listCodexAuthState(new Set(), new Map(), authDir);
         const authStat = await fs.lstat(initialState.authPath).catch(() => null);
@@ -5688,13 +5693,19 @@ export class BridgeSessionCore {
                     error: toErrorMeta(error),
                 });
             }
-            const repairDisposition = await this.markCodexAuthCandidateNeedsRepair(candidate.name);
+            const validationFailureKind = isCodexQuotaLimitError(validation.error)
+                ? 'quota_limited'
+                : 'auth_invalid';
+            const repairDisposition = validationFailureKind === 'auth_invalid'
+                ? await this.markCodexAuthCandidateNeedsRepair(candidate.name)
+                : { deleted: false, restarted: false };
             const outcome = {
                 ...result,
                 ok: false,
                 candidateName: candidate.name,
                 recovered,
                 error: validation.error,
+                validationFailureKind,
                 restoredPrevious,
                 autoDeleted: repairDisposition.deleted,
                 deleteRestarted: repairDisposition.restarted,
@@ -5713,6 +5724,7 @@ export class BridgeSessionCore {
             candidateName: candidate.name,
             recovered,
             error: null,
+            validationFailureKind: null,
             restoredPrevious: false,
             autoDeleted: false,
             deleteRestarted: false,
@@ -5720,9 +5732,11 @@ export class BridgeSessionCore {
         if (!sendResult) {
             return outcome;
         }
+        const doneKey = automaticReason === 'quota_limited' ? 'auth_quota_done' : 'auth_auto_done';
+        const doneQuietKey = automaticReason === 'quota_limited' ? 'auth_quota_done_quiet' : 'auth_auto_done_quiet';
         const lines = [automatic && this.config.authAutoDeleteNeedsRepair
-                ? t(locale, 'auth_auto_done_quiet')
-                : t(locale, automatic ? 'auth_auto_done' : 'auth_switch_done', this.codexAuthSwitchParams(locale, result.fromLabel, result.toLabel))];
+                ? t(locale, doneQuietKey)
+                : t(locale, automatic ? doneKey : 'auth_switch_done', this.codexAuthSwitchParams(locale, result.fromLabel, result.toLabel))];
         if (recovered) {
             lines.push(t(locale, 'auth_recovered_newer_candidate', { value: candidate.name }));
         }
@@ -5771,11 +5785,13 @@ export class BridgeSessionCore {
         if (outcome.ok) {
             return [];
         }
-        const validationKey = outcome.autoDeleted && this.config.authAutoDeleteNeedsRepair
-            ? 'auth_switch_validation_auto_deleted_quiet'
-            : outcome.autoDeleted
-                ? 'auth_switch_validation_auto_deleted'
-                : 'auth_switch_validation_failed';
+        const validationKey = outcome.validationFailureKind === 'quota_limited'
+            ? 'auth_switch_validation_quota_limited'
+            : outcome.autoDeleted && this.config.authAutoDeleteNeedsRepair
+                ? 'auth_switch_validation_auto_deleted_quiet'
+                : outcome.autoDeleted
+                    ? 'auth_switch_validation_auto_deleted'
+                    : 'auth_switch_validation_failed';
         return [
             t(locale, validationKey, {
                 value: outcome.candidateName,
@@ -9337,16 +9353,36 @@ function cloneAuthRetryContext(context) {
         failedAuthTargets: new Set(context.failedAuthTargets),
     };
 }
-function isCodexAuthRotationError(params) {
-    if (isChatGptBackendAccessBlocked(collectCodexErrorText(params))) {
-        return false;
+function classifyCodexAuthRotationError(params) {
+    const collected = collectCodexErrorText(params);
+    if (isChatGptBackendAccessBlocked(collected)) {
+        return null;
     }
     const code = stringOrNull(params?.error?.codexErrorInfo) ?? stringOrNull(params?.error?.code);
-    if (code && /usageLimitExceeded|auth|unauthorized|forbidden|login/i.test(code)) {
-        return true;
-    }
     const message = stringOrNull(params?.error?.message) ?? '';
-    return /(usage limit|rate limit|not authenticated|unauthorized|forbidden|sign in|log in|login|auth)/i.test(message);
+    const text = `${code ?? ''}\n${message}\n${collected}`;
+    if (isCodexQuotaLimitError(text)) {
+        return 'quota_limited';
+    }
+    if (code && /auth|unauthorized|forbidden|login/i.test(code)) {
+        return 'auth_invalid';
+    }
+    return /(not authenticated|unauthorized|forbidden|sign in|log in|login|auth)/i.test(message)
+        ? 'auth_invalid'
+        : null;
+}
+function isCodexQuotaLimitError(text) {
+    return /usageLimitExceeded/i.test(text)
+        || /you['’]?ve hit your usage limit/i.test(text)
+        || /\busage limit(?:s)?\b/i.test(text)
+        || /\brate limit(?:ed|s)?\b/i.test(text)
+        || /\btoo many requests\b/i.test(text)
+        || /\binsufficient[_\s-]?quota\b/i.test(text)
+        || /\bquota exceeded\b/i.test(text)
+        || /\bbilling hard limit\b/i.test(text)
+        || /\bcredits? exhausted\b/i.test(text)
+        || /\bout of credits?\b/i.test(text)
+        || /\bcredits? limit\b/i.test(text);
 }
 function formatCodexNotificationError(params) {
     const collected = collectCodexErrorText(params);

package/dist/i18n.d.ts

@@ -199,6 +199,7 @@ declare const MESSAGES: {
         readonly auth_switch_validation_failed: "Selected auth failed validation: {error}. Marked {value} for login repair.";
         readonly auth_switch_validation_auto_deleted: "Selected auth failed validation: {error}. Auto-deleted {value}.";
         readonly auth_switch_validation_auto_deleted_quiet: "Selected auth failed validation and was auto-deleted.";
+        readonly auth_switch_validation_quota_limited: "Selected auth hit a Codex usage limit: {error}. It was not marked invalid.";
         readonly auth_switch_validation_reverted: "Restored the previous auth after the failed switch.";
         readonly auth_recovered_newer_candidate: "Recovered a newer same-account credential for {value} from another Codex home before reload.";
         readonly auth_refresh_all_confirm_short: "Review refresh all risk first.";
@@ -219,9 +220,14 @@ declare const MESSAGES: {
         readonly auth_auto_recovered_current: "Codex auth problem detected ({error}). Recovered a newer same-account credential for {value} and restarted Codex app-server.";
         readonly auth_auto_done: "Auto-switched Codex auth: {from} -> {to}.";
         readonly auth_auto_done_quiet: "Codex auth problem handled with another maintained candidate.";
+        readonly auth_quota_switching: "Codex usage limit detected ({error}). Switching: {from} -> {to}...";
+        readonly auth_quota_switching_quiet: "Codex usage limit detected ({error}). Selecting another maintained candidate...";
+        readonly auth_quota_done: "Switched Codex auth after usage limit: {from} -> {to}.";
+        readonly auth_quota_done_quiet: "Codex usage limit handled with another maintained candidate.";
         readonly auth_auto_retrying: "Retrying the same request with the new auth...";
         readonly auth_auto_retry_thread_missing: "Auth was switched, but the original thread is no longer available ({threadId}). Retry was stopped to avoid creating duplicate sessions.";
         readonly auth_auto_no_candidate: "Codex auth problem detected ({error}), but no unused auth candidate is available.";
+        readonly auth_quota_no_candidate: "Codex usage limit detected ({error}), but no unused auth candidate is available.";
         readonly auth_add_exists: "Auth candidate already exists: {value}";
         readonly auth_add_preparing: "Preparing new Codex auth candidate {value}...";
         readonly auth_add_started: "New auth login started for {value}.";
@@ -887,6 +893,7 @@ declare const MESSAGES: {
         readonly auth_switch_validation_failed: "选中的 auth 验证失败：{error}。已将 {value} 标记为需要登录修复。";
         readonly auth_switch_validation_auto_deleted: "选中的 auth 验证失败：{error}。已自动剔除 {value}。";
         readonly auth_switch_validation_auto_deleted_quiet: "选中的 auth 验证失败，已自动剔除。";
+        readonly auth_switch_validation_quota_limited: "选中的 auth 已触发 Codex 额度限制：{error}。没有把它标记为失效。";
         readonly auth_switch_validation_reverted: "已在切换失败后恢复到之前的 auth。";
         readonly auth_recovered_newer_candidate: "重载前已从其他 Codex home 恢复 {value} 的同账号较新凭据。";
         readonly auth_refresh_all_confirm_short: "请先确认刷新全部风险。";
@@ -907,9 +914,14 @@ declare const MESSAGES: {
         readonly auth_auto_recovered_current: "检测到 Codex auth 问题（{error}），已为 {value} 恢复同账号较新凭据并重启 Codex app-server。";
         readonly auth_auto_done: "已自动切换 Codex auth：{from} -> {to}。";
         readonly auth_auto_done_quiet: "Codex auth 问题已用另一个维护中的候选处理。";
+        readonly auth_quota_switching: "检测到 Codex 额度限制（{error}），正在切换：{from} -> {to}...";
+        readonly auth_quota_switching_quiet: "检测到 Codex 额度限制（{error}），正在选择另一个维护中的候选...";
+        readonly auth_quota_done: "已因 Codex 额度限制自动切换 auth：{from} -> {to}。";
+        readonly auth_quota_done_quiet: "Codex 额度限制已用另一个维护中的候选处理。";
         readonly auth_auto_retrying: "正在用新的 auth 重试同一条请求...";
         readonly auth_auto_retry_thread_missing: "Auth 已切换，但原线程已经不可用（{threadId}）。已停止重试，避免创建重复 session。";
         readonly auth_auto_no_candidate: "检测到 Codex auth 问题（{error}），但没有可用的未失败候选 auth。";
+        readonly auth_quota_no_candidate: "检测到 Codex 额度限制（{error}），但没有可用的未失败候选 auth。";
         readonly auth_add_exists: "auth 候选已经存在：{value}";
         readonly auth_add_preparing: "正在准备新的 Codex auth 候选 {value}...";
         readonly auth_add_started: "{value} 的新 auth 登录已开始。";

package/dist/i18n.js

@@ -197,6 +197,7 @@ const MESSAGES = {
         auth_switch_validation_failed: 'Selected auth failed validation: {error}. Marked {value} for login repair.',
         auth_switch_validation_auto_deleted: 'Selected auth failed validation: {error}. Auto-deleted {value}.',
         auth_switch_validation_auto_deleted_quiet: 'Selected auth failed validation and was auto-deleted.',
+        auth_switch_validation_quota_limited: 'Selected auth hit a Codex usage limit: {error}. It was not marked invalid.',
         auth_switch_validation_reverted: 'Restored the previous auth after the failed switch.',
         auth_recovered_newer_candidate: 'Recovered a newer same-account credential for {value} from another Codex home before reload.',
         auth_refresh_all_confirm_short: 'Review refresh all risk first.',
@@ -217,9 +218,14 @@ const MESSAGES = {
         auth_auto_recovered_current: 'Codex auth problem detected ({error}). Recovered a newer same-account credential for {value} and restarted Codex app-server.',
         auth_auto_done: 'Auto-switched Codex auth: {from} -> {to}.',
         auth_auto_done_quiet: 'Codex auth problem handled with another maintained candidate.',
+        auth_quota_switching: 'Codex usage limit detected ({error}). Switching: {from} -> {to}...',
+        auth_quota_switching_quiet: 'Codex usage limit detected ({error}). Selecting another maintained candidate...',
+        auth_quota_done: 'Switched Codex auth after usage limit: {from} -> {to}.',
+        auth_quota_done_quiet: 'Codex usage limit handled with another maintained candidate.',
         auth_auto_retrying: 'Retrying the same request with the new auth...',
         auth_auto_retry_thread_missing: 'Auth was switched, but the original thread is no longer available ({threadId}). Retry was stopped to avoid creating duplicate sessions.',
         auth_auto_no_candidate: 'Codex auth problem detected ({error}), but no unused auth candidate is available.',
+        auth_quota_no_candidate: 'Codex usage limit detected ({error}), but no unused auth candidate is available.',
         auth_add_exists: 'Auth candidate already exists: {value}',
         auth_add_preparing: 'Preparing new Codex auth candidate {value}...',
         auth_add_started: 'New auth login started for {value}.',
@@ -885,6 +891,7 @@ const MESSAGES = {
         auth_switch_validation_failed: '选中的 auth 验证失败：{error}。已将 {value} 标记为需要登录修复。',
         auth_switch_validation_auto_deleted: '选中的 auth 验证失败：{error}。已自动剔除 {value}。',
         auth_switch_validation_auto_deleted_quiet: '选中的 auth 验证失败，已自动剔除。',
+        auth_switch_validation_quota_limited: '选中的 auth 已触发 Codex 额度限制：{error}。没有把它标记为失效。',
         auth_switch_validation_reverted: '已在切换失败后恢复到之前的 auth。',
         auth_recovered_newer_candidate: '重载前已从其他 Codex home 恢复 {value} 的同账号较新凭据。',
         auth_refresh_all_confirm_short: '请先确认刷新全部风险。',
@@ -905,9 +912,14 @@ const MESSAGES = {
         auth_auto_recovered_current: '检测到 Codex auth 问题（{error}），已为 {value} 恢复同账号较新凭据并重启 Codex app-server。',
         auth_auto_done: '已自动切换 Codex auth：{from} -> {to}。',
         auth_auto_done_quiet: 'Codex auth 问题已用另一个维护中的候选处理。',
+        auth_quota_switching: '检测到 Codex 额度限制（{error}），正在切换：{from} -> {to}...',
+        auth_quota_switching_quiet: '检测到 Codex 额度限制（{error}），正在选择另一个维护中的候选...',
+        auth_quota_done: '已因 Codex 额度限制自动切换 auth：{from} -> {to}。',
+        auth_quota_done_quiet: 'Codex 额度限制已用另一个维护中的候选处理。',
         auth_auto_retrying: '正在用新的 auth 重试同一条请求...',
         auth_auto_retry_thread_missing: 'Auth 已切换，但原线程已经不可用（{threadId}）。已停止重试，避免创建重复 session。',
         auth_auto_no_candidate: '检测到 Codex auth 问题（{error}），但没有可用的未失败候选 auth。',
+        auth_quota_no_candidate: '检测到 Codex 额度限制（{error}），但没有可用的未失败候选 auth。',
         auth_add_exists: 'auth 候选已经存在：{value}',
         auth_add_preparing: '正在准备新的 Codex auth 候选 {value}...',
         auth_add_started: '{value} 的新 auth 登录已开始。',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",