@foxden-app/foxclaw 0.5.20 → 0.5.22

package/.env.example

@@ -48,6 +48,10 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot
 # AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 # AUTH_SYNC_NODE_ID=
+# Resource-rich auth pool mode: unrecoverable candidates that would need repair
+# are deleted automatically and propagated across auth-sync peers. /config can
+# toggle this at runtime and writes AUTH_AUTO_DELETE_NEEDS_REPAIR back here.
+# AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 
 # Optional: standard HTTP(S) proxy for Telegram and ChatGPT/Codex backend requests.
 # Put these in the same env file that `foxclaw start` installs into systemd/launchd.

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.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
+
+### 中文
+- 新增资源富裕 auth 池模式：`AUTH_AUTO_DELETE_NEEDS_REPAIR=true` 或 `/config auth_auto_delete on` 会把原本要标记为 `?`/需要登录修复、且无法恢复的候选自动剔除。
+- 自动剔除会通过跨节点 auth sync 发送删除 tombstone，peer 收到后删除同名候选，并优先处理删除，避免待导入队列把坏候选复活。
+- `/status` 和 `/config` 现在显示 auth 池摘要：历史见过的候选数、当前存活数、因失效自动剔除数；`/config` 的开关会写回当前 FoxClaw `.env`。
+- 开启自动剔除后，auth mirror / auth sync 的候选级同步、导入、删除和恢复通知会静默或汇总为池子摘要；同步发送/导入失败、删除失败和系统级 `sync_error` 仍会明确提示。
+
+### English
+- Added a resource-rich auth pool mode: `AUTH_AUTO_DELETE_NEEDS_REPAIR=true` or `/config auth_auto_delete on` automatically deletes unrecoverable candidates that would otherwise be marked `?` / needs login repair.
+- Auto-delete now publishes a cross-node auth-sync delete tombstone, so peers delete the same candidate and process deletes before pending imports to avoid resurrecting bad candidates.
+- `/status` and `/config` now show an auth-pool summary: total candidates seen, currently alive, and invalid-deleted count. The `/config` toggle writes back to the active FoxClaw `.env`.
+- When auto-delete is enabled, candidate-level auth mirror / auth sync publish, import, delete, and recovery chatter is silenced or collapsed into pool summaries; sync send/import failures, delete failures, and system-level `sync_error` still notify explicitly.
+
 ## 0.5.20 - 2026-06-08
 
 ### 中文

package/README.md

@@ -216,7 +216,7 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw 仍然只运行一个系统服务。默认情况下，它会为每个 bot 启动独立 `codex app-server` 和独立 `CODEX_HOME`。因此 A 私聊运行 turn 时，B 私聊仍可独立切换自己的 `/auth`。候选凭据由 FoxClaw 在登录或刷新在线验证后镜像同步；切换或重载前还会从其他 Codex home 恢复同账号较新凭据。各 bot 的当前选择互不影响。每个 bot 首次私聊发送 `/help` 和 `/status`；`/auth` 会标明正在操作的 bot runtime，`/status` 会列出全部 bot 的连接、runtime 类型、当前 auth 和活动 turn 摘要。
 
