@foxden-app/foxclaw 0.4.13 → 0.4.15

package/dist/i18n.d.ts

@@ -125,6 +125,8 @@ declare const MESSAGES: {
         readonly status_runtime_weixin: "- Weixin default runtime: connected {connected}, active turns {turns}";
         readonly status_auth_mirror_none: "Last auth mirror: none recorded";
         readonly status_auth_mirror_synced: "Last auth mirror: {candidate} from {source} at {time}";
+        readonly status_auth_sync: "Cross-node auth sync: node {node}, peers {peers}, pending imports {pending}";
+        readonly status_auth_sync_error: "Cross-node auth sync error: {value}";
         readonly status_last_update_none: "Last service update: none recorded";
         readonly status_last_update: "Last service update: {from} -> {to} at {time}";
         readonly status_last_codex_update: "Last Codex update: {value}";
@@ -138,7 +140,8 @@ declare const MESSAGES: {
         readonly auth_reload_restarting: "Restarting Codex app-server to reload auth...";
         readonly auth_reload_done: "Codex app-server restarted. Current auth has been reloaded.";
         readonly auth_reload_blocked_active: "Cannot reload Codex auth while a turn, approval, or question is active. Wait or use /interrupt first.";
-        readonly usage_auth: "Usage: /auth [list [keyword]|filter <all|enabled|attention>|page <n>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|add <name>]";
+        readonly usage_auth: "Usage: /auth [list [keyword]|filter <all|enabled|attention>|page <n>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|sync <status|test|push all>|add <name>]";
+        readonly usage_auth_sync: "Usage: /auth sync <status|test|push all>";
         readonly usage_auth_add: "Usage: /auth add <name>. Use letters, numbers, dot, dash, or underscore.";
         readonly auth_list_title: "Codex auth files:";
         readonly auth_bot: "Bot runtime: {value}";
@@ -180,11 +183,13 @@ declare const MESSAGES: {
         readonly auth_refresh_all_cancelled: "Refresh all cancelled.";
         readonly auth_refresh_all_starting: "Refreshing all ChatGPT auth candidates. Every runtime must stay idle...";
         readonly auth_refresh_all_blocked_active: "Cannot refresh all auth candidates while any runtime, approval, input, login, or auth mirror write is active. Wait or use /interrupt first.";
+        readonly auth_refresh_all_lease_failed: "Cross-node refresh lock was not granted: {error}";
         readonly auth_refresh_all_done: "Auth refresh all complete: {refreshed} refreshed, {skipped} skipped, {failed} failed.";
         readonly auth_refresh_all_refreshed: "Refreshed: {value}";
         readonly auth_refresh_all_skipped: "Skipped non-ChatGPT/invalid candidates: {value}";
         readonly auth_refresh_all_failed: "Failed: {value}";
         readonly auth_auto_switching: "Codex auth problem detected ({error}). Switching: {from} -> {to}...";
+        readonly auth_auto_recovered_current: "Codex auth problem detected ({error}). Recovered a newer same-account credential for {value} and restarted Codex app-server.";
         readonly auth_auto_done: "Auto-switched Codex auth: {from} -> {to}.";
         readonly auth_auto_retrying: "Retrying the same request with the new auth...";
         readonly auth_auto_retry_thread_missing: "Auth was switched, but the original thread is no longer available ({threadId}). Retry was stopped to avoid creating duplicate sessions.";
@@ -197,6 +202,20 @@ declare const MESSAGES: {
         readonly auth_add_cancelled: "New auth login cancelled. Restored previous auth.";
         readonly auth_add_reverted: "Restored previous auth.";
         readonly auth_add_missing_file: "Login completed, but the new auth file was not created: {value}";
+        readonly auth_sync_disabled: "Cross-node auth sync is disabled.";
+        readonly auth_sync_test_sent: "Auth sync test ping sent to {count} peer(s).";
+        readonly auth_sync_push_blocked_active: "Cannot push auth sync while any runtime, approval, input, login, or auth mirror write is active.";
+        readonly auth_sync_push_done: "Auth sync push complete: sent {sent}, skipped {skipped}.";
+        readonly auth_sync_status_title: "Cross-node auth sync:";
+        readonly auth_sync_status_node: "Node: {value}";
+        readonly auth_sync_status_peers: "Peers: {value}";
+        readonly auth_sync_status_pending: "Pending imports: {value}";
+        readonly auth_sync_status_sent: "Last sent: {value}";
+        readonly auth_sync_status_received: "Last received: {value}";
+        readonly auth_sync_status_imported: "Last import: {value}";
+        readonly auth_sync_status_pull: "Last pull: {value}";
+        readonly auth_sync_status_lease: "Active refresh lease: {value}";
+        readonly auth_sync_status_error: "Last error: {value}";
         readonly button_login_device: "🔑 Login";
         readonly button_auth_reload: "🔄 Reload auth";
         readonly button_auth_refresh_all_confirm: "⚠️ Accept risk & refresh";
@@ -731,6 +750,8 @@ declare const MESSAGES: {
         readonly status_runtime_weixin: "- 微信默认运行时：连接 {connected}，进行中回复 {turns}";
         readonly status_auth_mirror_none: "最近 auth 镜像：暂无记录";
         readonly status_auth_mirror_synced: "最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步";
+        readonly status_auth_sync: "跨节点 auth 同步：节点 {node}，peer {peers}，待导入 {pending}";
+        readonly status_auth_sync_error: "跨节点 auth 同步错误：{value}";
         readonly status_last_update_none: "最近服务升级：暂无记录";
         readonly status_last_update: "最近服务升级：{from} -> {to}（{time}）";
         readonly status_last_codex_update: "最近 Codex 升级：{value}";
@@ -744,7 +765,8 @@ declare const MESSAGES: {
         readonly auth_reload_restarting: "正在重启 Codex app-server 以重新读取 auth...";
         readonly auth_reload_done: "Codex app-server 已重启，当前 auth 已重新读取。";
         readonly auth_reload_blocked_active: "当前有回复、审批或问题在进行中，不能重载 Codex auth。请先等待，或使用 /interrupt。";
-        readonly usage_auth: "用法：/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <编号>|enable <编号>|disable <编号>|reload|refresh all [confirm]|add <名称>]";
+        readonly usage_auth: "用法：/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <编号>|enable <编号>|disable <编号>|reload|refresh all [confirm]|sync <status|test|push all>|add <名称>]";
+        readonly usage_auth_sync: "用法：/auth sync <status|test|push all>";
         readonly usage_auth_add: "用法：/auth add <名称>。名称只能包含字母、数字、点、短横线或下划线。";
         readonly auth_list_title: "Codex auth 文件：";
         readonly auth_bot: "Bot runtime：{value}";
@@ -786,11 +808,13 @@ declare const MESSAGES: {
         readonly auth_refresh_all_cancelled: "已取消刷新全部。";
         readonly auth_refresh_all_starting: "正在刷新全部 ChatGPT auth 候选。执行期间所有 runtime 必须保持空闲...";
         readonly auth_refresh_all_blocked_active: "当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能刷新全部 auth。请先等待，或使用 /interrupt。";
+        readonly auth_refresh_all_lease_failed: "跨节点刷新锁未授予：{error}";
         readonly auth_refresh_all_done: "全部 auth 刷新完成：已刷新 {refreshed}，已跳过 {skipped}，失败 {failed}。";
         readonly auth_refresh_all_refreshed: "已刷新：{value}";
         readonly auth_refresh_all_skipped: "已跳过非 ChatGPT/无效候选：{value}";
         readonly auth_refresh_all_failed: "失败：{value}";
         readonly auth_auto_switching: "检测到 Codex auth 问题（{error}），正在切换：{from} -> {to}...";
+        readonly auth_auto_recovered_current: "检测到 Codex auth 问题（{error}），已为 {value} 恢复同账号较新凭据并重启 Codex app-server。";
         readonly auth_auto_done: "已自动切换 Codex auth：{from} -> {to}。";
         readonly auth_auto_retrying: "正在用新的 auth 重试同一条请求...";
         readonly auth_auto_retry_thread_missing: "Auth 已切换，但原线程已经不可用（{threadId}）。已停止重试，避免创建重复 session。";
@@ -803,6 +827,20 @@ declare const MESSAGES: {
         readonly auth_add_cancelled: "新 auth 登录已取消，已恢复之前的 auth。";
         readonly auth_add_reverted: "已恢复之前的 auth。";
         readonly auth_add_missing_file: "登录已完成，但没有创建新的 auth 文件：{value}";
+        readonly auth_sync_disabled: "跨节点 auth 同步未启用。";
+        readonly auth_sync_test_sent: "已向 {count} 个 peer 发送 auth sync 测试 ping。";
+        readonly auth_sync_push_blocked_active: "当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。";
+        readonly auth_sync_push_done: "auth 同步推送完成：已发送 {sent}，已跳过 {skipped}。";
+        readonly auth_sync_status_title: "跨节点 auth 同步：";
+        readonly auth_sync_status_node: "节点：{value}";
+        readonly auth_sync_status_peers: "Peer：{value}";
+        readonly auth_sync_status_pending: "待导入：{value}";
+        readonly auth_sync_status_sent: "最近发送：{value}";
+        readonly auth_sync_status_received: "最近接收：{value}";
+        readonly auth_sync_status_imported: "最近导入：{value}";
+        readonly auth_sync_status_pull: "最近拉取：{value}";
+        readonly auth_sync_status_lease: "当前刷新锁：{value}";
+        readonly auth_sync_status_error: "最近错误：{value}";
         readonly button_login_device: "🔑 设备登录";
         readonly button_auth_reload: "🔄 重载 auth";
         readonly button_auth_refresh_all_confirm: "⚠️ 接受风险并刷新";

package/dist/i18n.js

@@ -123,6 +123,8 @@ const MESSAGES = {
         status_runtime_weixin: '- Weixin default runtime: connected {connected}, active turns {turns}',
         status_auth_mirror_none: 'Last auth mirror: none recorded',
         status_auth_mirror_synced: 'Last auth mirror: {candidate} from {source} at {time}',
+        status_auth_sync: 'Cross-node auth sync: node {node}, peers {peers}, pending imports {pending}',
+        status_auth_sync_error: 'Cross-node auth sync error: {value}',
         status_last_update_none: 'Last service update: none recorded',
         status_last_update: 'Last service update: {from} -> {to} at {time}',
         status_last_codex_update: 'Last Codex update: {value}',
@@ -136,7 +138,8 @@ const MESSAGES = {
         auth_reload_restarting: 'Restarting Codex app-server to reload auth...',
         auth_reload_done: 'Codex app-server restarted. Current auth has been reloaded.',
         auth_reload_blocked_active: 'Cannot reload Codex auth while a turn, approval, or question is active. Wait or use /interrupt first.',
-        usage_auth: 'Usage: /auth [list [keyword]|filter <all|enabled|attention>|page <n>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|add <name>]',
+        usage_auth: 'Usage: /auth [list [keyword]|filter <all|enabled|attention>|page <n>|use <n>|enable <n>|disable <n>|reload|refresh all [confirm]|sync <status|test|push all>|add <name>]',
+        usage_auth_sync: 'Usage: /auth sync <status|test|push all>',
         usage_auth_add: 'Usage: /auth add <name>. Use letters, numbers, dot, dash, or underscore.',
         auth_list_title: 'Codex auth files:',
         auth_bot: 'Bot runtime: {value}',
@@ -178,11 +181,13 @@ const MESSAGES = {
         auth_refresh_all_cancelled: 'Refresh all cancelled.',
         auth_refresh_all_starting: 'Refreshing all ChatGPT auth candidates. Every runtime must stay idle...',
         auth_refresh_all_blocked_active: 'Cannot refresh all auth candidates while any runtime, approval, input, login, or auth mirror write is active. Wait or use /interrupt first.',
+        auth_refresh_all_lease_failed: 'Cross-node refresh lock was not granted: {error}',
         auth_refresh_all_done: 'Auth refresh all complete: {refreshed} refreshed, {skipped} skipped, {failed} failed.',
         auth_refresh_all_refreshed: 'Refreshed: {value}',
         auth_refresh_all_skipped: 'Skipped non-ChatGPT/invalid candidates: {value}',
         auth_refresh_all_failed: 'Failed: {value}',
         auth_auto_switching: 'Codex auth problem detected ({error}). Switching: {from} -> {to}...',
+        auth_auto_recovered_current: 'Codex auth problem detected ({error}). Recovered a newer same-account credential for {value} and restarted Codex app-server.',
         auth_auto_done: 'Auto-switched Codex auth: {from} -> {to}.',
         auth_auto_retrying: 'Retrying the same request with the new auth...',
         auth_auto_retry_thread_missing: 'Auth was switched, but the original thread is no longer available ({threadId}). Retry was stopped to avoid creating duplicate sessions.',
@@ -195,6 +200,20 @@ const MESSAGES = {
         auth_add_cancelled: 'New auth login cancelled. Restored previous auth.',
         auth_add_reverted: 'Restored previous auth.',
         auth_add_missing_file: 'Login completed, but the new auth file was not created: {value}',
+        auth_sync_disabled: 'Cross-node auth sync is disabled.',
+        auth_sync_test_sent: 'Auth sync test ping sent to {count} peer(s).',
+        auth_sync_push_blocked_active: 'Cannot push auth sync while any runtime, approval, input, login, or auth mirror write is active.',
+        auth_sync_push_done: 'Auth sync push complete: sent {sent}, skipped {skipped}.',
+        auth_sync_status_title: 'Cross-node auth sync:',
+        auth_sync_status_node: 'Node: {value}',
+        auth_sync_status_peers: 'Peers: {value}',
+        auth_sync_status_pending: 'Pending imports: {value}',
+        auth_sync_status_sent: 'Last sent: {value}',
+        auth_sync_status_received: 'Last received: {value}',
+        auth_sync_status_imported: 'Last import: {value}',
+        auth_sync_status_pull: 'Last pull: {value}',
+        auth_sync_status_lease: 'Active refresh lease: {value}',
+        auth_sync_status_error: 'Last error: {value}',
         button_login_device: '🔑 Login',
         button_auth_reload: '🔄 Reload auth',
         button_auth_refresh_all_confirm: '⚠️ Accept risk & refresh',
@@ -729,6 +748,8 @@ const MESSAGES = {
         status_runtime_weixin: '- 微信默认运行时：连接 {connected}，进行中回复 {turns}',
         status_auth_mirror_none: '最近 auth 镜像：暂无记录',
         status_auth_mirror_synced: '最近 auth 镜像：{candidate} 由 {source} 于 {time} 同步',
+        status_auth_sync: '跨节点 auth 同步：节点 {node}，peer {peers}，待导入 {pending}',
+        status_auth_sync_error: '跨节点 auth 同步错误：{value}',
         status_last_update_none: '最近服务升级：暂无记录',
         status_last_update: '最近服务升级：{from} -> {to}（{time}）',
         status_last_codex_update: '最近 Codex 升级：{value}',
@@ -742,7 +763,8 @@ const MESSAGES = {
         auth_reload_restarting: '正在重启 Codex app-server 以重新读取 auth...',
         auth_reload_done: 'Codex app-server 已重启，当前 auth 已重新读取。',
         auth_reload_blocked_active: '当前有回复、审批或问题在进行中，不能重载 Codex auth。请先等待，或使用 /interrupt。',
-        usage_auth: '用法：/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <编号>|enable <编号>|disable <编号>|reload|refresh all [confirm]|add <名称>]',
+        usage_auth: '用法：/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <编号>|enable <编号>|disable <编号>|reload|refresh all [confirm]|sync <status|test|push all>|add <名称>]',
+        usage_auth_sync: '用法：/auth sync <status|test|push all>',
         usage_auth_add: '用法：/auth add <名称>。名称只能包含字母、数字、点、短横线或下划线。',
         auth_list_title: 'Codex auth 文件：',
         auth_bot: 'Bot runtime：{value}',
@@ -784,11 +806,13 @@ const MESSAGES = {
         auth_refresh_all_cancelled: '已取消刷新全部。',
         auth_refresh_all_starting: '正在刷新全部 ChatGPT auth 候选。执行期间所有 runtime 必须保持空闲...',
         auth_refresh_all_blocked_active: '当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能刷新全部 auth。请先等待，或使用 /interrupt。',
+        auth_refresh_all_lease_failed: '跨节点刷新锁未授予：{error}',
         auth_refresh_all_done: '全部 auth 刷新完成：已刷新 {refreshed}，已跳过 {skipped}，失败 {failed}。',
         auth_refresh_all_refreshed: '已刷新：{value}',
         auth_refresh_all_skipped: '已跳过非 ChatGPT/无效候选：{value}',
         auth_refresh_all_failed: '失败：{value}',
         auth_auto_switching: '检测到 Codex auth 问题（{error}），正在切换：{from} -> {to}...',
+        auth_auto_recovered_current: '检测到 Codex auth 问题（{error}），已为 {value} 恢复同账号较新凭据并重启 Codex app-server。',
         auth_auto_done: '已自动切换 Codex auth：{from} -> {to}。',
         auth_auto_retrying: '正在用新的 auth 重试同一条请求...',
         auth_auto_retry_thread_missing: 'Auth 已切换，但原线程已经不可用（{threadId}）。已停止重试，避免创建重复 session。',
@@ -801,6 +825,20 @@ const MESSAGES = {
         auth_add_cancelled: '新 auth 登录已取消，已恢复之前的 auth。',
         auth_add_reverted: '已恢复之前的 auth。',
         auth_add_missing_file: '登录已完成，但没有创建新的 auth 文件：{value}',
+        auth_sync_disabled: '跨节点 auth 同步未启用。',
+        auth_sync_test_sent: '已向 {count} 个 peer 发送 auth sync 测试 ping。',
+        auth_sync_push_blocked_active: '当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。',
+        auth_sync_push_done: 'auth 同步推送完成：已发送 {sent}，已跳过 {skipped}。',
+        auth_sync_status_title: '跨节点 auth 同步：',
+        auth_sync_status_node: '节点：{value}',
+        auth_sync_status_peers: 'Peer：{value}',
+        auth_sync_status_pending: '待导入：{value}',
+        auth_sync_status_sent: '最近发送：{value}',
+        auth_sync_status_received: '最近接收：{value}',
+        auth_sync_status_imported: '最近导入：{value}',
+        auth_sync_status_pull: '最近拉取：{value}',
+        auth_sync_status_lease: '当前刷新锁：{value}',
+        auth_sync_status_error: '最近错误：{value}',
         button_login_device: '🔑 设备登录',
         button_auth_reload: '🔄 重载 auth',
         button_auth_refresh_all_confirm: '⚠️ 接受风险并刷新',

package/dist/main.js

@@ -141,7 +141,7 @@ Usage:
   foxclaw --help`);
 }
 async function runServeCli() {
-    const [{ BridgeMessagingRouter }, { TelegramMessagingPort }, { WeixinChannelAdapter }, { WeixinMessagingPort }, { attachIlinkRuntimeFromBridgeLogger }, { loadWeixinAccount }, { Logger }, { BridgeStore }, { TelegramGateway }, { CodexAppClient }, { BridgeSessionCore }, { TelegramChannelAdapter }, { AuthCandidateMirror },] = await Promise.all([
+    const [{ BridgeMessagingRouter }, { TelegramMessagingPort }, { WeixinChannelAdapter }, { WeixinMessagingPort }, { attachIlinkRuntimeFromBridgeLogger }, { loadWeixinAccount }, { Logger }, { BridgeStore }, { TelegramGateway }, { CodexAppClient }, { BridgeSessionCore }, { TelegramChannelAdapter }, { AuthCandidateMirror }, { CrossNodeAuthSync },] = await Promise.all([
         import('./channels/bridge_messaging_router.js'),
         import('./channels/telegram/telegram_messaging_port.js'),
         import('./channels/weixin/weixin_channel_adapter.js'),
@@ -155,6 +155,7 @@ async function runServeCli() {
         import('./controller/controller.js'),
         import('./channels/telegram/telegram_channel_adapter.js'),
         import('./auth/mirror.js'),
+        import('./auth/cross_node_sync.js'),
     ]);
     const config = loadConfig();
     const logger = new Logger(config.logLevel, config.logPath);
@@ -166,6 +167,7 @@ async function runServeCli() {
     let activeTelegramAdapters = [];
     let managedApps = [];
     let activeAuthMirror = null;
+    let activeAuthSync = null;
     try {
         store = new BridgeStore(config.storePath);
         if (config.tgMultiBotMode) {
@@ -206,6 +208,7 @@ async function runServeCli() {
                 const app = new CodexAppClient(runtimeConfig.codexCliBin, runtimeConfig.codexAppLaunchCmd, runtimeConfig.codexAppAutolaunch, runtimeConfig.codexAppServerStatePath, runtimeConfig.codexAppServerLogPath, logger, childEnv, sharedDefaultRuntime ? [] : ['cli_auth_credentials_store="file"']);
                 seeds.push({ id, home, authDir, sharedDefaultRuntime, config: runtimeConfig, bot, app });
             }
+            let authSync = null;
             const mirror = new AuthCandidateMirror(canonicalAuthDir, seeds.map((runtime) => ({
                 id: runtime.id,
                 label: runtime.bot.username ? `@${runtime.bot.username}` : runtime.id,
@@ -217,9 +220,12 @@ async function runServeCli() {
                         await runtime.bot.sendMessage(chatId, message);
                     }
                 },
-            })), logger, path.join(APP_HOME, 'runtime', 'auth-mirror.json'));
+            })), logger, path.join(APP_HOME, 'runtime', 'auth-mirror.json'), {
+                onSynced: async (event) => {
+                    await authSync?.publishCandidate(event.record.candidateName);
+                },
+            });
             await mirror.initialize();
-            mirror.start();
             activeAuthMirror = mirror;
             managedApps = seeds.map((runtime) => runtime.app);
             const selfUpdater = createSelfUpdateRuntime({
@@ -271,15 +277,35 @@ async function runServeCli() {
                         },
                     } : {}),
                     authMirror: mirror.getStatus(),
+                    authSync: authSync?.getStatus() ?? null,
                     lastUpdate: lastSelfUpdate,
                 });
             };
+            const authSyncLocalIdle = () => runtimes.every((runtime) => runtime.core.isIdleForServiceUpdate())
+                && (!activeWeixinCore || activeWeixinCore.isIdleForServiceUpdate())
+                && mirror.isIdle();
             const coordinator = {
-                canSelfUpdate: () => runtimes.every((runtime) => runtime.core.isIdleForServiceUpdate())
-                    && (!activeWeixinCore || activeWeixinCore.isIdleForServiceUpdate())
-                    && mirror.isIdle(),
+                canSelfUpdate: () => authSyncLocalIdle()
+                    && (!authSync || authSync.isIdle()),
                 authCandidateUpdated: (runtimeId, candidateName) => mirror.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined),
-                recoverAuthCandidate: (runtimeId, candidateName) => mirror.recoverRuntimeCandidate(runtimeId, candidateName).then(recovery => recovery !== null),
+                recoverAuthCandidate: async (runtimeId, candidateName) => {
+                    const local = await mirror.recoverRuntimeCandidate(runtimeId, candidateName);
+                    if (local)
+                        return true;
+                    const current = await mirror.readRuntimeCandidate(runtimeId, candidateName)
+                        ?? await mirror.readNewestCandidate(candidateName);
+                    return await authSync?.requestRecovery(candidateName, {
+                        accountId: current?.accountId ?? null,
+                        lastRefreshMs: current?.lastRefreshMs ?? null,
+                    }) ?? false;
+                },
+                acquireAuthRefreshLease: (reason) => authSync?.acquireRefreshLease(reason)
+                    ?? Promise.resolve({ ok: true, leaseId: null }),
+                releaseAuthRefreshLease: (leaseId) => authSync?.releaseRefreshLease(leaseId)
+                    ?? Promise.resolve(),
+                getAuthSyncStatus: () => authSync?.getStatus() ?? null,
+                authSyncPushAll: () => authSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
+                authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0 }),
                 statusUpdated: () => writeAggregateStatus(),
                 getServiceStatus: async () => ({
                     bots: await Promise.all(runtimes.map(async (runtime) => {
@@ -302,6 +328,7 @@ async function runServeCli() {
                         },
                     } : {}),
                     authMirror: mirror.getStatus(),
+                    authSync: authSync?.getStatus() ?? null,
                     lastUpdate: lastSelfUpdate,
                 }),
                 selfUpdateCompleted: (status) => {
@@ -324,6 +351,33 @@ async function runServeCli() {
                 weixinAdapter = new WeixinChannelAdapter(activeWeixinCore, store, config, logger);
             }
             activeTelegramAdapters = runtimes.map((runtime) => runtime.telegram);
+            if (config.authSyncEnabled) {
+                authSync = new CrossNodeAuthSync(buildAuthSyncConfig(config), 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');
+                    },
+                }, {
+                    readLocalCandidate: (candidateName) => mirror.readNewestCandidate(candidateName),
+                    listLocalCandidates: () => mirror.listNewestCandidates(),
+                    validateCandidate: async (candidateName, raw, expectedAccountId) => {
+                        if (!authSyncLocalIdle()) {
+                            return { ok: false, reason: 'runtime is not idle' };
+                        }
+                        const runtime = runtimes.find((entry) => entry.core.isIdleForServiceUpdate()) ?? runtimes[0] ?? null;
+                        if (!runtime) {
+                            return { ok: false, reason: 'no validation runtime is available' };
+                        }
+                        return runtime.core.validateExternalCodexAuthCandidate(candidateName, raw, expectedAccountId);
+                    },
+                    importCandidate: (candidateName, raw, source) => mirror.importExternalCandidate(candidateName, raw, source),
+                    isIdle: authSyncLocalIdle,
+                });
+                await authSync.initialize();
+                activeAuthSync = authSync;
+                attachTelegramAuthSync(seeds[0].bot, authSync, config, logger);
+                authSync.start();
+            }
+            mirror.start();
             process.on('unhandledRejection', (error) => {
                 logger.error('process.unhandled_rejection', { error: serializeError(error) });
             });
@@ -341,6 +395,7 @@ async function runServeCli() {
             logger.info('bridge.started', { bots: runtimes.map((runtime) => runtime.id) });
             const shutdown = async (signal) => {
                 logger.info('bridge.shutting_down', { signal });
+                authSync?.stop();
                 mirror.stop();
                 await weixinAdapter?.stop();
                 await activeWeixinCore?.stop();
@@ -372,7 +427,85 @@ async function runServeCli() {
             logPath: path.join(APP_HOME, 'logs', 'update.log'),
             codexCliBin: config.codexCliBin,
         });
-        const core = new BridgeSessionCore(config, store, logger, bot, app, outbound, selfUpdater);
+        let singleAuthSync = null;
+        let singleMirror = null;
+        let core = null;
+        const singleAuthDir = config.codexAuthDir ?? config.codexHome ?? process.env.CODEX_AUTH_DIR ?? path.join(os.homedir(), '.codex');
+        const singleAuthSyncLocalIdle = () => Boolean(core?.isIdleForServiceUpdate())
+            && (!singleMirror || singleMirror.isIdle());
+        const singleCoordinator = config.authSyncEnabled ? {
+            canSelfUpdate: () => singleAuthSyncLocalIdle()
+                && (!singleAuthSync || singleAuthSync.isIdle()),
+            authCandidateUpdated: (runtimeId, candidateName) => singleMirror?.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined) ?? Promise.resolve(),
+            recoverAuthCandidate: async (runtimeId, candidateName) => {
+                const local = await singleMirror?.recoverRuntimeCandidate(runtimeId, candidateName) ?? null;
+                if (local)
+                    return true;
+                const current = await singleMirror?.readRuntimeCandidate(runtimeId, candidateName)
+                    ?? await singleMirror?.readNewestCandidate(candidateName)
+                    ?? null;
+                return await singleAuthSync?.requestRecovery(candidateName, {
+                    accountId: current?.accountId ?? null,
+                    lastRefreshMs: current?.lastRefreshMs ?? null,
+                }) ?? false;
+            },
+            acquireAuthRefreshLease: (reason) => singleAuthSync?.acquireRefreshLease(reason)
+                ?? Promise.resolve({ ok: true, leaseId: null }),
+            releaseAuthRefreshLease: (leaseId) => singleAuthSync?.releaseRefreshLease(leaseId)
+                ?? Promise.resolve(),
+            getAuthSyncStatus: () => singleAuthSync?.getStatus() ?? null,
+            authSyncPushAll: () => singleAuthSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
+            authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0 }),
+            statusUpdated: (status) => {
+                writeRuntimeStatus(config.statusPath, {
+                    ...status,
+                    authMirror: singleMirror?.getStatus() ?? null,
+                    authSync: singleAuthSync?.getStatus() ?? null,
+                });
+            },
+        } : null;
+        if (config.authSyncEnabled) {
+            singleMirror = new AuthCandidateMirror(singleAuthDir, [{
+                    id: 'default',
+                    label: bot.username ? `@${bot.username}` : 'default',
+                    authDir: singleAuthDir,
+                    validate: async (context) => validateRefreshedAuthCandidate({
+                        id: 'default',
+                        authDir: singleAuthDir,
+                        app,
+                    }, context.candidateName),
+                }], logger, path.join(APP_HOME, 'runtime', 'auth-mirror.json'), {
+                onSynced: async (event) => {
+                    await singleAuthSync?.publishCandidate(event.record.candidateName);
+                },
+            });
+            await singleMirror.initialize();
+            activeAuthMirror = singleMirror;
+        }
+        core = new BridgeSessionCore(config, store, logger, bot, app, outbound, selfUpdater, singleCoordinator);
+        if (config.authSyncEnabled && singleMirror) {
+            singleAuthSync = new CrossNodeAuthSync(buildAuthSyncConfig(config), logger, {
+                send: async (peer, envelope) => {
+                    await bot.sendDocument(peer, `foxclaw-auth-sync-${Date.now()}.json`, Buffer.from(envelope, 'utf8'), 'FOXCLAW_AUTH_SYNC_V1');
+                },
+            }, {
+                readLocalCandidate: (candidateName) => singleMirror.readNewestCandidate(candidateName),
+                listLocalCandidates: () => singleMirror.listNewestCandidates(),
+                validateCandidate: async (candidateName, raw, expectedAccountId) => {
+                    if (!singleAuthSyncLocalIdle()) {
+                        return { ok: false, reason: 'runtime is not idle' };
+                    }
+                    return core.validateExternalCodexAuthCandidate(candidateName, raw, expectedAccountId);
+                },
+                importCandidate: (candidateName, raw, source) => singleMirror.importExternalCandidate(candidateName, raw, source),
+                isIdle: singleAuthSyncLocalIdle,
+            });
+            await singleAuthSync.initialize();
+            activeAuthSync = singleAuthSync;
+            attachTelegramAuthSync(bot, singleAuthSync, config, logger);
+            singleAuthSync.start();
+            singleMirror.start();
+        }
         const telegram = new TelegramChannelAdapter(core);
         managedApps = [app];
         activeTelegramAdapters = [telegram];
@@ -392,6 +525,8 @@ async function runServeCli() {
         logger.info('bridge.started', core.getRuntimeStatus());
         const shutdown = async (signal) => {
             logger.info('bridge.shutting_down', { signal });
+            singleAuthSync?.stop();
+            singleMirror?.stop();
             await weixinAdapter?.stop();
             await telegram.stop();
             writeRuntimeStatus(config.statusPath, {
@@ -419,6 +554,7 @@ async function runServeCli() {
         process.on('SIGTERM', () => void shutdown('SIGTERM'));
     }
     catch (error) {
+        activeAuthSync?.stop();
         activeAuthMirror?.stop();
         await weixinAdapter?.stop().catch(() => { });
         await activeWeixinCore?.stop().catch(() => { });
@@ -429,6 +565,54 @@ async function runServeCli() {
         throw error;
     }
 }
+const AUTH_SYNC_TELEGRAM_CAPTION = 'FOXCLAW_AUTH_SYNC_V1';
+function buildAuthSyncConfig(config) {
+    return {
+        enabled: config.authSyncEnabled,
+        transport: config.authSyncTransport,
+        key: config.authSyncKey,
+        peers: config.authSyncPeers,
+        nodeId: config.authSyncNodeId,
+        clusterId: config.authSyncClusterId,
+        statePath: config.authSyncStatePath,
+        tempDir: config.authSyncTempDir,
+    };
+}
+function attachTelegramAuthSync(bot, sync, config, logger) {
+    bot.on('peerDocument', (event) => {
+        void handleTelegramAuthSyncDocument(bot, sync, config, logger, event).catch((error) => {
+            logger.warn('auth.sync.telegram_document_failed', { error: serializeError(error) });
+        });
+    });
+}
+async function handleTelegramAuthSyncDocument(bot, sync, config, logger, event) {
+    const fileName = event.attachment.fileName ?? '';
+    if (event.text.trim() !== AUTH_SYNC_TELEGRAM_CAPTION && !fileName.startsWith('foxclaw-auth-sync-')) {
+        return;
+    }
+    const remoteFile = await bot.getFile(event.attachment.fileId);
+    if (!remoteFile.file_path) {
+        throw new Error('Telegram did not return file_path for auth sync document');
+    }
+    await fs.promises.mkdir(config.authSyncTempDir, { recursive: true, mode: 0o700 });
+    const destination = path.join(config.authSyncTempDir, `inbound-${process.pid}-${Date.now()}-${event.messageId}.json`);
+    try {
+        await bot.downloadResolvedFile(remoteFile.file_path, destination);
+        const raw = await fs.promises.readFile(destination, 'utf8');
+        const handled = await sync.handleIncomingEnvelope(raw, {
+            userId: event.userId,
+            username: event.username,
+        });
+        if (handled) {
+            logger.info('auth.sync.telegram_document_handled', {
+                peer: event.username ? `@${event.username}` : event.userId,
+            });
+        }
+    }
+    finally {
+        await fs.promises.rm(destination, { force: true }).catch(() => undefined);
+    }
+}
 async function validateRefreshedAuthCandidate(runtime, candidateName) {
     const authPath = path.join(runtime.authDir, 'auth.json');
     const candidatePath = path.join(runtime.authDir, candidateName);

package/dist/telegram/api.d.ts

@@ -10,5 +10,11 @@ export interface TelegramRemoteFile {
     file_path?: string;
 }
 export declare function callTelegramApi<T>(botToken: string, method: string, body: Record<string, unknown>): Promise<TelegramApiResult<T>>;
+export declare function callTelegramMultipartApi<T>(botToken: string, method: string, fields: Record<string, string>, files: Array<{
+    fieldName: string;
+    filename: string;
+    contents: Buffer;
+    contentType: string;
+}>): Promise<TelegramApiResult<T>>;
 export declare function getTelegramFile(botToken: string, fileId: string): Promise<TelegramRemoteFile>;
 export declare function downloadTelegramFile(botToken: string, remoteFilePath: string, destinationPath: string): Promise<number>;

package/dist/telegram/api.js

@@ -39,6 +39,53 @@ export async function callTelegramApi(botToken, method, body) {
         request.end();
     });
 }
+export async function callTelegramMultipartApi(botToken, method, fields, files) {
+    const boundary = `foxclaw-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const parts = [];
+    for (const [name, value] of Object.entries(fields)) {
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${escapeMultipartName(name)}"\r\n\r\n${value}\r\n`, 'utf8'));
+    }
+    for (const file of files) {
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${escapeMultipartName(file.fieldName)}"; filename="${escapeMultipartName(file.filename)}"\r\nContent-Type: ${file.contentType}\r\n\r\n`, 'utf8'));
+        parts.push(file.contents);
+        parts.push(Buffer.from('\r\n', 'utf8'));
+    }
+    parts.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'));
+    const payload = Buffer.concat(parts);
+    return new Promise((resolve, reject) => {
+        const request = https.request({
+            host: API_HOST,
+            port: 443,
+            path: `/bot${botToken}/${method}`,
+            method: 'POST',
+            family: 4,
+            headers: {
+                'content-type': `multipart/form-data; boundary=${boundary}`,
+                'content-length': payload.length,
+            },
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            response.on('end', () => {
+                try {
+                    const text = Buffer.concat(chunks).toString('utf8');
+                    resolve(JSON.parse(text));
+                }
+                catch (error) {
+                    reject(new Error(`Failed to parse Telegram response: ${String(error)}`));
+                }
+            });
+        });
+        request.on('error', reject);
+        request.setTimeout(20_000, () => {
+            request.destroy(new Error(`Telegram API request timed out for ${method}`));
+        });
+        request.write(payload);
+        request.end();
+    });
+}
 export async function getTelegramFile(botToken, fileId) {
     const result = await callTelegramApi(botToken, 'getFile', { file_id: fileId });
     if (!result.ok || !result.result) {
@@ -87,3 +134,6 @@ export async function downloadTelegramFile(botToken, remoteFilePath, destination
         response?.destroy();
     }
 }
+function escapeMultipartName(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\r', '').replaceAll('\n', '');
+}

package/dist/telegram/gateway.d.ts

@@ -17,6 +17,14 @@ export interface TelegramTextEvent {
     replyToBot: boolean;
     languageCode?: string;
 }
+export interface TelegramPeerDocumentEvent {
+    chatId: string;
+    userId: string;
+    username: string | null;
+    messageId: number;
+    text: string;
+    attachment: TelegramInboundAttachment;
+}
 export interface TelegramCallbackEvent {
     chatId: string;
     topicId: number | null;
@@ -53,6 +61,7 @@ export declare class TelegramGateway extends EventEmitter {
         text: string;
         callback_data: string;
     }>>, messageThreadId?: number | null): Promise<number>;
+    sendDocument(chatId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
     sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
     editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{
         text: string;