@foxden-app/foxclaw 0.4.17 → 0.5.0

package/CHANGELOG.md

@@ -2,17 +2,19 @@
 
 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.4.17 - 2026-06-04
+## 0.5.0 - 2026-06-04
 
 ### 中文
 - 明确跨节点 auth 同步推荐架构：每节点一个联系人 bot；多 bot 模式默认使用 `TG_BOT_TOKENS` 的第一个 token 作为联系人，同节点其他 bot 继续走本机 auth 镜像。
 - `/auth sync status` 和 `/status` 现在显示联系人 bot，避免在非联系人 bot 上执行命令时误判实际发包身份。
 - `/auth sync test` 升级为等待 peer 加密 pong 的真实握手，并显示未回应 peer；同时文档补充 BotFather MiniApp 入口、不要误进 Configure Mini App，以及 `push all` 只代表发送成功、不代表对端已导入。
+- 跨节点 auth 同步现在会通过联系人 bot 私聊通知发送、接收、排队、导入、跳过、失败和恢复查询进度；所有 peer 都无法提供可用副本时会明确提示人工介入。
 
 ### English
 - Clarified the recommended cross-node auth sync topology: one contact bot per node. In multi-bot mode, the first `TG_BOT_TOKENS` entry is the default contact while other same-node bots keep using local auth mirroring.
 - `/auth sync status` and `/status` now show the contact bot so commands run from a non-contact bot no longer obscure the actual sender identity.
 - `/auth sync test` now waits for encrypted peer pong replies and reports missing peers. Documentation now covers the BotFather MiniApp entry point, avoids the Configure Mini App confusion, and explains that `push all` only proves send success, not peer import.
+- Cross-node auth sync now sends contact-bot private notifications for send, receive, queue, import, skip, failure, and recovery query progress; it explicitly asks for manual intervention when every peer lacks an importable copy.
 
 ## 0.4.16 - 2026-06-04
 

package/README.md

@@ -212,7 +212,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 已持有的有效副本。跨节点恢复不会自动刷新 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 私聊里报告发送、接收、排队、导入、失败和人工介入提示。跨节点恢复不会自动刷新 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

@@ -212,7 +212,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. 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 send, receive, queue, import, failure, and manual-intervention states. 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/cross_node_sync.d.ts

@@ -35,6 +35,101 @@ export interface AuthSyncValidationResult {
     ok: boolean;
     reason?: string | null;
 }
+export type AuthSyncRemoteImportMode = 'push' | 'pull';
+export type AuthSyncPullResponseResult = 'sent' | 'candidate_not_found' | 'account_mismatch' | 'not_newer';
+export type AuthSyncNotification = {
+    kind: 'candidate_publish_started';
+    candidateName: string;
+    peers: string[];
+} | {
+    kind: 'candidate_publish_completed';
+    candidateName: string;
+    peers: string[];
+} | {
+    kind: 'candidate_publish_failed';
+    candidateName: string;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'push_all_started';
+    candidateCount: number;
+    peers: string[];
+} | {
+    kind: 'push_all_completed';
+    sent: number;
+    skipped: number;
+    peers: string[];
+} | {
+    kind: 'push_all_failed';
+    sent: number;
+    skipped: number;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'remote_bundle_received';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    queued: boolean;
+    queueLength: number;
+} | {
+    kind: 'remote_import_imported';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    mode: AuthSyncRemoteImportMode;
+} | {
+    kind: 'remote_import_skipped';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    mode: AuthSyncRemoteImportMode;
+    reason: string;
+} | {
+    kind: 'remote_import_failed';
+    candidateName: string;
+    sourceNodeId: string;
+    sourceLabel: string;
+    peer: string;
+    mode: AuthSyncRemoteImportMode;
+    reason: string;
+} | {
+    kind: 'recovery_started';
+    candidateName: string;
+    peers: string[];
+} | {
+    kind: 'recovery_peer_empty';
+    candidateName: string;
+    peer: string;
+    reason: string;
+} | {
+    kind: 'recovery_peer_bundle_received';
+    candidateName: string;
+    peer: string;
+    sourceNodeId: string;
+} | {
+    kind: 'recovery_failed';
+    candidateName: string;
+    peers: string[];
+    reason: string;
+} | {
+    kind: 'pull_request_received';
+    candidateName: string;
+    peer: string;
+    requesterNodeId: string;
+} | {
+    kind: 'pull_response_sent';
+    candidateName: string;
+    peer: string;
+    result: AuthSyncPullResponseResult;
+    reason: string | null;
+} | {
+    kind: 'sync_error';
+    reason: string;
+};
 export interface AuthSyncImportCallbacks {
     readLocalCandidate: (candidateName: string) => Promise<AuthMirrorCandidateRecord | null>;
     listLocalCandidates: () => Promise<AuthMirrorCandidateRecord[]>;
@@ -44,6 +139,7 @@ export interface AuthSyncImportCallbacks {
         label?: string | null;
     }) => Promise<AuthMirrorImportResult>;
     isIdle: () => boolean;
