@foxden-app/foxclaw 0.5.18 → 0.5.19

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.19 - 2026-06-08
+
+### 中文
+- 主动后台 auth 刷新现在只保留一条私聊状态消息：开始时发送，完成或拿不到刷新锁时编辑为最终结果，减少开始/完成两条消息的打扰。
+- 本机 auth 镜像和跨节点 auth 同步的刷新 burst 现在会短窗口汇总，把候选镜像、跨节点发送、收到远端包、导入/跳过/失败合成摘要；恢复失败和人工介入提示仍会明确发出。
+
+### English
+- Background proactive auth refresh now keeps one private status message: it sends the starting state and edits that message to the final result or lease failure, reducing separate start/done notifications.
+- Same-node auth mirroring and cross-node auth sync now group refresh bursts into short summaries covering mirror writes, peer sends, received remote bundles, import/skip/failure results, while recovery failures and manual-intervention notices remain explicit.
+
 ## 0.5.18 - 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 私聊里汇总报告发送、接收、排队、导入、失败和人工介入提示。`/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/README_EN.md

@@ -216,7 +216,7 @@ TG_BOT_TOKEN=123456:token_a
 
 FoxClaw remains one system service. By default, it starts an independent `codex app-server` and `CODEX_HOME` for each bot. While bot A is running a turn, bot B can switch its own `/auth` selection. Candidate credentials are mirrored only after online-validated login or refresh; before switching or reloading, FoxClaw also restores a newer same-account credential from another Codex home when available. Current selections remain independent. Send `/help` and `/status` in a private chat with each bot after installation; `/auth` names the runtime being managed, and `/status` summarizes every bot's connection, runtime type, selected auth, and active turns.
 
