@foxden-app/foxclaw 0.5.20 → 0.5.21

package/dist/main.js

@@ -253,7 +253,9 @@ async function runServeCli() {
                 label: runtime.bot.username ? `@${runtime.bot.username}` : runtime.id,
                 authDir: runtime.authDir,
                 validate: async (context) => validateRefreshedAuthCandidate(runtime, context.candidateName),
-                notify: createAuthMirrorNotifier(store, runtime.id, runtime.bot, authNotificationAggregator),
+                notify: createAuthMirrorNotifier(store, runtime.id, runtime.bot, authNotificationAggregator, {
+                    quietAuthPoolMode: () => config.authAutoDeleteNeedsRepair,
+                }),
             })), logger, path.join(APP_HOME, 'runtime', 'auth-mirror.json'), {
                 onSynced: async (event) => {
                     await authSync?.publishCandidate(event.record.candidateName);
@@ -324,7 +326,10 @@ async function runServeCli() {
                 canSelfUpdate: () => authSyncLocalIdle()
                     && (authSync ? authSync.isIdle() : localAuthRefreshLease.isIdle()),
                 authCandidateUpdated: (runtimeId, candidateName) => mirror.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined),
-                authCandidateDeleted: (_runtimeId, candidateName) => mirror.deleteCandidate(candidateName).then(() => undefined),
+                authCandidateDeleted: async (_runtimeId, candidateName, reason = null) => {
+                    await mirror.deleteCandidate(candidateName);
+                    await authSync?.publishCandidateDeletion(candidateName, reason);
+                },
                 recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                     const local = await mirror.recoverRuntimeCandidate(runtimeId, candidateName);
                     if (local)
@@ -424,8 +429,22 @@ async function runServeCli() {
                         return runtime.core.validateExternalCodexAuthCandidate(candidateName, raw, expectedAccountId);
                     },
                     importCandidate: (candidateName, raw, source) => mirror.importExternalCandidate(candidateName, raw, source),
+                    deleteLocalCandidate: async (candidateName, source) => {
+                        if (!authSyncLocalIdle()) {
+                            return { ok: false, deleted: false, reason: 'runtime is not idle' };
+                        }
+                        await mirror.deleteCandidate(candidateName);
+                        store.deleteCodexAuthCandidate(candidateName);
+                        await Promise.all(runtimes.map(runtime => runtime.core.handleExternalCodexAuthCandidateDeleted(candidateName, source.reason ?? null)));
+                        if (activeWeixinCore) {
+                            await activeWeixinCore.handleExternalCodexAuthCandidateDeleted(candidateName, source.reason ?? null);
+                        }
+                        return { ok: true, deleted: true, reason: source.reason ?? null };
+                    },
                     isIdle: authSyncLocalIdle,
-                    notify: createAuthSyncNotifier(store, authSyncTransportBot.bot, authNotificationAggregator),
+                    notify: createAuthSyncNotifier(store, authSyncTransportBot.bot, authNotificationAggregator, {
+                        quietAuthPoolMode: () => config.authAutoDeleteNeedsRepair,
+                    }),
                 });
                 await authSync.initialize();
                 activeAuthSync = authSync;
@@ -494,7 +513,10 @@ async function runServeCli() {
             canSelfUpdate: () => singleAuthSyncLocalIdle()
                 && (singleAuthSync ? singleAuthSync.isIdle() : singleLocalAuthRefreshLease.isIdle()),
             authCandidateUpdated: (runtimeId, candidateName) => singleMirror?.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined) ?? Promise.resolve(),
-            authCandidateDeleted: (_runtimeId, candidateName) => singleMirror?.deleteCandidate(candidateName).then(() => undefined) ?? Promise.resolve(),
+            authCandidateDeleted: async (_runtimeId, candidateName, reason = null) => {
+                await singleMirror?.deleteCandidate(candidateName);
+                await singleAuthSync?.publishCandidateDeletion(candidateName, reason);
+            },
             recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                 const local = await singleMirror?.recoverRuntimeCandidate(runtimeId, candidateName) ?? null;
                 if (local)