-多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_contact_bot`。推荐每台机器只选一个联系人 bot；同一节点内的其他 bot 继续走本机 auth 镜像。多 bot 模式下，默认用 `TG_BOT_TOKENS` 的第一个 token 作为联系人 bot。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本，并在联系人 bot 私聊里汇总报告发送、接收、排队、导入、失败和人工介入提示。`/auth sync events [过滤]` 和 `/auth sync trace <requestId>` 可查看最近通讯流水。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。完整配置、`@BotFather` 操作和验证步骤见 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
+多台机器共享同一合法账号池时，可以启用可选跨节点 auth 同步：`AUTH_SYNC_ENABLED=true`、`AUTH_SYNC_KEY` 和 `AUTH_SYNC_PEERS=@peer_contact_bot`。推荐每台机器只选一个联系人 bot；同一节点内的其他 bot 继续走本机 auth 镜像。多 bot 模式下，默认用 `TG_BOT_TOKENS` 的第一个 token 作为联系人 bot。FoxClaw 会通过 Telegram Bot-to-Bot 私聊传输加密 auth 包；本机验证刷新后主动 push，发现本机候选失效时主动 pull peer 已持有的有效副本，并在联系人 bot 私聊里汇总报告发送、接收、排队、导入、失败和人工介入提示。资源富裕、只关心池子数量时，可用 `/config auth_auto_delete on` 或 `AUTH_AUTO_DELETE_NEEDS_REPAIR=true` 让无法恢复的候选自动跨节点剔除，并把通知压缩为池子摘要。`/auth sync events [过滤]` 和 `/auth sync trace <requestId>` 可查看最近通讯流水。跨节点恢复不会自动刷新 token，`/auth refresh all confirm` 会先申请跨节点刷新锁。完整配置、`@BotFather` 操作和验证步骤见 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
 
 如果你需要一路 Telegram 与终端互通 session，把同一个 token 同时填入 `TG_BOT_TOKENS` 和 `TG_BOT_TOKEN`。这个 bot 使用默认 `CODEX_HOME`（未设置时通常是 `~/.codex`）和默认 auth，因此能看到终端 Codex 的本地线程；它不再享有隔离 runtime 的“互不影响”保证，切换 auth 会影响终端和其他默认 runtime。
 

package/dist/auth/cross_node_sync.d.ts

@@ -123,6 +123,46 @@ export type AuthSyncNotification = {
     peer: string;
     mode: AuthSyncRemoteImportMode;
     reason: string;
+} | {
+    kind: 'candidate_delete_sent';
+    candidateName: string;
+    peers: string[];
+    reason: string | null;
+} | {
+    kind: 'candidate_delete_failed';
+    candidateName: string;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'remote_delete_received';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    queued: boolean;
+    queueLength: number;
+    reason: string | null;
+} | {
+    kind: 'remote_delete_deleted';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    reason: string | null;
+} | {
+    kind: 'remote_delete_skipped';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    reason: string;
+} | {
+    kind: 'remote_delete_failed';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    reason: string;
 } | {
     kind: 'recovery_started';
     candidateName: string;
@@ -170,6 +210,15 @@ export interface AuthSyncImportCallbacks {
         nodeId: string;
         label?: string | null;
     }) => Promise<AuthMirrorImportResult>;
+    deleteLocalCandidate?: (candidateName: string, source: {
+        nodeId: string;
+        label?: string | null;
+        reason?: string | null;
+    }) => Promise<{
+        ok: boolean;
+        deleted: boolean;
+        reason?: string | null;
+    }>;
     isIdle: () => boolean;
     notify?: (event: AuthSyncNotification) => Promise<void>;
 }
@@ -201,6 +250,7 @@ export declare class CrossNodeAuthSync {
     private readonly peers;
     private readonly peerKeys;
     private readonly pendingImports;
+    private readonly pendingDeletes;
     private readonly pendingPulls;
     private readonly pendingLeases;
     private readonly pendingTests;
@@ -208,6 +258,7 @@ export declare class CrossNodeAuthSync {
     private lastPeerActivityAt;
     private timer;
     private importProcessorActive;
+    private deleteProcessorActive;
     private activeRemoteLease;
     private activeLocalLease;
     private lastNotifiedError;
@@ -223,6 +274,7 @@ export declare class CrossNodeAuthSync {
         sent: number;
         skipped: number;
     }>;
+    publishCandidateDeletion(candidateName: string, reason?: string | null): Promise<boolean>;
     publishDigest(): Promise<void>;
     requestRecovery(candidateName: string, current?: {
         accountId: string | null;
@@ -242,6 +294,9 @@ export declare class CrossNodeAuthSync {
     private handleLeaseReply;
     private enqueueImport;
     private processPendingImports;
+    private enqueueDelete;
+    private processPendingDeletes;
+    private deleteRemoteCandidate;
     private validateAndImport;
     private sendToAll;
     private sendToPeer;

package/dist/auth/cross_node_sync.js

@@ -21,6 +21,7 @@ export class CrossNodeAuthSync {
     peers;
     peerKeys;
     pendingImports = [];
+    pendingDeletes = [];
     pendingPulls = new Map();
     pendingLeases = new Map();
     pendingTests = new Map();
@@ -28,6 +29,7 @@ export class CrossNodeAuthSync {
     lastPeerActivityAt = new Map();
     timer = null;
     importProcessorActive = false;
+    deleteProcessorActive = false;
     activeRemoteLease = null;
     activeLocalLease = null;
     lastNotifiedError = null;
@@ -79,8 +81,8 @@ export class CrossNodeAuthSync {
             return;
         this.timer = setInterval(() => {
             this.expireLeases();
-            void this.processPendingImports().catch((error) => {
-                this.recordError(`pending import failed: ${formatError(error)}`);
+            void this.processPendingDeletes().then(() => this.processPendingImports()).catch((error) => {
+                this.recordError(`pending auth sync work failed: ${formatError(error)}`);
             });
         }, 5_000);
         this.timer.unref();
@@ -124,7 +126,9 @@ export class CrossNodeAuthSync {
     }
     isIdle() {
         return this.pendingImports.length === 0
+            && this.pendingDeletes.length === 0
             && !this.importProcessorActive
+            && !this.deleteProcessorActive
             && this.pendingPulls.size === 0
             && this.pendingLeases.size === 0
             && this.pendingTests.size === 0
@@ -205,6 +209,48 @@ export class CrossNodeAuthSync {
             throw error;
         }
     }
+    async publishCandidateDeletion(candidateName, reason = null) {
+        if (!this.isReady() || !isAuthCandidateName(candidateName))
+            return false;
+        const requestId = crypto.randomUUID();
+        try {
+            await this.sendToAll({
+                kind: 'delete.candidate',
+                requestId,
+                candidateName,
+                reason,
+                deletedAt: new Date().toISOString(),
+            });
+            this.recordEvent({
+                direction: 'local',
+                kind: 'delete.candidate',
+                stage: 'sent',
+                peer: null,
+                requestId,
+                candidateName,
+                detail: reason,
+            });
+            this.clearCandidateFailure(candidateName);
+            await this.writeState();
+            this.notify({ kind: 'candidate_delete_sent', candidateName, peers: [...this.peers], reason });
+            return true;
+        }
+        catch (error) {
+            const formatted = formatError(error);
+            this.recordError(`candidate delete publish failed for ${candidateName}: ${formatted}`, false);
+            this.recordEvent({
+                direction: 'local',
+                kind: 'delete.candidate',
+                stage: 'send_failed',
+                peer: null,
+                requestId,
+                candidateName,
+                detail: formatted,
+            });
+            this.notify({ kind: 'candidate_delete_failed', candidateName, peers: [...this.peers], reason: formatted });
+            throw error;
+        }
+    }
     async publishDigest() {
         if (!this.isReady())
             return;
@@ -455,6 +501,9 @@ export class CrossNodeAuthSync {
             case 'pull.response':
                 await this.handlePullResponse(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
                 return;
+            case 'delete.candidate':
+                this.enqueueDelete(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
+                return;
             case 'digest':
                 await this.handleDigest(message, normalizePeerIdentity(peer));
                 return;
@@ -717,6 +766,8 @@ export class CrossNodeAuthSync {
     async processPendingImports() {
         if (this.importProcessorActive)
             return;
+        if (this.pendingDeletes.length > 0 || this.deleteProcessorActive)
+            return;
         if (!this.callbacks.isIdle())
             return;
         this.importProcessorActive = true;
@@ -732,6 +783,150 @@ export class CrossNodeAuthSync {
             this.importProcessorActive = false;
         }
     }
+    enqueueDelete(message, sourceNodeId, sourceLabel, fromPeer) {
+        if (!isAuthCandidateName(message.candidateName))
+            return;
+        const queued = this.deleteProcessorActive
+            || this.importProcessorActive
+            || !this.callbacks.isIdle()
+            || this.pendingImports.length > 0
+            || this.pendingDeletes.length > 0;
+        for (let index = this.pendingImports.length - 1; index >= 0; index -= 1) {
+            if (this.pendingImports[index]?.bundle.candidateName === message.candidateName) {
+                this.pendingImports.splice(index, 1);
+            }
+        }
+        this.pendingDeletes.push({
+            candidateName: message.candidateName,
+            requestId: message.requestId,
+            sourceNodeId,
+            sourceLabel,
+            receivedAt: Date.now(),
+            fromPeer,
+            reason: message.reason ?? null,
+        });
+        this.recordEvent({
+            direction: 'local',
+            kind: 'delete.candidate',
+            stage: queued ? 'queued' : 'processing',
+            peer: fromPeer,
+            requestId: message.requestId,
+            candidateName: message.candidateName,
+            detail: message.reason ?? null,
+        });
+        this.notify({
+            kind: 'remote_delete_received',
+            candidateName: message.candidateName,
+            sourceNodeId,
+            sourceLabel: sourceLabel ?? fromPeer,
+            peer: fromPeer,
+            queued,
+            queueLength: this.pendingDeletes.length,
+            reason: message.reason ?? null,
+        });
+        void this.processPendingDeletes().then(() => this.processPendingImports()).catch((error) => {
+            this.recordError(`remote delete failed: ${formatError(error)}`);
+        });
+    }
+    async processPendingDeletes() {
+        if (this.deleteProcessorActive)
+            return;
+        if (!this.callbacks.isIdle())
+            return;
+        this.deleteProcessorActive = true;
+        try {
+            while (this.pendingDeletes.length > 0) {
+                if (!this.callbacks.isIdle())
+                    return;
+                const pending = this.pendingDeletes.shift();
+                await this.deleteRemoteCandidate(pending);
+            }
+        }
+        finally {
+            this.deleteProcessorActive = false;
+        }
+    }
+    async deleteRemoteCandidate(pending) {
+        const source = pending.sourceLabel ?? pending.fromPeer;
+        if (!this.callbacks.deleteLocalCandidate) {
+            this.recordEvent({
+                direction: 'local',
+                kind: 'delete.candidate',
+                stage: 'skipped',
+                peer: pending.fromPeer,
+                requestId: pending.requestId,
+                candidateName: pending.candidateName,
+                detail: 'delete callback is not configured',
+            });
+            this.notify({
+                kind: 'remote_delete_skipped',
+                candidateName: pending.candidateName,
+                sourceNodeId: pending.sourceNodeId,
+                sourceLabel: source,
+                peer: pending.fromPeer,
+                reason: 'delete callback is not configured',
+            });
+            return;
+        }
+        const result = await this.callbacks.deleteLocalCandidate(pending.candidateName, {
+            nodeId: pending.sourceNodeId,
+            label: source,
+            reason: pending.reason,
+        });
+        if (!result.ok) {
+            const reason = result.reason ?? 'remote delete failed';
+            this.recordEvent({
+                direction: 'local',
+                kind: 'delete.candidate',
+                stage: 'failed',
+                peer: pending.fromPeer,
+                requestId: pending.requestId,
+                candidateName: pending.candidateName,
+                detail: reason,
+            });
+            this.notify({
+                kind: 'remote_delete_failed',
+                candidateName: pending.candidateName,
+                sourceNodeId: pending.sourceNodeId,
+                sourceLabel: source,
+                peer: pending.fromPeer,
+                reason,
+            });
+            return;
+        }
+        const clearedFailure = this.clearCandidateFailure(pending.candidateName);
+        this.recordEvent({
+            direction: 'local',
+            kind: 'delete.candidate',
+            stage: result.deleted ? 'deleted' : 'skipped',
+            peer: pending.fromPeer,
+            requestId: pending.requestId,
+            candidateName: pending.candidateName,
+            detail: result.reason ?? pending.reason,
+        });
+        if (clearedFailure) {
+            await this.writeState();
+        }
+        if (result.deleted) {
+            this.notify({
+                kind: 'remote_delete_deleted',
+                candidateName: pending.candidateName,
+                sourceNodeId: pending.sourceNodeId,
+                sourceLabel: source,
+                peer: pending.fromPeer,
+                reason: pending.reason,
+            });
+            return;
+        }
+        this.notify({
+            kind: 'remote_delete_skipped',
+            candidateName: pending.candidateName,
+            sourceNodeId: pending.sourceNodeId,
+            sourceLabel: source,
+            peer: pending.fromPeer,
+            reason: result.reason ?? 'candidate was already absent',
+        });
+    }
     async validateAndImport(bundle, sourceNodeId, sourceLabel, fromPeer, mode) {
         const source = sourceLabel ?? fromPeer;
         if (!isValidBundle(bundle)) {
@@ -1215,6 +1410,7 @@ function requestIdFromMessage(message) {
             return message.requestId ?? null;
         case 'pull.request':
         case 'pull.response':
+        case 'delete.candidate':
         case 'test.ping':
         case 'test.pong':
             return message.requestId;
@@ -1232,6 +1428,7 @@ function candidateNameFromMessage(message) {
     switch (message.kind) {
         case 'push.bundle':
         case 'pull.request':
+        case 'delete.candidate':
             return message.candidateName;
         case 'pull.response':
             return message.bundle?.candidateName ?? null;

package/dist/config.d.ts

@@ -44,6 +44,7 @@ export interface AppConfig {
     statusPath: string;
     logPath: string;
     lockPath: string;
+    envPath: string | null;
     /** When true, start Weixin (iLink) long-poll alongside Telegram. */
     wxEnabled: boolean;
     /** Allowed `from_user_id` values for inbound Weixin messages (empty = allow any). */
@@ -61,6 +62,7 @@ export interface AppConfig {
     authSyncClusterId: string;
     authSyncStatePath: string;
     authSyncTempDir: string;
+    authAutoDeleteNeedsRepair: boolean;
 }
 export declare function loadConfig(): AppConfig;
 export declare function selectDefaultRuntimeBotToken(configuredTokens: string[], legacyToken: string | null): string | null;

package/dist/config.js

@@ -81,6 +81,7 @@ export function loadConfig() {
         statusPath: DEFAULT_STATUS_PATH,
         logPath: DEFAULT_LOG_PATH,
         lockPath: process.env.LOCK_PATH || DEFAULT_LOCK_PATH,
+        envPath: getLoadedEnvPath(),
         wxEnabled: boolEnv('WX_ENABLED', false),
         wxAllowedIlinkUserIds: parseCommaSeparatedIds(process.env.WX_ALLOWED_ILINK_USER_IDS),
         weixinAccountsDir: process.env.WEIXIN_ACCOUNTS_DIR || path.join(APP_HOME, 'weixin', 'accounts'),
@@ -95,6 +96,7 @@ export function loadConfig() {
         authSyncClusterId: process.env.AUTH_SYNC_CLUSTER_ID?.trim() || 'default',
         authSyncStatePath: process.env.AUTH_SYNC_STATE_PATH || DEFAULT_AUTH_SYNC_STATE_PATH,
         authSyncTempDir: process.env.AUTH_SYNC_TEMP_DIR || DEFAULT_AUTH_SYNC_TEMP_DIR,
+        authAutoDeleteNeedsRepair: boolEnv('AUTH_AUTO_DELETE_NEEDS_REPAIR', false),
     };
     ensureAppDirs(config);
     return config;

package/dist/controller/controller.d.ts

@@ -9,7 +9,7 @@ import type { SelfUpdateRuntime, SelfUpdateStatus } from '../update.js';
 export interface CoreCoordinator {
     canSelfUpdate?: () => boolean;
     authCandidateUpdated?: (runtimeId: string, candidateName: string) => Promise<void>;
-    authCandidateDeleted?: (runtimeId: string, candidateName: string) => Promise<void>;
+    authCandidateDeleted?: (runtimeId: string, candidateName: string, reason?: string | null) => Promise<void>;
     recoverAuthCandidate?: (runtimeId: string, candidateName: string, options?: {
         crossNode?: boolean;
     }) => Promise<boolean>;
@@ -195,6 +195,7 @@ export declare class BridgeSessionCore {
     private registerActiveTurn;
     private createActiveTurnState;
     getCurrentAuthLabel(): Promise<string | null>;
+    handleExternalCodexAuthCandidateDeleted(candidateName: string, reason?: string | null): Promise<void>;
     validateExternalCodexAuthCandidate(candidateName: string, rawAuth: string, expectedAccountId: string): Promise<{
         ok: boolean;
         reason?: string | null;
@@ -327,6 +328,9 @@ export declare class BridgeSessionCore {
     private handleAppsCommand;
     private handleFeaturesCommand;
     private handleConfigCommand;
+    private handleConfigToggleCallback;
+    private setAuthAutoDeleteNeedsRepair;
+    private formatConfigToggleUpdate;
     private handleRequirementsCommand;
     private handleProviderCommand;
     private handleMcpCommand;