-When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_contact_bot`. The recommended topology is one contact bot per node; other bots on the same node continue to use local auth mirroring. In multi-bot mode, the first token in `TG_BOT_TOKENS` is the default contact bot. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. The contact bot private chat reports send, receive, queue, import, failure, and manual-intervention states. `/auth sync events [filter]` and `/auth sync trace <requestId>` inspect recent traffic. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease. For full config, `@BotFather` operations, and verification steps, read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
+When multiple machines share the same legally owned account pool, optional cross-node auth sync can be enabled with `AUTH_SYNC_ENABLED=true`, `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS=@peer_contact_bot`. The recommended topology is one contact bot per node; other bots on the same node continue to use local auth mirroring. In multi-bot mode, the first token in `TG_BOT_TOKENS` is the default contact bot. FoxClaw sends encrypted auth bundles through Telegram Bot-to-Bot private messages. A locally verified refresh is pushed to peers, and a node with a bad local candidate can pull an already-held valid peer copy. The contact bot private chat reports grouped send, receive, queue, import, failure, and manual-intervention states. `/auth sync events [filter]` and `/auth sync trace <requestId>` inspect recent traffic. Cross-node recovery never auto-refreshes tokens; `/auth refresh all confirm` first requests a cross-node refresh lease. For full config, `@BotFather` operations, and verification steps, read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
 
 To keep one Telegram bot interoperable with terminal Codex sessions, put the same token in both `TG_BOT_TOKENS` and `TG_BOT_TOKEN`. That bot uses the default `CODEX_HOME` (usually `~/.codex` when unset) and default auth, so it can see local terminal sessions. It no longer has the isolated runtime guarantee: `/auth` switches also affect the terminal and other default runtimes.
 

package/dist/auth/mirror.d.ts

@@ -3,7 +3,7 @@ export interface AuthMirrorRuntime {
     id: string;
     label?: string;
     authDir: string;
-    notify?: (message: string) => Promise<void>;
+    notify?: (event: AuthMirrorNotification) => Promise<void>;
     validate?: (context: AuthMirrorValidationContext) => Promise<AuthMirrorValidationResult | boolean>;
 }
 export interface AuthMirrorStatus {
@@ -62,6 +62,17 @@ export interface AuthMirrorSyncAllResult {
 export interface AuthMirrorHooks {
     onSynced?: (event: AuthMirrorSyncedEvent) => Promise<void> | void;
 }
+export type AuthMirrorNotification = {
+    kind: 'local_synced';
+    candidateName: string;
+    sourceRuntimeId: string;
+    sourceLabel: string;
+} | {
+    kind: 'remote_imported';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+};
 export declare class AuthCandidateMirror {
     private readonly canonicalDir;
     private readonly runtimes;

package/dist/auth/mirror.js

@@ -297,8 +297,13 @@ export class AuthCandidateMirror {
                 };
                 await writeMirrorStatus(this.statusPath, this.lastStatus);
                 this.logger.info('auth.mirror.remote_imported', { candidateName, sourceNodeId: source.nodeId });
-                const message = `${candidateName} has been synchronized from remote node ${sourceLabel}.`;
-                await Promise.allSettled(this.runtimes.map((target) => target.notify?.(message)));
+                const notification = {
+                    kind: 'remote_imported',
+                    candidateName,
+                    sourceNodeId: source.nodeId,
+                    sourceLabel,
+                };
+                await Promise.allSettled(this.runtimes.map((target) => target.notify?.(notification)));
                 return {
                     ok: true,
                     imported: true,
@@ -382,8 +387,13 @@ export class AuthCandidateMirror {
             };
             await writeMirrorStatus(this.statusPath, this.lastStatus);
             this.logger.info('auth.mirror.synced', { sourceRuntimeId: runtime.id, name });
-            const message = `${name} has been refreshed by ${sourceLabel} and synchronized to the other Codex homes.`;
-            await Promise.allSettled(this.runtimes.map((target) => target.notify?.(message)));
+            const notification = {
+                kind: 'local_synced',
+                candidateName: name,
+                sourceRuntimeId: runtime.id,
+                sourceLabel,
+            };
+            await Promise.allSettled(this.runtimes.map((target) => target.notify?.(notification)));
             await this.hooks.onSynced?.({
                 status: this.lastStatus,
                 record: {

package/dist/auth/notifications.d.ts

@@ -0,0 +1,27 @@
+import type { AppLocale } from '../types.js';
+import type { AuthSyncNotification } from './cross_node_sync.js';
+import type { AuthMirrorNotification } from './mirror.js';
+export type AuthRefreshNotificationItem = {
+    source: 'mirror';
+    event: AuthMirrorNotification;
+} | {
+    source: 'auth_sync';
+    event: AuthSyncNotification;
+};
+export interface AuthRefreshNotificationDestination {
+    key: string;
+    locale: AppLocale;
+    sendMessage: (text: string) => Promise<unknown>;
+}
+export interface AuthRefreshNotificationAggregator {
+    enqueueMirror(destination: AuthRefreshNotificationDestination, event: AuthMirrorNotification): void;
+    enqueueAuthSync(destination: AuthRefreshNotificationDestination, event: AuthSyncNotification): boolean;
+    flushAll(): Promise<void>;
+}
+interface AuthNotificationLogger {
+    warn(message: string, meta?: unknown): void;
+}
+export declare function createAuthRefreshNotificationAggregator(logger: AuthNotificationLogger, delayMs?: number): AuthRefreshNotificationAggregator;
+export declare function isAggregateableAuthSyncNotification(event: AuthSyncNotification): boolean;
+export declare function formatAggregatedAuthRefreshNotifications(locale: AppLocale, items: AuthRefreshNotificationItem[]): string | null;
+export {};

package/dist/auth/notifications.js

@@ -0,0 +1,235 @@
+const AUTH_REFRESH_NOTIFICATION_AGGREGATE_DELAY_MS = 8_000;
+const AUTH_REFRESH_NOTIFICATION_LIST_LIMIT = 8;
+export function createAuthRefreshNotificationAggregator(logger, delayMs = AUTH_REFRESH_NOTIFICATION_AGGREGATE_DELAY_MS) {
+    const queues = new Map();
+    const flush = async (key) => {
+        const queue = queues.get(key);
+        if (!queue)
+            return;
+        if (queue.timer) {
+            clearTimeout(queue.timer);
+            queue.timer = null;
+        }
+        queues.delete(key);
+        const message = formatAggregatedAuthRefreshNotifications(queue.locale, queue.items);
+        if (!message)
+            return;
+        try {
+            await queue.sendMessage(message);
+        }
+        catch (error) {
+            logger.warn('auth.notification_aggregate_send_failed', { error: formatError(error) });
+        }
+    };
+    const enqueue = (destination, item) => {
+        const existing = queues.get(destination.key);
+        const queue = existing ?? {
+            locale: destination.locale,
+            sendMessage: destination.sendMessage,
+            items: [],
+            timer: null,
+        };
+        queue.locale = destination.locale;
+        queue.sendMessage = destination.sendMessage;
+        queue.items.push(item);
+        if (queue.timer) {
+            clearTimeout(queue.timer);
+        }
+        queue.timer = setTimeout(() => {
+            void flush(destination.key);
+        }, delayMs);
+        queue.timer.unref();
+        queues.set(destination.key, queue);
+    };
+    return {
+        enqueueMirror(destination, event) {
+            enqueue(destination, { source: 'mirror', event });
+        },
+        enqueueAuthSync(destination, event) {
+            if (!isAggregateableAuthSyncNotification(event)) {
+                return false;
+            }
+            enqueue(destination, { source: 'auth_sync', event });
+            return true;
+        },
+        async flushAll() {
+            await Promise.all([...queues.keys()].map((key) => flush(key)));
+        },
+    };
+}
+export function isAggregateableAuthSyncNotification(event) {
+    switch (event.kind) {
+        case 'candidate_publish_started':
+        case 'candidate_publish_completed':
+        case 'candidate_publish_failed':
+        case 'remote_bundle_received':
+        case 'remote_import_imported':
+        case 'remote_import_skipped':
+        case 'remote_import_failed':
+            return true;
+        default:
+            return false;
+    }
+}
+export function formatAggregatedAuthRefreshNotifications(locale, items) {
+    const localSynced = [];
+    const mirrorRemoteImports = [];
+    const publishes = new Map();
+    const remoteBundles = new Map();
+    const remoteImports = new Map();
+    for (const item of items) {
+        if (item.source === 'mirror') {
+            if (item.event.kind === 'local_synced') {
+                localSynced.push({
+                    candidateName: item.event.candidateName,
+                    sourceLabel: item.event.sourceLabel,
+                });
+            }
+            else {
+                mirrorRemoteImports.push({
+                    candidateName: item.event.candidateName,
+                    sourceNodeId: item.event.sourceNodeId,
+                    sourceLabel: item.event.sourceLabel,
+                });
+            }
+            continue;
+        }
+        const event = item.event;
+        switch (event.kind) {
+            case 'candidate_publish_started':
+                publishes.set(event.candidateName, {
+                    candidateName: event.candidateName,
+                    peers: event.peers,
+                    state: 'sending',
+                    reason: null,
+                });
+                break;
+            case 'candidate_publish_completed':
+                publishes.set(event.candidateName, {
+                    candidateName: event.candidateName,
+                    peers: event.peers,
+                    state: 'sent',
+                    reason: null,
+                });
+                break;
+            case 'candidate_publish_failed':
+                publishes.set(event.candidateName, {
+                    candidateName: event.candidateName,
+                    peers: event.peers,
+                    state: 'failed',
+                    reason: event.reason,
+                });
+                break;
+            case 'remote_bundle_received':
+                remoteBundles.set(remoteKey(event), {
+                    candidateName: event.candidateName,
+                    sourceNodeId: event.sourceNodeId,
+                    sourceLabel: event.sourceLabel,
+                    peer: event.peer,
+                    queued: event.queued,
+                });
+                break;
+            case 'remote_import_imported':
+            case 'remote_import_skipped':
+            case 'remote_import_failed':
+                remoteImports.set(remoteKey(event), {
+                    candidateName: event.candidateName,
+                    sourceNodeId: event.sourceNodeId,
+                    sourceLabel: event.sourceLabel,
+                    peer: event.peer,
+                    state: event.kind === 'remote_import_imported'
+                        ? 'imported'
+                        : event.kind === 'remote_import_skipped'
+                            ? 'skipped'
+                            : 'failed',
+                    reason: 'reason' in event ? event.reason : null,
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    const lines = [locale === 'zh' ? 'auth 刷新/同步汇总' : 'Auth refresh/sync summary'];
+    const failedPublishes = [...publishes.values()].filter((entry) => entry.state === 'failed');
+    const failedImports = [...remoteImports.values()].filter((entry) => entry.state === 'failed');
+    const sentPublishes = [...publishes.values()].filter((entry) => entry.state === 'sent');
+    const sendingPublishes = [...publishes.values()].filter((entry) => entry.state === 'sending');
+    const imported = [...remoteImports.values()].filter((entry) => entry.state === 'imported');
+    const skipped = [...remoteImports.values()].filter((entry) => entry.state === 'skipped');
+    const pendingRemote = [...remoteBundles.entries()]
+        .filter(([key]) => !remoteImports.has(key))
+        .map(([, entry]) => entry);
+    const coveredRemoteImportKeys = new Set([...remoteImports.values()]
+        .map((entry) => `${entry.candidateName}\0${entry.sourceNodeId}`));
+    const mirrorRemoteOnly = mirrorRemoteImports
+        .filter((entry) => !coveredRemoteImportKeys.has(`${entry.candidateName}\0${entry.sourceNodeId}`));
+    if (failedPublishes.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node send failed', '跨节点发送失败', failedPublishes.map((entry) => `${entry.candidateName} -> ${formatPeerList(entry.peers, locale)} (${clipInline(entry.reason ?? '')})`)));
+    }
+    if (failedImports.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node import failed', '跨节点导入失败', failedImports.map((entry) => `${entry.candidateName} <- ${formatSource(entry.sourceLabel, entry.sourceNodeId)} (${clipInline(entry.reason ?? '')})`)));
+    }
+    if (localSynced.length > 0) {
+        lines.push(formatLine(locale, 'Same-node mirror', '同节点镜像', dedupe(localSynced.map((entry) => `${entry.candidateName} <- ${entry.sourceLabel}`))));
+    }
+    if (sentPublishes.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node sent', '跨节点已发送', sentPublishes.map((entry) => `${entry.candidateName} -> ${formatPeerList(entry.peers, locale)}`)));
+    }
+    if (sendingPublishes.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node sending', '跨节点发送中', sendingPublishes.map((entry) => `${entry.candidateName} -> ${formatPeerList(entry.peers, locale)}`)));
+    }
+    if (imported.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node imported', '跨节点已导入', imported.map((entry) => `${entry.candidateName} <- ${formatSource(entry.sourceLabel, entry.sourceNodeId)}`)));
+    }
+    if (skipped.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node skipped', '跨节点已跳过', skipped.map((entry) => `${entry.candidateName} <- ${formatSource(entry.sourceLabel, entry.sourceNodeId)} (${clipInline(entry.reason ?? '')})`)));
+    }
+    if (pendingRemote.length > 0) {
+        lines.push(formatLine(locale, 'Cross-node pending', '跨节点待处理', pendingRemote.map((entry) => {
+            const state = locale === 'zh'
+                ? (entry.queued ? '已排队' : '验证中')
+                : (entry.queued ? 'queued' : 'validating');
+            return `${entry.candidateName} <- ${formatSource(entry.sourceLabel, entry.sourceNodeId)} (${state})`;
+        })));
+    }
+    if (mirrorRemoteOnly.length > 0) {
+        lines.push(formatLine(locale, 'Remote mirror write', '远端镜像写入', mirrorRemoteOnly.map((entry) => `${entry.candidateName} <- ${formatSource(entry.sourceLabel, entry.sourceNodeId)}`)));
+    }
+    return lines.length > 1 ? lines.join('\n') : null;
+}
+function remoteKey(event) {
+    return `${event.candidateName}\0${event.sourceNodeId}\0${event.peer}\0${event.mode ?? 'push'}`;
+}
+function formatLine(locale, enLabel, zhLabel, values) {
+    return `${locale === 'zh' ? zhLabel : enLabel}: ${formatCompactList(values, locale)}`;
+}
+function formatCompactList(values, locale) {
+    const unique = dedupe(values).filter(Boolean);
+    if (unique.length <= AUTH_REFRESH_NOTIFICATION_LIST_LIMIT) {
+        return unique.join(', ');
+    }
+    const shown = unique.slice(0, AUTH_REFRESH_NOTIFICATION_LIST_LIMIT).join(', ');
+    const remaining = unique.length - AUTH_REFRESH_NOTIFICATION_LIST_LIMIT;
+    return locale === 'zh'
+        ? `${shown}，另 ${remaining} 项`
+        : `${shown}, and ${remaining} more`;
+}
+function formatPeerList(peers, locale) {
+    return peers.length > 0 ? peers.join(', ') : (locale === 'zh' ? '无' : 'none');
+}
+function formatSource(sourceLabel, sourceNodeId) {
+    return sourceLabel === sourceNodeId ? sourceNodeId : `${sourceLabel} / ${sourceNodeId}`;
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+function clipInline(value, limit = 120) {
+    const clean = value.replace(/\s+/g, ' ').trim();
+    if (clean.length <= limit) {
+        return clean;
+    }
+    return `${clean.slice(0, Math.max(0, limit - 3))}...`;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/controller/controller.d.ts

@@ -87,6 +87,7 @@ export declare class BridgeSessionCore {
     private selfUpdatePollTimer;
     private proactiveAuthRefreshTimer;
     private proactiveAuthRefreshInProgress;
+    private proactiveAuthRefreshStatusMessage;
     private attachedThreads;
     private botUsername;
     private lastError;

package/dist/controller/controller.js

@@ -136,6 +136,7 @@ export class BridgeSessionCore {
     selfUpdatePollTimer = null;
     proactiveAuthRefreshTimer = null;
     proactiveAuthRefreshInProgress = false;
+    proactiveAuthRefreshStatusMessage = null;
     attachedThreads = new Set();
     botUsername = null;
     lastError = null;
@@ -4388,11 +4389,11 @@ export class BridgeSessionCore {
                 this.logger.warn('codex.auth_proactive_refresh_lease_failed', { reason: lease.reason });
                 await this.notifyProactiveAuthRefresh(locale, t(locale, 'auth_proactive_refresh_lease_failed', {
                     error: lease.reason ?? t(locale, 'unknown'),
-                }));
+                }), true);
                 return;
             }
             const result = await this.refreshCodexAuthCandidates(new Set(dueCandidates.map(candidate => candidate.name)));
-            await this.notifyProactiveAuthRefresh(locale, formatAuthRefreshAllResult(locale, result, 'proactive'));
+            await this.notifyProactiveAuthRefresh(locale, formatAuthRefreshAllResult(locale, result, 'proactive'), true);
         }
         finally {
             await this.coordinator?.releaseAuthRefreshLease?.(lease?.leaseId ?? null);
@@ -4408,14 +4409,32 @@ export class BridgeSessionCore {
             return 'en';
         return this.localeForChat(privateScope.scopeId);
     }
-    async notifyProactiveAuthRefresh(locale, message) {
+    async notifyProactiveAuthRefresh(locale, message, final = false) {
         const identity = this.bot.identity;
         if (!identity)
             return;
         const privateScope = this.store.getTelegramPrivateScope(identity);
         if (!privateScope)
             return;
-        await this.bot.sendMessage(privateScope.chatId, message).catch((error) => {
+        const previous = this.proactiveAuthRefreshStatusMessage;
+        if (previous?.chatId === privateScope.chatId) {
+            try {
+                await this.bot.editMessage(privateScope.chatId, previous.messageId, message, []);
+                if (final) {
+                    this.proactiveAuthRefreshStatusMessage = null;
+                }
+                return;
+            }
+            catch (error) {
+                this.logger.warn('codex.auth_proactive_refresh_notify_edit_failed', { error: toErrorMeta(error) });
+            }
+        }
+        await this.bot.sendMessage(privateScope.chatId, message).then((messageId) => {
+            this.proactiveAuthRefreshStatusMessage = final ? null : { chatId: privateScope.chatId, messageId };
+        }).catch((error) => {
+            if (final) {
+                this.proactiveAuthRefreshStatusMessage = null;
+            }
             this.logger.warn('codex.auth_proactive_refresh_notify_failed', { error: toErrorMeta(error) });
         });
     }

package/dist/main.js

@@ -8,6 +8,7 @@ import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
+import { createAuthRefreshNotificationAggregator, } from './auth/notifications.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 import { buildFoxclawSystemdUnitText, buildSystemdRestartHelperArgs, cgroupContainsSystemdUnit, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns, } from './systemd.js';
@@ -196,6 +197,7 @@ async function runServeCli() {
     ]);
     const config = loadConfig();
     const logger = new Logger(config.logLevel, config.logPath);
+    const authNotificationAggregator = createAuthRefreshNotificationAggregator(logger);
     attachIlinkRuntimeFromBridgeLogger(logger, config.wxIlinkRouteTag);
     const processLock = acquireProcessLock(config.lockPath);
     let store = null;
@@ -251,12 +253,7 @@ async function runServeCli() {
                 label: runtime.bot.username ? `@${runtime.bot.username}` : runtime.id,
                 authDir: runtime.authDir,
                 validate: async (context) => validateRefreshedAuthCandidate(runtime, context.candidateName),
-                notify: async (message) => {
-                    const chatId = store.getTelegramPrivateChatId(runtime.id);
-                    if (chatId) {
-                        await runtime.bot.sendMessage(chatId, message);
-                    }
-                },
+                notify: createAuthMirrorNotifier(store, runtime.id, runtime.bot, authNotificationAggregator),
             })), logger, path.join(APP_HOME, 'runtime', 'auth-mirror.json'), {
                 onSynced: async (event) => {
                     await authSync?.publishCandidate(event.record.candidateName);
@@ -428,7 +425,7 @@ async function runServeCli() {
                     },
                     importCandidate: (candidateName, raw, source) => mirror.importExternalCandidate(candidateName, raw, source),
                     isIdle: authSyncLocalIdle,
-                    notify: createAuthSyncNotifier(store, authSyncTransportBot.bot),
+                    notify: createAuthSyncNotifier(store, authSyncTransportBot.bot, authNotificationAggregator),
                 });
                 await authSync.initialize();
                 activeAuthSync = authSync;
@@ -453,6 +450,7 @@ async function runServeCli() {
             logger.info('bridge.started', { bots: runtimes.map((runtime) => runtime.id) });
             const shutdown = async (signal) => {
                 logger.info('bridge.shutting_down', { signal });
+                await authNotificationAggregator.flushAll();
                 authSync?.stop();
                 mirror.stop();
                 await weixinAdapter?.stop();
@@ -573,7 +571,7 @@ async function runServeCli() {
                 },
                 importCandidate: (candidateName, raw, source) => singleMirror.importExternalCandidate(candidateName, raw, source),
                 isIdle: singleAuthSyncLocalIdle,
-                notify: createAuthSyncNotifier(store, bot),
+                notify: createAuthSyncNotifier(store, bot, authNotificationAggregator),
             });
             await singleAuthSync.initialize();
             activeAuthSync = singleAuthSync;
@@ -600,6 +598,7 @@ async function runServeCli() {
         logger.info('bridge.started', core.getRuntimeStatus());
         const shutdown = async (signal) => {
             logger.info('bridge.shutting_down', { signal });
+            await authNotificationAggregator.flushAll();
             singleAuthSync?.stop();
             singleMirror?.stop();
             await weixinAdapter?.stop();
@@ -630,6 +629,7 @@ async function runServeCli() {
         process.on('SIGTERM', () => void shutdown('SIGTERM'));
     }
     catch (error) {
+        await authNotificationAggregator.flushAll().catch(() => { });
         activeAuthSync?.stop();
         activeAuthMirror?.stop();
         await weixinAdapter?.stop().catch(() => { });
@@ -641,7 +641,20 @@ async function runServeCli() {
         throw error;
     }
 }
-function createAuthSyncNotifier(store, bot) {
+function createAuthMirrorNotifier(store, botId, bot, aggregator) {
+    return async (event) => {
+        const privateScope = store.getTelegramPrivateScope(botId);
+        if (!privateScope)
+            return;
+        const locale = store.getChatSettings(privateScope.scopeId)?.locale ?? 'en';
+        aggregator.enqueueMirror({
+            key: authNotificationDestinationKey(botId, privateScope.chatId),
+            locale,
+            sendMessage: (text) => bot.sendMessage(privateScope.chatId, text),
+        }, event);
+    };
+}
+function createAuthSyncNotifier(store, bot, aggregator) {
     return async (event) => {
         if (!bot.identity)
             return;
@@ -649,9 +662,20 @@ function createAuthSyncNotifier(store, bot) {
         if (!privateScope)
             return;
         const locale = store.getChatSettings(privateScope.scopeId)?.locale ?? 'en';
+        const destination = {
+            key: authNotificationDestinationKey(bot.identity, privateScope.chatId),
+            locale,
+            sendMessage: (text) => bot.sendMessage(privateScope.chatId, text),
+        };
+        if (aggregator.enqueueAuthSync(destination, event)) {
+            return;
+        }
         await bot.sendMessage(privateScope.chatId, formatAuthSyncNotification(locale, event));
     };
 }
+function authNotificationDestinationKey(botId, chatId) {
+    return `${botId}:${chatId}`;
+}
 function formatAuthSyncNotification(locale, event) {
     const peers = 'peers' in event ? formatPeerList(event.peers, locale) : '';
     if (locale === 'zh') {

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

@@ -166,7 +166,7 @@ Confirm that pending imports were processed, or that the candidate exists or has
 
 Note: `/auth sync push all` saying “sent” only means this node successfully handed encrypted packages to Telegram. It does not prove the peer wrote files. The peer imports only when it is globally idle, usage validation succeeds, same-name candidates belong to the same account id and compatible ChatGPT user/email identity, and the remote `last_refresh` is newer than the local copy. If the local file is already equal or newer, it will not change and `Last import` may remain empty.
 
-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. Notifications never include auth contents, tokens, or encrypted bundle payloads.
+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. Notifications never include auth contents, tokens, or encrypted bundle payloads.
 
 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.
 

package/docs/user-manual.md

@@ -421,11 +421,11 @@ When an auth candidate has already failed while in use and FoxClaw cannot recove
 
 `/auth refresh all` is a command-only maintenance action because ChatGPT refresh tokens are rotated. It is allowed only when every Telegram runtime, the Weixin runtime, approvals, inputs, logins, and auth mirroring are idle. The command first shows a risk confirmation: if OpenAI/Codex consumes an old refresh token but the new token cannot be saved because of network, process, or disk failure, that candidate may require device login or phone verification again. After confirmation, FoxClaw visits every ChatGPT candidate, asks Codex to force-refresh tokens with `account/read refreshToken=true`, verifies the result through the usage endpoint, mirrors successful candidates, restores the original current auth, and shows a summary.
 
-OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token replay grace period. Codex refreshes automatically when an access token approaches expiry; when it cannot parse the access-token `exp`, current Codex uses a `last_refresh` fallback of about 8 days. The panel labels candidates without a refresh record in that interval as `not recently refreshed`. FoxClaw also checks once per hour in the background: if an enabled ChatGPT candidate has a `last_refresh` older than 9 days, FoxClaw proactively refreshes that batch only when every runtime is idle, no approvals/inputs/logins/auth mirror writes are active, and the node holds the cross-node refresh lease. The private bot chat reports the proactive refresh result, and newer candidates continue through same-node mirroring and cross-node sync.
+OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token replay grace period. Codex refreshes automatically when an access token approaches expiry; when it cannot parse the access-token `exp`, current Codex uses a `last_refresh` fallback of about 8 days. The panel labels candidates without a refresh record in that interval as `not recently refreshed`. FoxClaw also checks once per hour in the background: if an enabled ChatGPT candidate has a `last_refresh` older than 9 days, FoxClaw proactively refreshes that batch only when every runtime is idle, no approvals/inputs/logins/auth mirror writes are active, and the node holds the cross-node refresh lease. The private bot chat shows one proactive-refresh status message and edits it to the final result. Newer candidates continue through same-node mirroring and cross-node sync, and bursty mirror/cross-node refresh notices are grouped into short summary messages.
 
 ### 6.4 Cross-Node Auth Sync
 
-Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`. The contact bot private chat reports send, receive, queue, import, failure, recovery-query, and manual-intervention states; per-candidate validation failures are shown as candidate failures instead of overwriting the sync-system last error. Recent bot-to-bot traffic is also kept in an event ring so `/auth sync events [filter]` and `/auth sync trace <requestId>` can explain a specific candidate, peer, or request.
+Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`. The contact bot private chat reports send, receive, queue, import, failure, recovery-query, and manual-intervention states; refresh/send/import bursts are grouped into summaries, while recovery and manual-intervention notices remain explicit. Per-candidate validation failures are shown as candidate failures instead of overwriting the sync-system last error. Recent bot-to-bot traffic is also kept in an event ring so `/auth sync events [filter]` and `/auth sync trace <requestId>` can explain a specific candidate, peer, or request.
 
 For the full design, safety boundaries, `.env` examples, and troubleshooting, read the [Cross-Node Auth Sync Setup Guide](./cross-node-auth-sync.md).
 

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

@@ -166,7 +166,7 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致且 ChatGPT 用户/邮箱身份兼容，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
 
-启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。通知不会包含 auth 内容、token 或同步密文。
+启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。刷新、发送、导入密集发生时会合并成简短汇总，避免一个候选更新拆成开始、收到、镜像写入和完成多条消息；恢复和人工介入提示仍会明确发出。通知不会包含 auth 内容、token 或同步密文。
 
 从 0.5.2 起，`/auth sync status` 会把同步系统级 `最近错误` 和单个 auth 的 `候选失败` 分开显示。比如某个远端候选返回 `token_invalidated` 或 access token 过期时，只会记录到该候选名下面；当前 `auth.json` 是否健康仍以当前 auth 的 usage 验证为准。`local candidate is already newer or equal` 属于正常跳过，不会记为错误。
 

package/docs/zh/user-manual.md

@@ -421,11 +421,11 @@ Candidates: 2
 
 `/auth refresh all` 是仅命令入口的维护操作，因为 ChatGPT refresh token 会被轮换。只有所有 Telegram runtime、微信 runtime、审批、待输入、登录流程和 auth 镜像写入都空闲时才允许执行。命令会先显示风险确认：如果 OpenAI/Codex 已经消费旧 refresh token，但因为网络、进程或磁盘故障导致新 token 没能成功保存，该候选可能需要重新设备登录，甚至重新手机号验证。确认后，它会逐个访问 ChatGPT 候选，让 Codex 通过 `account/read refreshToken=true` 强制刷新 token，再用 usage 接口验证，成功后镜像到其他 bot home，最后恢复原本的当前 auth 并显示摘要。
 
-OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放宽限期。Codex 会在 access token 临近到期时自动刷新；如果 access token 里无法解析 `exp`，Codex 当前使用 `last_refresh` 超过约 8 天作为兜底刷新条件。面板把超过 8 天没有刷新记录的候选标为“长期未刷新”。FoxClaw 还会在后台每小时检查一次：已启用的 ChatGPT 候选如果 `last_refresh` 超过 9 天，会在所有 runtime 空闲、没有审批/待输入/登录/auth 镜像写入，并且拿到跨节点刷新锁后，主动刷新这一批候选。主动刷新完成后会私聊通知，并把较新的候选继续镜像和跨节点同步。
+OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放宽限期。Codex 会在 access token 临近到期时自动刷新；如果 access token 里无法解析 `exp`，Codex 当前使用 `last_refresh` 超过约 8 天作为兜底刷新条件。面板把超过 8 天没有刷新记录的候选标为“长期未刷新”。FoxClaw 还会在后台每小时检查一次：已启用的 ChatGPT 候选如果 `last_refresh` 超过 9 天，会在所有 runtime 空闲、没有审批/待输入/登录/auth 镜像写入，并且拿到跨节点刷新锁后，主动刷新这一批候选。私聊里会显示一条主动刷新状态消息，并在结束时编辑成最终结果；较新的候选会继续镜像和跨节点同步，成批出现的镜像/跨节点刷新通知会合并成简短汇总。
 
 ### 6.4 跨节点 auth 同步
 
-跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示；单个候选验证失败会作为“候选失败”显示，不会覆盖同步系统级最近错误。最近 bot-to-bot 通讯会保存在事件环里，可用 `/auth sync events [过滤]` 和 `/auth sync trace <requestId>` 追查某个候选、peer 或请求。
+跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示；刷新、发送、导入密集发生时会合并成汇总，恢复和人工介入提示仍会明确发出。单个候选验证失败会作为“候选失败”显示，不会覆盖同步系统级最近错误。最近 bot-to-bot 通讯会保存在事件环里，可用 `/auth sync events [过滤]` 和 `/auth sync trace <requestId>` 追查某个候选、peer 或请求。
 
 完整设计、安全边界、`.env` 示例和排查步骤见 [跨节点 auth 同步配置指南](./cross-node-auth-sync.md)。
 

package/package.json

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