@@ -570,8 +592,19 @@ async function runServeCli() {
                     return core.validateExternalCodexAuthCandidate(candidateName, raw, expectedAccountId);
                 },
                 importCandidate: (candidateName, raw, source) => singleMirror.importExternalCandidate(candidateName, raw, source),
+                deleteLocalCandidate: async (candidateName, source) => {
+                    if (!singleAuthSyncLocalIdle()) {
+                        return { ok: false, deleted: false, reason: 'runtime is not idle' };
+                    }
+                    await singleMirror.deleteCandidate(candidateName);
+                    store.deleteCodexAuthCandidate(candidateName);
+                    await core.handleExternalCodexAuthCandidateDeleted(candidateName, source.reason ?? null);
+                    return { ok: true, deleted: true, reason: source.reason ?? null };
+                },
                 isIdle: singleAuthSyncLocalIdle,
-                notify: createAuthSyncNotifier(store, bot, authNotificationAggregator),
+                notify: createAuthSyncNotifier(store, bot, authNotificationAggregator, {
+                    quietAuthPoolMode: () => config.authAutoDeleteNeedsRepair,
+                }),
             });
             await singleAuthSync.initialize();
             activeAuthSync = singleAuthSync;
@@ -641,8 +674,10 @@ async function runServeCli() {
         throw error;
     }
 }
-function createAuthMirrorNotifier(store, botId, bot, aggregator) {
+function createAuthMirrorNotifier(store, botId, bot, aggregator, options = {}) {
     return async (event) => {
+        if (options.quietAuthPoolMode?.())
+            return;
         const privateScope = store.getTelegramPrivateScope(botId);
         if (!privateScope)
             return;
@@ -654,7 +689,27 @@ function createAuthMirrorNotifier(store, botId, bot, aggregator) {
         }, event);
     };
 }
