@foxden-app/foxclaw 0.4.16 → 0.5.0

package/dist/main.js

@@ -305,7 +305,7 @@ async function runServeCli() {
                     ?? Promise.resolve(),
                 getAuthSyncStatus: () => authSync?.getStatus() ?? null,
                 authSyncPushAll: () => authSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
-                authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0 }),
+                authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
                 statusUpdated: () => writeAggregateStatus(),
                 getServiceStatus: async () => ({
                     bots: await Promise.all(runtimes.map(async (runtime) => {
@@ -352,9 +352,13 @@ async function runServeCli() {
             }
             activeTelegramAdapters = runtimes.map((runtime) => runtime.telegram);
             if (config.authSyncEnabled) {
-                authSync = new CrossNodeAuthSync(buildAuthSyncConfig(config), logger, {
+                const authSyncTransportBot = seeds[0];
+                const authSyncTransportLabel = authSyncTransportBot.bot.username
+                    ? `@${authSyncTransportBot.bot.username}`
+                    : authSyncTransportBot.id;
+                authSync = new CrossNodeAuthSync(buildAuthSyncConfig(config, authSyncTransportLabel), logger, {
                     send: async (peer, envelope) => {
-                        await seeds[0].bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
+                        await authSyncTransportBot.bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
                     },
                 }, {
                     readLocalCandidate: (candidateName) => mirror.readNewestCandidate(candidateName),
@@ -371,10 +375,11 @@ async function runServeCli() {
                     },
                     importCandidate: (candidateName, raw, source) => mirror.importExternalCandidate(candidateName, raw, source),
                     isIdle: authSyncLocalIdle,
+                    notify: createAuthSyncNotifier(store, authSyncTransportBot.bot),
                 });
                 await authSync.initialize();
                 activeAuthSync = authSync;
-                attachTelegramAuthSync(seeds[0].bot, authSync, config, logger);
+                attachTelegramAuthSync(authSyncTransportBot.bot, authSync, config, logger);
                 authSync.start();
             }
             mirror.start();
@@ -455,7 +460,7 @@ async function runServeCli() {
                 ?? Promise.resolve(),
             getAuthSyncStatus: () => singleAuthSync?.getStatus() ?? null,
             authSyncPushAll: () => singleAuthSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
-            authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0 }),
+            authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
             statusUpdated: (status) => {
                 writeRuntimeStatus(config.statusPath, {
                     ...status,
@@ -484,7 +489,8 @@ async function runServeCli() {
         }
         core = new BridgeSessionCore(config, store, logger, bot, app, outbound, selfUpdater, singleCoordinator);
         if (config.authSyncEnabled && singleMirror) {
-            singleAuthSync = new CrossNodeAuthSync(buildAuthSyncConfig(config), logger, {
+            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');
                 },
@@ -499,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;
@@ -565,11 +572,139 @@ 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) {
+function buildAuthSyncConfig(config, transportLabel = null) {
     return {
         enabled: config.authSyncEnabled,
         transport: config.authSyncTransport,
+        transportLabel,
         key: config.authSyncKey,
         peers: config.authSyncPeers,
         nodeId: config.authSyncNodeId,

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/dist/types.d.ts

@@ -363,6 +363,7 @@ export interface RuntimeStatus {
     authSync?: {
         enabled: boolean;
         nodeId: string | null;
+        transportLabel: string | null;
         peers: string[];
         pendingImports: number;
         lastSentAt: string | null;

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

@@ -11,6 +11,7 @@ Use it when:
 - You legally own and maintain the ChatGPT accounts and auth files.
 - Multiple machines run FoxClaw, and each machine has at least one Telegram bot.
 - You want auth files to stay fresh across nodes without routinely rotating refresh tokens.
+- The recommended default is one contact bot per node for cross-node sync. Other bots on the same node continue to use local auth mirroring.
 
 Do not use it when:
 
@@ -44,6 +45,8 @@ Assume two machines:
 - Node A: bot `@foxclaw_node_a_bot`
 - Node B: bot `@foxclaw_node_b_bot`
 
+These are the two node contact bots. `AUTH_SYNC_PEERS` only needs peer node contact bots; you do not need to list every bot running on the same machine. In multi-bot mode, FoxClaw uses the first token in `TG_BOT_TOKENS` as the local contact bot by default. If you want bot 5 to be the contact, put bot 5's token first, or enable Bot-to-Bot for every local bot as a temporary fallback.
+
 Each node should already work independently:
 
 ```bash
@@ -62,16 +65,20 @@ In a private Telegram chat with each bot, verify:
 
 Repeat this for every participating bot:
 
-1. Open Telegram and enter `@BotFather`.
-2. Send `/mybots`.
-3. Select the bot that will participate in auth sync.
-4. Open the bot settings / Mini App settings interface.
+1. Prefer the latest Telegram mobile client; some desktop or older clients do not show the setting.
+2. Open `https://t.me/BotFather?startapp`, or open the `@BotFather` profile and tap **Open App**.
+3. In the BotFather MiniApp, select the contact bot that will participate in auth sync.
+4. Open Settings / Bot Settings.
 5. Find **Bot-to-Bot Communication Mode**.
 6. Enable it.
-7. Repeat for every peer bot.
+7. Repeat for every node contact bot.
+
+Do not use `/mybots` → Bot Settings → **Configure Mini App**. That configures your bot's Mini App URL, not Bot-to-Bot Communication Mode.
 
 Private cross-node sync requires this mode on both bots. Enabling it on only one side is usually not enough for two bots to exchange private sync packets.
 
+If you see `Bad Request: USER_BOT_TO_BOT_DISABLED`, first confirm that both the sender contact bot and recipient contact bot have Bot-to-Bot enabled. In multi-bot mode, the sender contact is the first token in `TG_BOT_TOKENS` by default; it may not be the bot where you typed the command.
+
 ## .env Configuration
 
 Use the same `AUTH_SYNC_KEY` and `AUTH_SYNC_CLUSTER_ID` on all nodes, but give each node a different `AUTH_SYNC_NODE_ID`.
@@ -79,6 +86,7 @@ Use the same `AUTH_SYNC_KEY` and `AUTH_SYNC_CLUSTER_ID` on all nodes, but give e
 Node A:
 
 ```dotenv
+TG_BOT_TOKENS=<node-a-contact-token>,<node-a-other-bot-token>
 AUTH_SYNC_ENABLED=true
 AUTH_SYNC_KEY=<shared key with at least 32 bytes>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
@@ -89,6 +97,7 @@ AUTH_SYNC_PEERS=@foxclaw_node_b_bot
 Node B:
 
 ```dotenv
+TG_BOT_TOKENS=<node-b-contact-token>,<node-b-other-bot-token>
 AUTH_SYNC_ENABLED=true
 AUTH_SYNC_KEY=<shared key with at least 32 bytes>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
@@ -132,6 +141,14 @@ You should see the node id, peer list, and pending imports.
 
 Node A should report that it sent a test ping. Node B's `/auth sync status` should show a recent receive or test-state change.
 
+Starting in 0.4.17, `/auth sync test` waits for an encrypted pong from peers. A healthy result looks like:
+
+```text
+Auth sync test complete: sent 1, replies 1.
+```
+
+If it shows `Missing replies: @peer_bot`, Telegram delivery may have succeeded, but the peer did not receive, decrypt, pass allowlist validation, or run the same auth sync configuration.
+
 3. Use a low-risk candidate for the first broadcast. Make sure every runtime is idle, then run on node A:
 
 ```text
@@ -147,6 +164,10 @@ Node A should report that it sent a test ping. Node B's `/auth sync status` shou
 
 Confirm that pending imports were processed, or that the candidate exists or has a newer timestamp.
 
+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
@@ -174,4 +195,3 @@ With cross-node sync enabled, this command first requests a cross-node refresh l
 **Should I periodically run `/auth refresh all confirm` as keepalive?**
 
 No. Codex refreshes automatically when access tokens expire. Cross-node auth sync propagates auth files that have already refreshed successfully; Refresh all should remain a maintenance command, not a routine keepalive.
-

package/docs/user-manual.md

@@ -419,18 +419,19 @@ 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. Enable Bot-to-Bot Communication Mode for the participating bots in BotFather first.
+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).
 
 In `@BotFather`, repeat this for every participating bot:
 
-1. Open `@BotFather`.
-2. Send `/mybots`.
-3. Select the bot that will participate in sync.
-4. Open the bot settings / Mini App settings interface.
-5. Find and enable **Bot-to-Bot Communication Mode**.
-6. Repeat for every peer bot; private sync requires this mode on both sender and recipient.
+1. Use the latest Telegram mobile client to open `https://t.me/BotFather?startapp`, or open the `@BotFather` profile and tap **Open App**.
+2. In the BotFather MiniApp, select the contact bot that will participate in sync.
+3. Open Settings / Bot Settings.
+4. Find and enable **Bot-to-Bot Communication Mode**.
+5. Repeat for every node contact bot; private sync requires this mode on both sender and recipient.
+
+Do not use `/mybots` → Bot Settings → **Configure Mini App**. That configures your bot's Mini App URL, not Bot-to-Bot Communication Mode.
 
 Example:
 
@@ -460,8 +461,8 @@ Dual-active behavior:
 Commands:
 
 - `/auth sync status`: show node id, peers, recent sends/receives/imports, pending imports, and the latest error.
-- `/auth sync test`: send an encrypted ping to verify peer config, shared key, and Bot-to-Bot private messages.
-- `/auth sync push all`: manually broadcast all locally verified candidates without refreshing tokens.
+- `/auth sync test`: send an encrypted ping and wait for peer pong replies to verify peer config, shared key, and Bot-to-Bot private messages.
+- `/auth sync push all`: manually broadcast all locally verified candidates without refreshing tokens. “Sent” does not mean the peer imported files; check `/auth sync status` and `/auth` on the peer.
 
 Equivalent commands:
 

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

@@ -11,6 +11,7 @@
 - 这些 ChatGPT 账号和 auth 文件都由你合法拥有和维护。
 - 多台机器都运行 FoxClaw，并且每台机器至少有一个 Telegram bot。
 - 你希望 auth 文件在节点间自动保持较新，但不希望日常主动旋转 refresh token。
+- 默认推荐每台机器只选择一个“联系人 bot”参与跨节点同步；同一节点内其他 bot 继续使用原本的本机 auth 镜像。
 
 不适合：
 
@@ -44,6 +45,8 @@ Telegram 官方 Bot Features 文档说明：私聊 bot-to-bot 需要发送方和
 - 节点 A：bot `@foxclaw_node_a_bot`
 - 节点 B：bot `@foxclaw_node_b_bot`
 
+这两个 bot 就是两个节点的联系人。`AUTH_SYNC_PEERS` 只需要写 peer 节点的联系人 bot，不需要把同一台机器上的所有 bot 都互相列进去。多 bot 模式下，FoxClaw 默认使用 `TG_BOT_TOKENS` 里的第一个 token 作为本节点联系人；如果你希望 5 号 bot 当联系人，就把 5 号 token 放到 `TG_BOT_TOKENS` 第一位，或者给全部 bot 都开启 Bot-to-Bot 作为临时兜底。
+
 每个节点都应该先能独立使用 FoxClaw：
 
 ```bash
@@ -62,16 +65,20 @@ foxclaw start
 
 对参与同步的每一个 bot 都做一遍：
 
-1. 打开 Telegram，进入 `@BotFather`。
-2. 发送 `/mybots`。
-3. 选择要参与同步的 bot。
-4. 打开 BotFather 的 bot settings / Mini App 设置界面。
+1. 建议使用最新版 Telegram 手机客户端；部分桌面端或旧客户端看不到这个开关。
+2. 打开 `https://t.me/BotFather?startapp`，或进入 `@BotFather` 资料页后点击 **Open App / 打开应用**。
+3. 在 BotFather MiniApp 中选择要参与同步的联系人 bot。
+4. 进入 Settings / Bot Settings。
 5. 找到 **Bot-to-Bot Communication Mode**。
 6. 启用该开关。
-7. 对所有 peer bot 重复以上步骤。
+7. 对所有节点的联系人 bot 重复以上步骤。
+
+不要走 `/mybots` → Bot Settings → **Configure Mini App**。那是配置你自己 bot 的 Mini App URL，不是 Bot-to-Bot Communication Mode。
 
 私聊跨节点同步要求双方都开启这个模式。只开一个通常不足以让两个 bot 互相私聊传输同步包。
 
+如果你看到 `Bad Request: USER_BOT_TO_BOT_DISABLED`，优先确认两件事：发送方联系人 bot 和接收方联系人 bot 都已经开启 Bot-to-Bot；多 bot 模式下，发送方联系人默认是 `TG_BOT_TOKENS` 的第一个 token，不一定是你当前输入命令的 bot。
+
 ## .env 配置
 
 两台机器使用相同的 `AUTH_SYNC_KEY` 和 `AUTH_SYNC_CLUSTER_ID`，但 `AUTH_SYNC_NODE_ID` 必须不同。
@@ -79,6 +86,7 @@ foxclaw start
 节点 A：
 
 ```dotenv
+TG_BOT_TOKENS=<node-a-contact-token>,<node-a-other-bot-token>
 AUTH_SYNC_ENABLED=true
 AUTH_SYNC_KEY=<至少32字节的共享密钥>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
@@ -89,6 +97,7 @@ AUTH_SYNC_PEERS=@foxclaw_node_b_bot
 节点 B：
 
 ```dotenv
+TG_BOT_TOKENS=<node-b-contact-token>,<node-b-other-bot-token>
 AUTH_SYNC_ENABLED=true
 AUTH_SYNC_KEY=<至少32字节的共享密钥>
 AUTH_SYNC_CLUSTER_ID=my-codex-auth-pool
@@ -132,6 +141,14 @@ foxclaw restart
 
 节点 A 应提示已向 peer 发送测试 ping。节点 B 的 `/auth sync status` 应能看到最近收到的同步事件或测试状态变化。
 
+从 0.4.17 起，`/auth sync test` 会等待 peer 返回加密 pong。正常结果应该类似：
+
+```text
+auth sync 测试完成：已发送 1，收到回应 1。
+```
+
+如果显示 `未回应：@peer_bot`，说明 Telegram 发送可能成功，但对方没有成功接收、解密、通过 allowlist，或没有运行同一组 auth sync 配置。
+
 3. 用低风险候选做第一次广播。先确认所有 bot runtime 空闲，然后在节点 A 执行：
 
 ```text
@@ -147,6 +164,10 @@ foxclaw restart
 
 确认待导入清单被处理，或候选已经出现/更新时间变新。
 
+注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
+
+启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。通知不会包含 auth 内容、token 或同步密文。
+
 5. 只有在完全理解 refresh token 轮换风险时，才测试：
 
 ```text
@@ -174,4 +195,3 @@ foxclaw restart
 **要不要定期 `/auth refresh all confirm` 保活**
 
 不要。Codex 会按 access token 到期自动刷新。FoxClaw 的跨节点同步会同步“已经成功刷新的新 auth”，不应该把 refresh all 当作日常保活。
-

package/docs/zh/user-manual.md

@@ -419,18 +419,19 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 
 ### 6.4 跨节点 auth 同步
 
-跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP；需要先在 BotFather 为参与同步的 bot 开启 Bot-to-Bot Communication Mode。
+跨节点 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)。
 
 在 `@BotFather` 中对每个参与同步的 bot 执行：
 
-1. 打开 `@BotFather`。
-2. 发送 `/mybots`。
-3. 选择参与同步的 bot。
-4. 打开 bot settings / Mini App 设置界面。
-5. 找到并启用 **Bot-to-Bot Communication Mode**。
-6. 对所有 peer bot 重复；私聊同步要求发送方和接收方都开启。
+1. 用最新版 Telegram 手机客户端打开 `https://t.me/BotFather?startapp`，或进入 `@BotFather` 资料页点 **Open App / 打开应用**。
+2. 在 BotFather MiniApp 中选择参与同步的联系人 bot。
+3. 打开 Settings / Bot Settings。
+4. 找到并启用 **Bot-to-Bot Communication Mode**。
+5. 对所有节点的联系人 bot 重复；私聊同步要求发送方和接收方都开启。
+
+不要走 `/mybots` → Bot Settings → **Configure Mini App**；那是配置 bot 的 Mini App URL，不是 Bot-to-Bot Communication Mode。
 
 配置示例：
 
@@ -460,8 +461,8 @@ AUTH_SYNC_NODE_ID=workstation-a
 命令：
 
 - `/auth sync status`：查看 node id、peer、最近收发、最近导入、待导入和最近错误。
-- `/auth sync test`：发送加密 ping，确认 peer、共享密钥和 Bot-to-Bot 私聊可用。
-- `/auth sync push all`：手动广播当前节点已验证的全部候选，不刷新 token。
+- `/auth sync test`：发送加密 ping 并等待 peer 返回 pong，确认 peer、共享密钥和 Bot-to-Bot 私聊可用。
+- `/auth sync push all`：手动广播当前节点已验证的全部候选，不刷新 token；“已发送”不等于对端已经导入，需要在 peer 上看 `/auth sync status` 和 `/auth`。
 
 命令等价用法：
 

package/package.json

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

package/skills/foxclaw/SKILL.md

@@ -70,7 +70,7 @@ Telegram behavior:
 - `/auth` paginates large candidate inventories at 8 rows per page, supports all/enabled/attention filters and filename search, renders actual observed quota windows in text rows, uses compact two-number remaining quota labels on buttons, and omits the repeated `auth.json_` prefix from panel labels without renaming files
 - treat the `/auth` `not recently refreshed` state as a maintenance hint only: OpenAI does not publish a fixed ChatGPT refresh-token lifetime or replay grace period, and FoxClaw must not add routine bulk keepalive refreshes
 - `/auth refresh all` remains a command-only maintenance action, not a panel button; it requires explicit token-rotation risk confirmation, then force-refreshes every ChatGPT candidate through Codex `account/read refreshToken=true`, validates usage, mirrors successful candidates, and restores the original current auth while every runtime is globally idle
-- optional cross-node auth sync uses Telegram Bot-to-Bot private messages with encrypted auth bundles; configure `AUTH_SYNC_ENABLED=true`, a shared `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS`, then use `/auth sync status`, `/auth sync test`, and `/auth sync push all`; cross-node recovery pulls already-held valid peer copies and does not auto-refresh tokens
+- optional cross-node auth sync uses Telegram Bot-to-Bot private messages with encrypted auth bundles; the default topology is one contact bot per node, and in multi-bot mode the first `TG_BOT_TOKENS` entry is the contact transport; configure `AUTH_SYNC_ENABLED=true`, a shared `AUTH_SYNC_KEY`, and `AUTH_SYNC_PEERS` containing peer contact bot usernames, then use `/auth sync status`, `/auth sync test`, and `/auth sync push all`; `/auth sync test` waits for encrypted peer pong replies, while push-all only proves send success and peer import must be checked on the receiver
 - when cross-node auth sync is enabled, `/auth refresh all confirm` must obtain a cross-node refresh lease before rotating refresh tokens; any busy, denying, or non-responsive peer blocks the refresh
 - if `TG_BOT_TOKEN` is also set to one exact token from `TG_BOT_TOKENS`, that bot uses the default/shared-terminal runtime instead of an isolated Telegram home
 - if Weixin is enabled alongside multiple Telegram bots, it remains on the default Codex runtime instead of borrowing a Telegram bot runtime