+    notify?: (event: AuthSyncNotification) => Promise<void>;
 }
 export interface AuthSyncTransport {
     send: (peer: string, envelope: string) => Promise<void>;
@@ -75,6 +171,7 @@ export declare class CrossNodeAuthSync {
     private timer;
     private activeRemoteLease;
     private activeLocalLease;
+    private lastNotifiedError;
     private state;
     constructor(config: AuthSyncConfig, logger: Logger, transport: AuthSyncTransport, callbacks: AuthSyncImportCallbacks);
     initialize(): Promise<void>;
@@ -99,6 +196,7 @@ export declare class CrossNodeAuthSync {
     private handleMessage;
     private handlePullRequest;
     private handlePullResponse;
+    private markPullPeerUnavailable;
     private handleDigest;
     private handleLeaseRequest;
     private handleLeaseReply;
@@ -116,6 +214,9 @@ export declare class CrossNodeAuthSync {
     private matchConfiguredPeer;
     private expireLeases;
     private recordError;
+    private rejectImport;
+    private notify;
+    private notifyError;
     private writeState;
 }
 export declare function readAccessTokenExpiresAtMs(raw: string): number | null;

package/dist/auth/cross_node_sync.js

@@ -27,6 +27,7 @@ export class CrossNodeAuthSync {
     timer = null;
     activeRemoteLease = null;
     activeLocalLease = null;
+    lastNotifiedError = null;
     state = {
         lastSentAt: null,
         lastReceivedAt: null,
@@ -116,10 +117,24 @@ export class CrossNodeAuthSync {
         const record = await this.callbacks.readLocalCandidate(candidateName);
         if (!record)
             return false;
-        await this.sendToAll({
-            kind: 'push.bundle',
-            ...bundleFromRecord(record),
-        });
+        this.notify({ kind: 'candidate_publish_started', candidateName, peers: [...this.peers] });
+        try {
+            await this.sendToAll({
+                kind: 'push.bundle',
+                ...bundleFromRecord(record),
+            });
+            this.notify({ kind: 'candidate_publish_completed', candidateName, peers: [...this.peers] });
+        }
+        catch (error) {
+            this.recordError(`candidate publish failed for ${candidateName}: ${formatError(error)}`, false);
+            this.notify({
+                kind: 'candidate_publish_failed',
+                candidateName,
+                peers: [...this.peers],
+                reason: formatError(error),
+            });
+            throw error;
+        }
         return true;
     }
     async pushAll() {
@@ -127,18 +142,34 @@ export class CrossNodeAuthSync {
             return { sent: 0, skipped: 0 };
         let sent = 0;
         let skipped = 0;
-        for (const record of await this.callbacks.listLocalCandidates()) {
-            if (!isAuthCandidateName(record.candidateName)) {
-                skipped += 1;
-                continue;
+        const records = await this.callbacks.listLocalCandidates();
+        this.notify({ kind: 'push_all_started', candidateCount: records.length, peers: [...this.peers] });
+        try {
+            for (const record of records) {
+                if (!isAuthCandidateName(record.candidateName)) {
+                    skipped += 1;
+                    continue;
+                }
+                await this.sendToAll({
+                    kind: 'push.bundle',
+                    ...bundleFromRecord(record),
+                });
+                sent += 1;
             }
-            await this.sendToAll({
-                kind: 'push.bundle',
-                ...bundleFromRecord(record),
+            this.notify({ kind: 'push_all_completed', sent, skipped, peers: [...this.peers] });
+            return { sent, skipped };
+        }
+        catch (error) {
+            this.recordError(`push all failed: ${formatError(error)}`, false);
+            this.notify({
+                kind: 'push_all_failed',
+                sent,
+                skipped,
+                peers: [...this.peers],
+                reason: formatError(error),
             });
-            sent += 1;
+            throw error;
         }
-        return { sent, skipped };
     }
     async publishDigest() {
         if (!this.isReady())
@@ -154,18 +185,28 @@ export class CrossNodeAuthSync {
         if (!this.isReady() || !isAuthCandidateName(candidateName))
             return false;
         const requestId = crypto.randomUUID();
+        const peers = [...this.peers];
+        this.notify({ kind: 'recovery_started', candidateName, peers });
         const result = await new Promise((resolve) => {
             const timer = setTimeout(() => {
                 const pending = this.pendingPulls.get(requestId);
                 if (pending) {
                     pending.finished = true;
                     this.pendingPulls.delete(requestId);
+                    this.notify({
+                        kind: 'recovery_failed',
+                        candidateName,
+                        peers,
+                        reason: `timed out waiting for ${this.peers.length} auth sync peer response(s)`,
+                    });
                     resolve(false);
                 }
             }, PULL_TIMEOUT_MS);
             timer.unref();
             this.pendingPulls.set(requestId, {
                 candidateName,
+                peers,
+                emptyReplies: new Map(),
                 resolve,
                 timer,
                 finished: false,
@@ -179,7 +220,13 @@ export class CrossNodeAuthSync {
             }).catch((error) => {
                 clearTimeout(timer);
                 this.pendingPulls.delete(requestId);
-                this.recordError(`pull request failed: ${formatError(error)}`);
+                this.recordError(`pull request failed: ${formatError(error)}`, false);
+                this.notify({
+                    kind: 'recovery_failed',
+                    candidateName,
+                    peers: [...this.peers],
+                    reason: formatError(error),
+                });
                 resolve(false);
             });
         });
@@ -301,7 +348,7 @@ export class CrossNodeAuthSync {
                 this.enqueueImport(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
                 return;
             case 'pull.request':
-                await this.handlePullRequest(message, normalizePeerIdentity(peer));
+                await this.handlePullRequest(message, senderNodeId, normalizePeerIdentity(peer));
                 return;
             case 'pull.response':
                 await this.handlePullResponse(message, senderNodeId, sourceLabel, normalizePeerIdentity(peer));
@@ -336,20 +383,47 @@ export class CrossNodeAuthSync {
                 return;
         }
     }
-    async handlePullRequest(message, peer) {
+    async handlePullRequest(message, requesterNodeId, peer) {
         if (!isAuthCandidateName(message.candidateName))
             return;
+        this.notify({
+            kind: 'pull_request_received',
+            candidateName: message.candidateName,
+            peer,
+            requesterNodeId,
+        });
         const record = await this.callbacks.readLocalCandidate(message.candidateName);
         if (!record) {
             await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'candidate not found' });
+            this.notify({
+                kind: 'pull_response_sent',
+                candidateName: message.candidateName,
+                peer,
+                result: 'candidate_not_found',
+                reason: 'candidate not found',
+            });
             return;
         }
         if (message.accountId && record.accountId !== message.accountId) {
             await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'account mismatch' });
+            this.notify({
+                kind: 'pull_response_sent',
+                candidateName: message.candidateName,
+                peer,
+                result: 'account_mismatch',
+                reason: 'account mismatch',
+            });
             return;
         }
         if (message.lastRefreshMs !== null && record.lastRefreshMs <= message.lastRefreshMs) {
             await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'not newer' });
+            this.notify({
+                kind: 'pull_response_sent',
+                candidateName: message.candidateName,
+                peer,
+                result: 'not_newer',
+                reason: 'not newer',
+            });
             return;
         }
         await this.sendToPeer(peer, {
@@ -357,22 +431,68 @@ export class CrossNodeAuthSync {
             requestId: message.requestId,
             bundle: bundleFromRecord(record),
         });
+        this.notify({
+            kind: 'pull_response_sent',
+            candidateName: message.candidateName,
+            peer,
+            result: 'sent',
+            reason: null,
+        });
     }
     async handlePullResponse(message, senderNodeId, sourceLabel, peer) {
         const pending = this.pendingPulls.get(message.requestId);
         if (!pending || pending.finished)
             return;
+        const matchedPeer = this.matchConfiguredPeer(peer) ?? peer;
         if (!message.bundle || message.bundle.candidateName !== pending.candidateName) {
+            const reason = message.reason ?? 'peer did not return a matching candidate';
+            this.notify({
+                kind: 'recovery_peer_empty',
+                candidateName: pending.candidateName,
+                peer,
+                reason,
+            });
+            this.markPullPeerUnavailable(message.requestId, matchedPeer, reason);
             return;
         }
-        const imported = await this.validateAndImport(message.bundle, senderNodeId, sourceLabel, peer);
-        if (!imported)
+        this.notify({
+            kind: 'recovery_peer_bundle_received',
+            candidateName: pending.candidateName,
+            peer,
+            sourceNodeId: senderNodeId,
+        });
+        const outcome = await this.validateAndImport(message.bundle, senderNodeId, sourceLabel, peer, 'pull');
+        if (!outcome.imported) {
+            this.markPullPeerUnavailable(message.requestId, matchedPeer, outcome.reason ?? 'peer candidate was not imported');
             return;
+        }
         pending.finished = true;
         clearTimeout(pending.timer);
         this.pendingPulls.delete(message.requestId);
         pending.resolve(true);
     }
+    markPullPeerUnavailable(requestId, peer, reason) {
+        const pending = this.pendingPulls.get(requestId);
+        if (!pending || pending.finished)
+            return;
+        pending.emptyReplies.set(peer, reason);
+        if (!pending.peers.every(peerName => pending.emptyReplies.has(peerName))) {
+            return;
+        }
+        pending.finished = true;
+        clearTimeout(pending.timer);
+        this.pendingPulls.delete(requestId);
+        const details = pending.peers
+            .map(peerName => `${peerName}: ${pending.emptyReplies.get(peerName) ?? 'no usable candidate'}`)
+            .join('; ');
+        this.notify({
+            kind: 'recovery_failed',
+            candidateName: pending.candidateName,
+            peers: pending.peers,
+            reason: `all peers replied without an importable auth candidate${details ? ` (${details})` : ''}`,
+        });
+        pending.resolve(false);
+    }
     async handleDigest(message, peer) {
         const remote = new Map(message.records.map(record => [record.candidateName, record]));
         for (const local of await this.callbacks.listLocalCandidates()) {
@@ -428,6 +548,7 @@ export class CrossNodeAuthSync {
         }
     }
     enqueueImport(bundle, sourceNodeId, sourceLabel, fromPeer) {
+        const queued = !this.callbacks.isIdle() || this.pendingImports.length > 0;
         this.pendingImports.push({
             bundle,
             sourceNodeId,
@@ -435,6 +556,15 @@ export class CrossNodeAuthSync {
             receivedAt: Date.now(),
             fromPeer,
         });
+        this.notify({
+            kind: 'remote_bundle_received',
+            candidateName: bundle.candidateName,
+            sourceNodeId,
+            sourceLabel: sourceLabel ?? fromPeer,
+            peer: fromPeer,
+            queued,
+            queueLength: this.pendingImports.length,
+        });
         void this.processPendingImports().catch((error) => {
             this.recordError(`remote import failed: ${formatError(error)}`);
         });
@@ -444,40 +574,35 @@ export class CrossNodeAuthSync {
             return;
         while (this.pendingImports.length > 0 && this.callbacks.isIdle()) {
             const pending = this.pendingImports.shift();
-            await this.validateAndImport(pending.bundle, pending.sourceNodeId, pending.sourceLabel, pending.fromPeer);
+            await this.validateAndImport(pending.bundle, pending.sourceNodeId, pending.sourceLabel, pending.fromPeer, 'push');
         }
     }
-    async validateAndImport(bundle, sourceNodeId, sourceLabel, fromPeer) {
+    async validateAndImport(bundle, sourceNodeId, sourceLabel, fromPeer, mode) {
+        const source = sourceLabel ?? fromPeer;
         if (!isValidBundle(bundle)) {
-            this.recordError('remote bundle shape is invalid');
-            return false;
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, 'remote bundle shape is invalid');
         }
         const metadata = parseChatGptAuthMetadata(bundle.rawAuth);
         if (!metadata || metadata.accountId !== bundle.accountId || metadata.lastRefreshMs !== bundle.lastRefreshMs) {
-            this.recordError(`remote bundle metadata mismatch for ${bundle.candidateName}`);
-            return false;
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote bundle metadata mismatch for ${bundle.candidateName}`);
         }
         if (sha256(bundle.rawAuth) !== bundle.authSha256) {
-            this.recordError(`remote bundle hash mismatch for ${bundle.candidateName}`);
-            return false;
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote bundle hash mismatch for ${bundle.candidateName}`);
         }
         const expiresAt = readAccessTokenExpiresAtMs(bundle.rawAuth);
         if (expiresAt === null || expiresAt <= Date.now() + REMOTE_ACCESS_TOKEN_MIN_TTL_MS) {
-            this.recordError(`remote access token is expired or missing exp for ${bundle.candidateName}`);
-            return false;
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote access token is expired or missing exp for ${bundle.candidateName}`);
         }
         const validation = await this.callbacks.validateCandidate(bundle.candidateName, bundle.rawAuth, bundle.accountId);
         if (!validation.ok) {
-            this.recordError(`remote candidate validation failed for ${bundle.candidateName}: ${validation.reason ?? 'unknown'}`);
-            return false;
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote candidate validation failed for ${bundle.candidateName}: ${validation.reason ?? 'unknown'}`);
         }
         const result = await this.callbacks.importCandidate(bundle.candidateName, bundle.rawAuth, {
             nodeId: sourceNodeId,
-            label: sourceLabel ?? fromPeer,
+            label: source,
         });
         if (!result.ok) {
-            this.recordError(`remote candidate import failed for ${bundle.candidateName}: ${result.reason ?? 'unknown'}`);
-            return false;
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote candidate import failed for ${bundle.candidateName}: ${result.reason ?? 'unknown'}`);
         }
         if (result.imported) {
             this.state.lastImportedAt = new Date().toISOString();
@@ -485,8 +610,27 @@ export class CrossNodeAuthSync {
             this.state.lastError = null;
             await this.writeState();
             this.logger.info('auth.sync.imported', { candidateName: bundle.candidateName, sourceNodeId });
+            this.notify({
+                kind: 'remote_import_imported',
+                candidateName: bundle.candidateName,
+                sourceNodeId,
+                sourceLabel: source,
+                peer: fromPeer,
+                mode,
+            });
+        }
+        else {
+            this.notify({
+                kind: 'remote_import_skipped',
+                candidateName: bundle.candidateName,
+                sourceNodeId,
+                sourceLabel: source,
+                peer: fromPeer,
+                mode,
+                reason: result.reason ?? 'local candidate did not need an update',
+            });
         }
-        return result.imported;
+        return { ok: true, imported: result.imported, reason: result.reason ?? null };
     }
     async sendToAll(message) {
         await Promise.all(this.peers.map(peer => this.sendToPeer(peer, message)));
@@ -601,12 +745,41 @@ export class CrossNodeAuthSync {
             this.activeLocalLease = null;
         }
     }
-    recordError(message) {
+    recordError(message, notify = true) {
         this.state.lastError = message;
         this.logger.warn('auth.sync.error', { error: message });
         void this.writeState().catch((error) => {
             this.logger.warn('auth.sync.state_write_failed', { error: formatError(error) });
         });
+        if (notify) {
+            this.notifyError(message);
+        }
+    }
+    rejectImport(bundle, sourceNodeId, sourceLabel, fromPeer, mode, reason) {
+        this.recordError(reason, false);
+        this.notify({
+            kind: 'remote_import_failed',
+            candidateName: bundle.candidateName,
+            sourceNodeId,
+            sourceLabel,
+            peer: fromPeer,
+            mode,
+            reason,
+        });
+        return { ok: false, imported: false, reason };
+    }
+    notify(event) {
+        if (!this.callbacks.notify)
+            return;
+        void this.callbacks.notify(event).catch((error) => {
+            this.logger.warn('auth.sync.notify_failed', { error: formatError(error) });
+        });
+    }
+    notifyError(reason) {
+        if (this.lastNotifiedError === reason)
+            return;
+        this.lastNotifiedError = reason;
+        this.notify({ kind: 'sync_error', reason });
     }
     async writeState() {
         if (!this.config.enabled)

package/dist/main.js

@@ -375,6 +375,7 @@ async function runServeCli() {
                     },
                     importCandidate: (candidateName, raw, source) => mirror.importExternalCandidate(candidateName, raw, source),
                     isIdle: authSyncLocalIdle,
+                    notify: createAuthSyncNotifier(store, authSyncTransportBot.bot),
                 });
                 await authSync.initialize();
                 activeAuthSync = authSync;
@@ -488,6 +489,7 @@ async function runServeCli() {
         }
         core = new BridgeSessionCore(config, store, logger, bot, app, outbound, selfUpdater, singleCoordinator);
         if (config.authSyncEnabled && singleMirror) {
+            await bot.initializeIdentity();
             singleAuthSync = new CrossNodeAuthSync(buildAuthSyncConfig(config, bot.username ? `@${bot.username}` : 'default'), logger, {
                 send: async (peer, envelope) => {
                     await bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
@@ -503,6 +505,7 @@ async function runServeCli() {
                 },
                 importCandidate: (candidateName, raw, source) => singleMirror.importExternalCandidate(candidateName, raw, source),
                 isIdle: singleAuthSyncLocalIdle,
+                notify: createAuthSyncNotifier(store, bot),
             });
             await singleAuthSync.initialize();
             activeAuthSync = singleAuthSync;
@@ -569,6 +572,133 @@ async function runServeCli() {
         throw error;
     }
 }
+function createAuthSyncNotifier(store, bot) {
+    return async (event) => {
+        if (!bot.identity)
+            return;
+        const privateScope = store.getTelegramPrivateScope(bot.identity);
+        if (!privateScope)
+            return;
+        const locale = store.getChatSettings(privateScope.scopeId)?.locale ?? 'en';
+        await bot.sendMessage(privateScope.chatId, formatAuthSyncNotification(locale, event));
+    };
+}
+function formatAuthSyncNotification(locale, event) {
+    const peers = 'peers' in event ? formatPeerList(event.peers, locale) : '';
+    if (locale === 'zh') {
+        switch (event.kind) {
+            case 'candidate_publish_started':
+                return `本机 auth 已更新：${event.candidateName}\n处理：正在同步到跨节点 peer：${peers}`;
+            case 'candidate_publish_completed':
+                return `跨节点 auth 已发出：${event.candidateName}\nPeer：${peers}\n注意：这只代表发送成功，对端导入结果会在对端通知或 /auth sync status 中显示。`;
+            case 'candidate_publish_failed':
+                return `跨节点 auth 发送失败：${event.candidateName}\nPeer：${peers}\n原因：${event.reason}`;
+            case 'push_all_started':
+                return `开始手动推送全部 auth：候选 ${event.candidateCount} 个\nPeer：${peers}`;
+            case 'push_all_completed':
+                return `手动 auth 同步推送完成：已发送 ${event.sent}，已跳过 ${event.skipped}\nPeer：${peers}`;
+            case 'push_all_failed':
+                return `手动 auth 同步推送中断：已发送 ${event.sent}，已跳过 ${event.skipped}\nPeer：${peers}\n原因：${event.reason}`;
+            case 'remote_bundle_received':
+                return [
+                    `收到跨节点 auth：${event.candidateName}`,
+                    `来源：${formatSource(event.sourceLabel, event.sourceNodeId)}，peer ${event.peer}`,
+                    `处理：${event.queued ? `本机忙，已排队等待空闲后验证导入；当前待导入 ${event.queueLength}` : '本机空闲，正在验证 usage 后导入'}`,
+                ].join('\n');
+            case 'remote_import_imported':
+                return `${event.mode === 'pull' ? '已拉取并导入跨节点 auth' : '已导入跨节点 auth'}：${event.candidateName}\n来源：${formatSource(event.sourceLabel, event.sourceNodeId)}\n处理：已写入本机 auth 镜像，并同步到同节点 bot home。`;
+            case 'remote_import_skipped':
+                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 'recovery_started':
+                return `auth 恢复开始：${event.candidateName}\n处理：同节点没有可用较新副本，正在向跨节点 peer 查询：${peers}`;
+            case 'recovery_peer_empty':
+                return `auth 恢复收到 peer 回应但没有可用副本：${event.candidateName}\nPeer：${event.peer}\n原因：${event.reason}`;
+            case 'recovery_peer_bundle_received':
+                return `auth 恢复收到 peer 候选：${event.candidateName}\nPeer：${event.peer}，来源节点：${event.sourceNodeId}\n处理：正在验证 usage 后导入。`;
+            case 'recovery_failed':
+                return `auth 恢复已穷尽：${event.candidateName}\n已查询 peer：${peers}\n原因：${event.reason}\n请人工介入：使用 /auth add <name> 或设备登录重新生成可用 auth。`;
+            case 'pull_request_received':
+                return `收到 peer 的 auth 查询：${event.candidateName}\nPeer：${event.peer}，请求节点：${event.requesterNodeId}`;
+            case 'pull_response_sent':
+                return `已回应 peer 的 auth 查询：${event.candidateName}\nPeer：${event.peer}\n结果：${formatPullResponseResult(event.result, event.reason, locale)}`;
+            case 'sync_error':
+                return `auth sync 需要注意：\n${event.reason}`;
+        }
+    }
+    switch (event.kind) {
+        case 'candidate_publish_started':
+            return `Local auth updated: ${event.candidateName}\nAction: syncing to cross-node peers: ${peers}`;
+        case 'candidate_publish_completed':
+            return `Cross-node auth sent: ${event.candidateName}\nPeers: ${peers}\nNote: this confirms send success only; peer import is reported on the receiving node.`;
+        case 'candidate_publish_failed':
+            return `Cross-node auth send failed: ${event.candidateName}\nPeers: ${peers}\nReason: ${event.reason}`;
+        case 'push_all_started':
+            return `Manual auth sync push started: ${event.candidateCount} candidates\nPeers: ${peers}`;
+        case 'push_all_completed':
+            return `Manual auth sync push complete: sent ${event.sent}, skipped ${event.skipped}\nPeers: ${peers}`;
+        case 'push_all_failed':
+            return `Manual auth sync push stopped: sent ${event.sent}, skipped ${event.skipped}\nPeers: ${peers}\nReason: ${event.reason}`;
+        case 'remote_bundle_received':
+            return [
+                `Received cross-node auth: ${event.candidateName}`,
+                `Source: ${formatSource(event.sourceLabel, event.sourceNodeId)}, peer ${event.peer}`,
+                `Action: ${event.queued ? `queued until this node is idle; pending imports ${event.queueLength}` : 'validating usage before import'}`,
+            ].join('\n');
+        case 'remote_import_imported':
+            return `${event.mode === 'pull' ? 'Pulled and imported cross-node auth' : 'Imported cross-node auth'}: ${event.candidateName}\nSource: ${formatSource(event.sourceLabel, event.sourceNodeId)}\nAction: written to the local auth mirror and same-node bot homes.`;
+        case 'remote_import_skipped':
+            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 'recovery_started':
+            return `Auth recovery started: ${event.candidateName}\nAction: no newer same-node copy was available; querying cross-node peers: ${peers}`;
+        case 'recovery_peer_empty':
+            return `Auth recovery peer replied without usable auth: ${event.candidateName}\nPeer: ${event.peer}\nReason: ${event.reason}`;
+        case 'recovery_peer_bundle_received':
+            return `Auth recovery peer returned a candidate: ${event.candidateName}\nPeer: ${event.peer}, source node: ${event.sourceNodeId}\nAction: validating usage before import.`;
+        case 'recovery_failed':
+            return `Auth recovery exhausted: ${event.candidateName}\nPeers checked: ${peers}\nReason: ${event.reason}\nManual action: use /auth add <name> or device login to create a usable auth.`;
+        case 'pull_request_received':
+            return `Received peer auth recovery request: ${event.candidateName}\nPeer: ${event.peer}, requester node: ${event.requesterNodeId}`;
+        case 'pull_response_sent':
+            return `Replied to peer auth recovery request: ${event.candidateName}\nPeer: ${event.peer}\nResult: ${formatPullResponseResult(event.result, event.reason, locale)}`;
+        case 'sync_error':
+            return `Auth sync needs attention:\n${event.reason}`;
+    }
+}
+function formatPeerList(peers, locale) {
+    return peers.length > 0 ? peers.join(', ') : (locale === 'zh' ? '无' : 'none');
+}
+function formatSource(sourceLabel, sourceNodeId) {
+    return sourceLabel === sourceNodeId ? sourceNodeId : `${sourceLabel} / ${sourceNodeId}`;
+}
+function formatPullResponseResult(result, reason, locale) {
+    const suffix = reason ? ` (${reason})` : '';
+    if (locale === 'zh') {
+        switch (result) {
+            case 'sent':
+                return `已返回较新候选${suffix}`;
+            case 'candidate_not_found':
+                return `本机没有这个候选${suffix}`;
+            case 'account_mismatch':
+                return `账号不匹配，未返回${suffix}`;
+            case 'not_newer':
+                return `本机副本不更新，未返回${suffix}`;
+        }
+    }
+    switch (result) {
+        case 'sent':
+            return `sent newer candidate${suffix}`;
+        case 'candidate_not_found':
+            return `candidate not found${suffix}`;
+        case 'account_mismatch':
+            return `account mismatch; nothing sent${suffix}`;
+        case 'not_newer':
+            return `local copy is not newer; nothing sent${suffix}`;
+    }
+}
 const AUTH_SYNC_TELEGRAM_CAPTION = 'FOXCLAW_AUTH_SYNC_V1';
 function buildAuthSyncConfig(config, transportLabel = null) {
     return {

package/dist/store/database.d.ts

@@ -43,6 +43,10 @@ export declare class BridgeStore {
     setTelegramOffset(botKey: string, updateId: number): void;
     rememberTelegramPrivateScope(botId: string, scopeId: string, chatId: string): void;
     getTelegramPrivateChatId(botId: string): string | null;
+    getTelegramPrivateScope(botId: string): {
+        scopeId: string;
+        chatId: string;
+    } | null;
     getBinding(chatId: string): ThreadBinding | null;
     setBinding(chatId: string, threadId: string, cwd: string | null): void;
     clearBinding(chatId: string): void;

package/dist/store/database.js

@@ -178,6 +178,10 @@ export class BridgeStore {
         const row = this.db.prepare('SELECT chat_id FROM telegram_private_scopes WHERE bot_id = ?').get(botId);
         return row ? String(row.chat_id) : null;
     }
+    getTelegramPrivateScope(botId) {
+        const row = this.db.prepare('SELECT scope_id, chat_id FROM telegram_private_scopes WHERE bot_id = ?').get(botId);
+        return row ? { scopeId: String(row.scope_id), chatId: String(row.chat_id) } : null;
+    }
     getBinding(chatId) {
         const row = this.db.prepare('SELECT chat_id, thread_id, cwd, updated_at FROM chat_bindings WHERE chat_id = ?').get(chatId);
         if (!row)

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

@@ -166,6 +166,8 @@ 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 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.
+
 5. Only test refresh-token rotation after you understand the risk:
 
 ```text

package/docs/user-manual.md

@@ -419,7 +419,7 @@ OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token r
 
 ### 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`.
+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.
 
 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,6 +166,8 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
 
+启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。通知不会包含 auth 内容、token 或同步密文。
+
 5. 只有在完全理解 refresh token 轮换风险时，才测试：
 
 ```text

package/docs/zh/user-manual.md

@@ -419,7 +419,7 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 
 ### 6.4 跨节点 auth 同步
 
-跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。
+跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示。
 
 完整设计、安全边界、`.env` 示例和排查步骤见 [跨节点 auth 同步配置指南](./cross-node-auth-sync.md)。
 

package/package.json

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