-function createAuthSyncNotifier(store, bot, aggregator) {
+function createAuthSyncNotifier(store, bot, aggregator, options = {}) {
+    const poolSummaryQueues = new Map();
+    const enqueuePoolSummary = (destination) => {
+        const existing = poolSummaryQueues.get(destination.key);
+        if (existing) {
+            clearTimeout(existing.timer);
+        }
+        const timer = setTimeout(() => {
+            const queued = poolSummaryQueues.get(destination.key);
+            if (!queued)
+                return;
+            poolSummaryQueues.delete(destination.key);
+            void queued.sendMessage(formatAuthPoolSummary(queued.locale, store.getCodexAuthPoolStats())).catch(() => undefined);
+        }, 2_000);
+        timer.unref();
+        poolSummaryQueues.set(destination.key, {
+            locale: destination.locale,
+            sendMessage: destination.sendMessage,
+            timer,
+        });
+    };
     return async (event) => {
         if (!bot.identity)
             return;
@@ -667,6 +722,12 @@ function createAuthSyncNotifier(store, bot, aggregator) {
             locale,
             sendMessage: (text) => bot.sendMessage(privateScope.chatId, text),
         };
+        if (options.quietAuthPoolMode?.() && isQuietAuthPoolNotification(event)) {
+            if (shouldSendQuietAuthPoolSummary(event)) {
+                enqueuePoolSummary(destination);
+            }
+            return;
+        }
         if (aggregator.enqueueAuthSync(destination, event)) {
             return;
         }
@@ -676,6 +737,45 @@ function createAuthSyncNotifier(store, bot, aggregator) {
 function authNotificationDestinationKey(botId, chatId) {
     return `${botId}:${chatId}`;
 }
+function formatAuthPoolSummary(locale, stats) {
+    return locale === 'zh'
+        ? `auth 池：历史 ${stats.totalSeen}，存活 ${stats.alive}，因失效剔除 ${stats.deletedInvalid}。`
+        : `Auth pool: total seen ${stats.totalSeen}, alive ${stats.alive}, invalid-deleted ${stats.deletedInvalid}.`;
+}
+function isQuietAuthPoolNotification(event) {
+    switch (event.kind) {
+        case 'candidate_publish_started':
+        case 'candidate_publish_completed':
+        case 'push_all_started':
+        case 'push_all_completed':
+        case 'remote_bundle_received':
+        case 'remote_import_imported':
+        case 'remote_import_skipped':
+        case 'candidate_delete_sent':
+        case 'remote_delete_received':
+        case 'remote_delete_deleted':
+        case 'remote_delete_skipped':
+        case 'recovery_started':
+        case 'recovery_peer_empty':
+        case 'recovery_peer_bundle_received':
+        case 'recovery_failed':
+        case 'pull_request_received':
+        case 'pull_response_sent':
+            return true;
+        default:
+            return false;
+    }
+}
+function shouldSendQuietAuthPoolSummary(event) {
+    switch (event.kind) {
+        case 'candidate_delete_sent':
+        case 'remote_delete_deleted':
+        case 'remote_delete_skipped':
+            return true;
+        default:
+            return false;
+    }
+}
 function formatAuthSyncNotification(locale, event) {
     const peers = 'peers' in event ? formatPeerList(event.peers, locale) : '';
     if (locale === 'zh') {
@@ -704,6 +804,23 @@ function formatAuthSyncNotification(locale, event) {
                 return `${event.mode === 'pull' ? '跨节点拉取未改动本机文件' : '收到跨节点 auth 但未写盘'}：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}\n原因：${event.reason}`;
             case 'remote_import_failed':
                 return `${event.mode === 'pull' ? '跨节点拉取导入失败' : '跨节点 auth 导入失败'}：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}\n原因：${event.reason}\n需要注意：如果其他候选也无法恢复，请人工介入重新登录或刷新这个 auth。`;
+            case 'candidate_delete_sent':
+                return `跨节点 auth 删除已发出：${event.candidateName}\nPeer：${peers}${event.reason ? `\n原因：${event.reason}` : ''}`;
+            case 'candidate_delete_failed':
+                return `跨节点 auth 删除发送失败：${event.candidateName}\nPeer：${peers}\n原因：${event.reason}`;
+            case 'remote_delete_received':
+                return [
+                    `收到跨节点 auth 删除：${event.candidateName}`,
+                    `来源：${formatSource(event.sourceLabel, event.sourceNodeId)}，peer ${event.peer}`,
+                    `处理：${event.queued ? `本机忙，已排队等待空闲后删除；当前待删除 ${event.queueLength}` : '本机空闲，正在删除同名候选'}`,
+                    event.reason ? `原因：${event.reason}` : null,
+                ].filter(Boolean).join('\n');
+            case 'remote_delete_deleted':
+                return `已执行跨节点 auth 删除：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}${event.reason ? `\n原因：${event.reason}` : ''}`;
+            case 'remote_delete_skipped':
+                return `跨节点 auth 删除未改动本机文件：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}\n原因：${event.reason}`;
+            case 'remote_delete_failed':
+                return `跨节点 auth 删除失败：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}\n原因：${event.reason}`;
             case 'recovery_started':
                 return `auth 恢复开始：${event.candidateName}\nRequest：${event.requestId}\n处理：同节点没有可用较新副本，正在向跨节点 peer 查询：${peers}，最长等待 ${event.timeoutMs}ms`;
             case 'recovery_peer_empty':
@@ -753,6 +870,23 @@ function formatAuthSyncNotification(locale, event) {
             return `${event.mode === 'pull' ? 'Cross-node pull did not change local files' : 'Received cross-node auth but did not write it'}: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}\nReason: ${event.reason}`;
         case 'remote_import_failed':
             return `${event.mode === 'pull' ? 'Cross-node pull import failed' : 'Cross-node auth import failed'}: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}\nReason: ${event.reason}\nAttention: if no other candidate can recover this account, run device login or refresh this auth manually.`;
+        case 'candidate_delete_sent':
+            return `Cross-node auth delete sent: ${event.candidateName}\nPeers: ${peers}${event.reason ? `\nReason: ${event.reason}` : ''}`;
+        case 'candidate_delete_failed':
+            return `Cross-node auth delete send failed: ${event.candidateName}\nPeers: ${peers}\nReason: ${event.reason}`;
+        case 'remote_delete_received':
+            return [
+                `Received cross-node auth delete: ${event.candidateName}`,
+                `Source: ${formatSource(event.sourceLabel, event.sourceNodeId)}, peer ${event.peer}`,
+                `Action: ${event.queued ? `queued until this node is idle; pending deletes ${event.queueLength}` : 'deleting the matching local candidate'}`,
+                event.reason ? `Reason: ${event.reason}` : null,
+            ].filter(Boolean).join('\n');
+        case 'remote_delete_deleted':
+            return `Applied cross-node auth delete: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}${event.reason ? `\nReason: ${event.reason}` : ''}`;
+        case 'remote_delete_skipped':
+            return `Cross-node auth delete did not change local files: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}\nReason: ${event.reason}`;
+        case 'remote_delete_failed':
+            return `Cross-node auth delete failed: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}\nReason: ${event.reason}`;
         case 'recovery_started':
             return `Auth recovery started: ${event.candidateName}\nRequest: ${event.requestId}\nAction: no newer same-node copy was available; querying cross-node peers: ${peers}; timeout ${event.timeoutMs}ms`;
         case 'recovery_peer_empty':

package/dist/store/database.d.ts

@@ -38,6 +38,11 @@ export interface CodexAuthQuotaSnapshotRecord {
     secondaryRemainingPercent: number | null;
     updatedAt: number;
 }
+export interface CodexAuthPoolStats {
+    totalSeen: number;
+    alive: number;
+    deletedInvalid: number;
+}
 export type CodexAuthCandidateState = 'active' | 'needs_repair';
 export declare class BridgeStore {
     private db;
@@ -125,6 +130,10 @@ export declare class BridgeStore {
     setCodexAuthCandidateDisabled(name: string, disabled: boolean, runtimeId?: string): void;
     setCodexAuthCandidateState(name: string, state: CodexAuthCandidateState, runtimeId?: string): void;
     deleteCodexAuthCandidate(name: string): void;
+    recordCodexAuthPoolInventory(names: string[]): void;
+    recordCodexAuthCandidateInvalidDelete(name: string, reason?: string | null): void;
+    recordCodexAuthCandidateRemoved(name: string, reason?: string | null): void;
+    getCodexAuthPoolStats(): CodexAuthPoolStats;
     setCodexAuthQuotaSnapshot(runtimeId: string, candidateName: string, accountId: string, quotaIdentityId: string, snapshot: Pick<CodexAuthQuotaSnapshotRecord, 'capturedAtMs' | 'planType' | 'primaryWindowDurationMins' | 'primaryRemainingPercent' | 'secondaryWindowDurationMins' | 'secondaryRemainingPercent'>): void;
     listCodexAuthQuotaSnapshots(quotaIdentityIds: string[]): CodexAuthQuotaSnapshotRecord[];
     private ensureColumn;

package/dist/store/database.js

@@ -197,6 +197,14 @@ export class BridgeStore {
       );
       CREATE INDEX IF NOT EXISTS codex_auth_quota_snapshots_account_idx
         ON codex_auth_quota_snapshots(account_id);
+      CREATE TABLE IF NOT EXISTS codex_auth_pool_history (
+        name TEXT PRIMARY KEY,
+        first_seen_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL,
+        deleted_at INTEGER,
+        delete_reason TEXT,
+        invalid_delete_count INTEGER NOT NULL DEFAULT 0
+      );
     `);
         this.ensureColumn('thread_cache', 'name', 'TEXT');
         this.ensureColumn('thread_cache', 'model_provider', 'TEXT');
@@ -217,6 +225,7 @@ export class BridgeStore {
         this.ensureColumn('codex_auth_quota_snapshots', 'primary_window_duration_mins', 'REAL');
         this.ensureColumn('codex_auth_quota_snapshots', 'secondary_window_duration_mins', 'REAL');
         this.ensureColumn('codex_auth_quota_snapshots', 'quota_identity_id', "TEXT NOT NULL DEFAULT ''");
+        this.ensureColumn('codex_auth_pool_history', 'invalid_delete_count', 'INTEGER NOT NULL DEFAULT 0');
         this.db.prepare(`
       UPDATE codex_auth_quota_snapshots
       SET quota_identity_id = account_id
@@ -896,6 +905,84 @@ export class BridgeStore {
         this.db.prepare('DELETE FROM codex_auth_candidate_runtime WHERE name = ?').run(name);
         this.db.prepare('DELETE FROM codex_auth_quota_snapshots WHERE candidate_name = ?').run(name);
     }
+    recordCodexAuthPoolInventory(names) {
+        if (names.length === 0) {
+            return;
+        }
+        const now = Date.now();
+        const upsert = this.db.prepare(`
+      INSERT INTO codex_auth_pool_history (name, first_seen_at, last_seen_at, deleted_at, delete_reason, invalid_delete_count)
+      VALUES (?, ?, ?, NULL, NULL, 0)
+      ON CONFLICT(name) DO UPDATE SET
+        last_seen_at = excluded.last_seen_at,
+        deleted_at = NULL,
+        delete_reason = NULL
+    `);
+        const seen = new Set(names);
+        this.db.exec('BEGIN');
+        try {
+            for (const name of seen) {
+                upsert.run(name, now, now);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    recordCodexAuthCandidateInvalidDelete(name, reason = null) {
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO codex_auth_pool_history (
+        name,
+        first_seen_at,
+        last_seen_at,
+        deleted_at,
+        delete_reason,
+        invalid_delete_count
+      )
+      VALUES (?, ?, ?, ?, ?, 1)
+      ON CONFLICT(name) DO UPDATE SET
+        last_seen_at = excluded.last_seen_at,
+        deleted_at = excluded.deleted_at,
+        delete_reason = excluded.delete_reason,
+        invalid_delete_count = codex_auth_pool_history.invalid_delete_count
+          + CASE WHEN codex_auth_pool_history.deleted_at IS NULL THEN 1 ELSE 0 END
+    `).run(name, now, now, now, reason);
+    }
+    recordCodexAuthCandidateRemoved(name, reason = null) {
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO codex_auth_pool_history (
+        name,
+        first_seen_at,
+        last_seen_at,
+        deleted_at,
+        delete_reason,
+        invalid_delete_count
+      )
+      VALUES (?, ?, ?, ?, ?, 0)
+      ON CONFLICT(name) DO UPDATE SET
+        last_seen_at = excluded.last_seen_at,
+        deleted_at = excluded.deleted_at,
+        delete_reason = excluded.delete_reason
+    `).run(name, now, now, now, reason);
+    }
+    getCodexAuthPoolStats() {
+        const row = this.db.prepare(`
+      SELECT
+        COUNT(*) AS total_seen,
+        COALESCE(SUM(CASE WHEN deleted_at IS NULL THEN 1 ELSE 0 END), 0) AS alive,
+        COALESCE(SUM(invalid_delete_count), 0) AS deleted_invalid
+      FROM codex_auth_pool_history
+    `).get();
+        return {
+            totalSeen: Number(row?.total_seen ?? 0),
+            alive: Number(row?.alive ?? 0),
+            deletedInvalid: Number(row?.deleted_invalid ?? 0),
+        };
+    }
     setCodexAuthQuotaSnapshot(runtimeId, candidateName, accountId, quotaIdentityId, snapshot) {
         this.db.prepare(`
       INSERT INTO codex_auth_quota_snapshots (

package/docs/cross-node-auth-sync.md

@@ -92,6 +92,7 @@ AUTH_SYNC_KEY=<shared key with at least 32 bytes>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 AUTH_SYNC_NODE_ID=workstation-a
 AUTH_SYNC_PEERS=@foxclaw_node_b_bot
+AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 ```
 
 Node B:
@@ -103,6 +104,7 @@ AUTH_SYNC_KEY=<shared key with at least 32 bytes>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 AUTH_SYNC_NODE_ID=workstation-b
 AUTH_SYNC_PEERS=@foxclaw_node_a_bot
+AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 ```
 
 For more peers, separate bot usernames with commas:
@@ -168,6 +170,8 @@ Note: `/auth sync push all` saying “sent” only means this node successfully
 
 When cross-node sync is enabled, the contact bot private chat receives node-level notifications: local auth updates and the peers being contacted, received remote bundles and whether they were queued or immediately validated, import success/skip/failure reasons, recovery peer queries and peer replies, and a manual-intervention notice when every peer lacks an importable copy. Refresh/send/import bursts are grouped into short summaries so one candidate update does not produce separate start, receive, mirror-write, and completion messages. Recovery and manual-intervention notices remain explicit. Remote import validation temporarily restarts the local Codex app-server; during that restart window FoxClaw treats the runtime as non-idle and asks ordinary messages to be resent shortly instead of running them against a restarting bridge. Notifications never include auth contents, tokens, or encrypted bundle payloads.
 
+For a resource-rich pool where individual candidate maintenance is not important, enable `AUTH_AUTO_DELETE_NEEDS_REPAIR=true` or toggle it with `/config auth_auto_delete on`. Candidates that cannot be recovered and would otherwise be marked for repair are deleted locally, a delete tombstone is sent to peers, and candidate-level sync/delete chatter is collapsed into an auth-pool summary.
+
 Starting in 0.5.2, `/auth sync status` separates sync-system `Last error` from per-auth `Candidate failures`. For example, a remote candidate that returns `token_invalidated` or has an expired access token is recorded under that candidate name only; current `auth.json` health is still determined by validating the current auth usage. `local candidate is already newer or equal` is a normal skip, not an error.
 
 Manual `/auth` switches and `/auth reload` recover from same-node local mirrors only and do not send cross-node pull requests. FoxClaw queries peers only during automatic recovery after it detects a real auth problem. Recovery timeout notifications include the request id, candidate name, peer list, and wait duration; if another auth sync message arrived from the same peer during that wait, the notification says the peer was reachable but this request timed out.

package/docs/user-manual.md

@@ -448,6 +448,8 @@ AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 # Optional; FoxClaw generates and persists a local node id when omitted.
 AUTH_SYNC_NODE_ID=workstation-a
+# Optional resource-rich mode: auto-delete unrecoverable candidates across peers.
+AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 ```
 
 Safety boundaries:
@@ -457,6 +459,7 @@ Safety boundaries:
 - Remote imports wait for global local idleness, temporarily switch to the candidate for app-server usage validation, and only then write the candidate.
 - A same-name candidate known to belong to a different account id, or to a different identifiable ChatGPT user/email under the same account, is never overwritten.
 - Cross-node recovery only pulls an already-held valid peer copy and does not rotate refresh tokens during recovery. If no peer has a usable copy, it stops and asks you to maintain auth manually. The background 9-day proactive refresh separately requests the cross-node refresh lease and skips that cycle if the lease is not granted.
+- When `AUTH_AUTO_DELETE_NEEDS_REPAIR=true` is enabled, or the same option is turned on in `/config`, unrecoverable candidates are deleted and propagated to peers with a delete tombstone. Private notifications collapse to an auth-pool summary: total seen, alive, and invalid-deleted.
 
 Dual-active behavior:
 

package/docs/zh/cross-node-auth-sync.md

@@ -92,6 +92,7 @@ AUTH_SYNC_KEY=<至少32字节的共享密钥>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 AUTH_SYNC_NODE_ID=workstation-a
 AUTH_SYNC_PEERS=@foxclaw_node_b_bot
+AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 ```
 
 节点 B：
@@ -103,6 +104,7 @@ AUTH_SYNC_KEY=<至少32字节的共享密钥>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 AUTH_SYNC_NODE_ID=workstation-b
 AUTH_SYNC_PEERS=@foxclaw_node_a_bot
+AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 ```
 
 多节点时，`AUTH_SYNC_PEERS` 用英文逗号分隔：
@@ -168,6 +170,8 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。刷新、发送、导入密集发生时会合并成简短汇总，避免一个候选更新拆成开始、收到、镜像写入和完成多条消息；恢复和人工介入提示仍会明确发出。远端导入验证会临时重启本机 Codex app-server；这段窗口里 FoxClaw 会把 runtime 视为非空闲，并让普通消息稍后重发，而不是送进正在重启的 bridge。通知不会包含 auth 内容、token 或同步密文。
 
+如果这是资源富裕的账号池、不关心单个候选如何维护，可以启用 `AUTH_AUTO_DELETE_NEEDS_REPAIR=true`，或用 `/config auth_auto_delete on` 运行时打开。无法恢复、原本会标记为需要修复的候选会直接本地删除，并向 peer 发送删除 tombstone；候选级同步/删除消息会压缩成 auth 池摘要。
+
 从 0.5.2 起，`/auth sync status` 会把同步系统级 `最近错误` 和单个 auth 的 `候选失败` 分开显示。比如某个远端候选返回 `token_invalidated` 或 access token 过期时，只会记录到该候选名下面；当前 `auth.json` 是否健康仍以当前 auth 的 usage 验证为准。`local candidate is already newer or equal` 属于正常跳过，不会记为错误。
 
 手动 `/auth` 切换和 `/auth reload` 只会尝试同节点本地 mirror 恢复，不会主动向跨节点 peer 发起 pull。只有 FoxClaw 检测到当前 auth 真的出现认证问题并进入自动恢复时，才会向 peer 查询可用副本。恢复超时通知会包含 request id、候选名、peer 列表和等待时长；如果等待期间收到过同 peer 的其他 auth sync 消息，通知会标明 peer 可达但该请求超时。

package/docs/zh/user-manual.md

@@ -448,6 +448,8 @@ AUTH_SYNC_PEERS=@other_node_bot,@third_node_bot
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
 # 可选；不填时 FoxClaw 会生成并持久化本机 node id
 AUTH_SYNC_NODE_ID=workstation-a
+# 可选；资源富裕模式下自动跨节点剔除无法恢复的候选
+AUTH_AUTO_DELETE_NEEDS_REPAIR=false
 ```
 
 安全边界：
@@ -457,6 +459,7 @@ AUTH_SYNC_NODE_ID=workstation-a
 - 远端导入必须等本机全局空闲，再临时切换到待验证 auth、重启 app-server、读取 usage 验证成功后才写入候选。
 - 同名候选如果已知属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱，永远拒绝覆盖。
 - 跨节点恢复只拉取 peer 已持有的有效副本，不会在恢复过程中直接轮换 refresh token；找不到有效副本时会停止，提示你人工维护授权。后台 9 天主动刷新会单独申请跨节点刷新锁，拿不到锁就跳过本轮。
+- 如果开启 `AUTH_AUTO_DELETE_NEEDS_REPAIR=true` 或在 `/config` 中打开自动剔除，无法恢复的候选会直接删除并向 peer 传播删除 tombstone；私聊通知会压缩为 auth 池摘要：历史总数、存活数、因失效剔除数。
 
 双主动流程：
 

package/package.json

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