@foxden-app/foxclaw 0.5.10 → 0.5.11

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.11 - 2026-06-08
+
+### 中文
+- `/auth` 面板的 `Bot runtime` 现在显示 Telegram bot id，例如 `@WuguiAI2_Bot (bot8949529424)`，便于和 `~/.foxclaw/codex/telegram/<botid>/home` 对应。
+- `/auth` 面板新增“安全同步”按钮，并支持 `/auth sync safe`，可在全局空闲时安全打平本机多 bot auth，并把已校验的候选推送到跨节点 peer。
+- 本机 auth mirror 新增全量安全同步路径：只传播通过既有在线校验的刷新候选，同时补齐 canonical 中已知、同账号且更新的 runtime 副本。
+
+### English
+- The `/auth` panel now shows the Telegram bot id in `Bot runtime`, for example `@WuguiAI2_Bot (bot8949529424)`, making it easy to match the runtime with `~/.foxclaw/codex/telegram/<botid>/home`.
+- Added a Safe sync button to the `/auth` panel, plus `/auth sync safe`, to flatten same-node multi-bot auth while globally idle and push validated candidates to cross-node peers.
+- Added a full safe-sync path for the local auth mirror: it only propagates candidates that pass the existing online validation and fills runtime copies from newer same-account canonical candidates.
+
 ## 0.5.10 - 2026-06-08
 
 ### 中文

package/README.md

@@ -39,6 +39,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - 已经装好，想系统了解 `/help`、`/setup`、`/threads`、`/watch`、`/auth` 和账号轮转？看 [用户手册](./docs/zh/user-manual.md)。
 - 想把同一组合法 ChatGPT auth 候选同步到多台机器？看 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
 - 想了解每个版本改了什么？看 [更新日志](./CHANGELOG.md)。
+- 维护者准备发版？看 [发布 runbook](./docs/zh/release.md)。
 - Git、Node、`.env` 都玩得转？直接往下看快速设置。
 - 卡住了？看 [故障排查](./docs/zh/troubleshooting.md)。
 

package/README_EN.md

@@ -39,6 +39,7 @@ FoxClaw is more than message forwarding. It provides Telegram panels for Codex w
 - Already installed and want the full command guide for `/help`, `/setup`, `/threads`, `/watch`, `/auth`, and auth rotation? Read the [User Manual](./docs/user-manual.md).
 - Want to sync the same legally owned ChatGPT auth candidate pool across multiple machines? Read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
 - Want to see what changed in each release? Read the [Changelog](./CHANGELOG.md).
+- Maintaining a release? Use the [Release Runbook](./docs/release.md).
 - Already comfortable with Git, Node, and `.env` files? Use the quick setup below.
 - Something failed? Check [Troubleshooting](./docs/troubleshooting.md).
 

package/dist/auth/mirror.d.ts

@@ -52,6 +52,10 @@ export interface AuthMirrorSyncedEvent {
     status: AuthMirrorStatus;
     record: AuthMirrorCandidateRecord;
 }
+export interface AuthMirrorSyncAllResult {
+    synced: number;
+    skipped: number;
+}
 export interface AuthMirrorHooks {
     onSynced?: (event: AuthMirrorSyncedEvent) => Promise<void> | void;
 }
@@ -77,8 +81,10 @@ export declare class AuthCandidateMirror {
     readRuntimeCandidate(runtimeId: string, candidateName: string): Promise<AuthMirrorCandidateRecord | null>;
     listNewestCandidates(): Promise<AuthMirrorCandidateRecord[]>;
     syncRuntimeCandidate(runtimeId: string, candidateName: string): Promise<boolean>;
+    syncAllRuntimeCandidates(): Promise<AuthMirrorSyncAllResult>;
     recoverRuntimeCandidate(runtimeId: string, candidateName: string): Promise<AuthMirrorRecovery | null>;
     private scan;
+    private distributeCanonicalCandidates;
     importExternalCandidate(candidateName: string, raw: string, source: {
         nodeId: string;
         label?: string | null;

package/dist/auth/mirror.js

@@ -126,6 +126,28 @@ export class AuthCandidateMirror {
             return false;
         return this.withActivity(() => this.propagateValidatedCandidate(runtime, candidateName));
     }
+    async syncAllRuntimeCandidates() {
+        return this.withActivity(async () => {
+            let synced = 0;
+            let skipped = 0;
+            for (const runtime of this.runtimes) {
+                const names = await listAuthCandidateNames(runtime.authDir);
+                for (const name of names) {
+                    if (await this.propagateValidatedCandidate(runtime, name)) {
+                        synced += 1;
+                    }
+                    else {
+                        skipped += 1;
+                    }
+                }
+            }
+            const distributed = await this.distributeCanonicalCandidates();
+            return {
+                synced: synced + distributed.synced,
+                skipped: skipped + distributed.skipped,
+            };
+        });
+    }
     async recoverRuntimeCandidate(runtimeId, candidateName) {
         if (!isAuthCandidateName(candidateName))
             return null;
@@ -169,6 +191,33 @@ export class AuthCandidateMirror {
             }
         });
     }
+    async distributeCanonicalCandidates() {
+        let synced = 0;
+        let skipped = 0;
+        for (const name of await listAuthCandidateNames(this.canonicalDir)) {
+            const canonical = await readChatGptAuthRecord(path.join(this.canonicalDir, name));
+            if (!canonical) {
+                skipped += this.runtimes.length;
+                continue;
+            }
+            for (const runtime of this.runtimes) {
+                const destinationPath = path.join(runtime.authDir, name);
+                const destination = await readChatGptAuthRecord(destinationPath);
+                if (destination && destination.accountId !== canonical.accountId) {
+                    skipped += 1;
+                    this.logger.warn('auth.mirror.distribution_conflict', { runtimeId: runtime.id, name });
+                    continue;
+                }
+                if (destination && destination.lastRefreshMs >= canonical.lastRefreshMs) {
+                    skipped += 1;
+                    continue;
+                }
+                await atomicWrite(destinationPath, canonical.raw);
+                synced += 1;
+            }
+        }
+        return { synced, skipped };
+    }
     async importExternalCandidate(candidateName, raw, source) {
         if (!isAuthCandidateName(candidateName)) {
             return { ok: false, imported: false, reason: 'invalid candidate name' };

package/dist/controller/controller.d.ts

@@ -19,6 +19,12 @@ export interface CoreCoordinator {
     }>;
     releaseAuthRefreshLease?: (leaseId: string | null) => Promise<void>;
     getAuthSyncStatus?: () => RuntimeStatus['authSync'];
+    authSyncSafeAll?: () => Promise<{
+        localSynced: number;
+        localSkipped: number;
+        sent: number;
+        skipped: number;
+    }>;
     authSyncPushAll?: () => Promise<{
         sent: number;
         skipped: number;
@@ -283,6 +289,7 @@ export declare class BridgeSessionCore {
     private notifyProactiveAuthRefresh;
     private handleAuthCommand;
     private handleAuthSyncCommand;
+    private runAuthSafeSyncAll;
     private handleAuthRefreshAllCommand;
     private handleAuthUseCommand;
     private handleAuthToggleCommand;

package/dist/controller/controller.js

@@ -1065,7 +1065,7 @@ export class BridgeSessionCore {
             await this.handleAuthListViewCallback(event, authClearSearchMatch[1], 'clear_search', locale);
             return;
         }
-        const authActionMatch = /^auth:([a-f0-9]+):(login_device|reload|refresh_all_confirm|refresh_all_cancel|refresh_all)$/.exec(event.data);
+        const authActionMatch = /^auth:([a-f0-9]+):(login_device|reload|safe_sync|refresh_all_confirm|refresh_all_cancel|refresh_all)$/.exec(event.data);
         if (authActionMatch) {
             await this.handleAuthPanelActionCallback(event, authActionMatch[1], authActionMatch[2], locale);
             return;
@@ -2956,7 +2956,7 @@ export class BridgeSessionCore {
     authDisplayBotLabel() {
         if (!this.config.tgScopeBotId)
             return null;
-        return this.botUsername ? `@${this.botUsername}` : this.config.tgScopeBotId;
+        return this.botUsername ? `@${this.botUsername} (${this.config.tgScopeBotId})` : this.config.tgScopeBotId;
     }
     ownsScope(scopeId) {
         if (scopeId.startsWith(BRIDGE_SCOPE_WEIXIN_PREFIX)) {
@@ -4467,17 +4467,19 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, message);
             return;
         }
-        if (action === 'push' && args[1]?.toLowerCase() === 'all') {
+        if (action === 'safe' || (action === 'push' && args[1]?.toLowerCase() === 'all')) {
             if (!this.canRunGlobalAuthRefresh()) {
                 await this.sendMessage(scopeId, t(locale, 'auth_sync_push_blocked_active'));
                 return;
             }
-            const result = await this.coordinator?.authSyncPushAll?.();
+            const result = await this.runAuthSafeSyncAll();
             if (!result) {
                 await this.sendMessage(scopeId, t(locale, 'auth_sync_disabled'));
                 return;
             }
-            await this.sendMessage(scopeId, t(locale, 'auth_sync_push_done', {
+            await this.sendMessage(scopeId, t(locale, 'auth_sync_safe_done', {
+                localSynced: result.localSynced,
+                localSkipped: result.localSkipped,
                 sent: result.sent,
                 skipped: result.skipped,
             }));
@@ -4485,6 +4487,16 @@ export class BridgeSessionCore {
         }
         await this.sendMessage(scopeId, t(locale, 'usage_auth_sync'));
     }
+    async runAuthSafeSyncAll() {
+        const safeResult = await this.coordinator?.authSyncSafeAll?.();
+        if (safeResult) {
+            return safeResult;
+        }
+        const pushResult = await this.coordinator?.authSyncPushAll?.();
+        return pushResult
+            ? { localSynced: 0, localSkipped: 0, sent: pushResult.sent, skipped: pushResult.skipped }
+            : null;
+    }
     async handleAuthRefreshAllCommand(scopeId, locale, confirmed = false) {
         if (!this.canRunGlobalAuthRefresh()) {
             await this.sendMessage(scopeId, t(locale, 'auth_refresh_all_blocked_active'));
@@ -4993,6 +5005,37 @@ export class BridgeSessionCore {
             await this.handleLoginDeviceCommand(event.scopeId, locale);
             return;
         }
+        if (action === 'safe_sync') {
+            if (!this.canRunGlobalAuthRefresh()) {
+                await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_sync_push_blocked_active'));
+                return;
+            }
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_sync_safe_starting'));
+            if (record.messageId !== null) {
+                await this.editMessage(event.scopeId, record.messageId, t(locale, 'auth_sync_safe_starting'), []);
+            }
+            const result = await this.runAuthSafeSyncAll();
+            if (!result) {
+                if (record.messageId !== null) {
+                    await this.editMessage(event.scopeId, record.messageId, t(locale, 'auth_sync_disabled'), authChoiceKeyboard(locale, record));
+                }
+                return;
+            }
+            const state = await this.listCodexAuthState();
+            await this.applySharedCodexAuthQuotaSnapshots(state);
+            record.candidates = state.candidates;
+            record.createdAt = Date.now();
+            clampCodexAuthListOffset(record);
+            if (record.messageId !== null) {
+                await this.editMessage(event.scopeId, record.messageId, `${t(locale, 'auth_sync_safe_done', {
+                    localSynced: result.localSynced,
+                    localSkipped: result.localSkipped,
+                    sent: result.sent,
+                    skipped: result.skipped,
+                })}\n\n${renderAuthListMessage(locale, state, this.authDisplayBotLabel(), parseWeixinBridgeScope(event.scopeId) !== null, record)}`, authChoiceKeyboard(locale, record));
+            }
+            return;
+        }
         if (action === 'refresh_all') {
             if (!this.canRunGlobalAuthRefresh()) {
                 await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_refresh_all_blocked_active'));
@@ -8409,7 +8452,7 @@ function renderAuthListMessage(locale, state, botLabel = null, includeWeixinCopy
     if (state.candidates.length === 0) {
         lines.push(t(locale, 'auth_no_candidates'));
         if (includeWeixinCopyPaste) {
-            lines.push('', t(locale, 'weixin_copy_paste_divider'), t(locale, 'weixin_copy_auth_title'), '/login_device', '/auth reload', '/permissions');
+            lines.push('', t(locale, 'weixin_copy_paste_divider'), t(locale, 'weixin_copy_auth_title'), '/login_device', '/auth sync safe', '/auth reload', '/permissions');
         }
         return lines.join('\n');
     }
@@ -8442,7 +8485,7 @@ function renderAuthListMessage(locale, state, botLabel = null, includeWeixinCopy
     if (includeWeixinCopyPaste) {
         lines.push('', t(locale, 'weixin_copy_paste_divider'), t(locale, 'weixin_copy_auth_title'), ...page.visible.map(({ index }) => `/auth use ${index + 1}`), ...page.visible.map(({ candidate, index }) => candidate.disabled
             ? `/auth enable ${index + 1}`
-            : `/auth disable ${index + 1}`), '/auth filter all', '/auth filter enabled', '/auth filter attention', '/auth list <keyword>', '/login_device', '/auth reload', '/permissions');
+            : `/auth disable ${index + 1}`), '/auth filter all', '/auth filter enabled', '/auth filter attention', '/auth list <keyword>', '/login_device', '/auth sync safe', '/auth reload', '/permissions');
     }
     return lines.join('\n');
 }
@@ -8480,7 +8523,10 @@ function authChoiceKeyboard(locale, record) {
         { text: t(locale, 'button_permissions'), callback_data: 'nav:permissions' },
         { text: t(locale, 'button_login_device'), callback_data: `auth:${record.localId}:login_device` },
     ]);
-    rows.push([{ text: t(locale, 'button_auth_reload'), callback_data: `auth:${record.localId}:reload` }]);
+    rows.push([
+        { text: t(locale, 'button_auth_safe_sync'), callback_data: `auth:${record.localId}:safe_sync` },
+        { text: t(locale, 'button_auth_reload'), callback_data: `auth:${record.localId}:reload` },
+    ]);
     return rows;
 }
 function formatCodexAuthCandidateDisplayName(name) {

package/dist/i18n.d.ts

@@ -143,8 +143,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]|sync <status|test|push all>|add <name>]";
-        readonly usage_auth_sync: "Usage: /auth sync <status|events [filter]|trace <requestId>|test|push all>";
+        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|safe|push all>|add <name>]";
+        readonly usage_auth_sync: "Usage: /auth sync <status|events [filter]|trace <requestId>|test|safe|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}";
@@ -212,6 +212,8 @@ declare const MESSAGES: {
         readonly auth_sync_test_sent: "Auth sync test complete: sent {sent}, replies {replied}.";
         readonly auth_sync_test_missing: "Missing replies: {value}";
         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_safe_starting: "Safely syncing auth across local bot runtimes and cross-node peers...";
+        readonly auth_sync_safe_done: "Safe auth sync complete: local synced {localSynced}, local skipped {localSkipped}; cross-node sent {sent}, skipped {skipped}.";
         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}";
@@ -235,6 +237,7 @@ declare const MESSAGES: {
         readonly auth_sync_trace_missing: "Usage: /auth sync trace <requestId>";
         readonly button_login_device: "🔑 Login";
         readonly button_auth_reload: "🔄 Reload auth";
+        readonly button_auth_safe_sync: "🧷 Safe sync";
         readonly button_auth_refresh_all_confirm: "⚠️ Accept risk & refresh";
         readonly button_auth_enable: "✅";
         readonly button_auth_disable: "⏸️";
@@ -796,8 +799,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]|sync <status|test|push all>|add <名称>]";
-        readonly usage_auth_sync: "用法：/auth sync <status|events [过滤]|trace <requestId>|test|push all>";
+        readonly usage_auth: "用法：/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <编号>|enable <编号>|disable <编号>|reload|refresh all [confirm]|sync <status|test|safe|push all>|add <名称>]";
+        readonly usage_auth_sync: "用法：/auth sync <status|events [过滤]|trace <requestId>|test|safe|push all>";
         readonly usage_auth_add: "用法：/auth add <名称>。名称只能包含字母、数字、点、短横线或下划线。";
         readonly auth_list_title: "Codex auth 文件：";
         readonly auth_bot: "Bot runtime：{value}";
@@ -865,6 +868,8 @@ declare const MESSAGES: {
         readonly auth_sync_test_sent: "auth sync 测试完成：已发送 {sent}，收到回应 {replied}。";
         readonly auth_sync_test_missing: "未回应：{value}";
         readonly auth_sync_push_blocked_active: "当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。";
+        readonly auth_sync_safe_starting: "正在安全同步本机多 bot runtime 和跨节点 auth...";
+        readonly auth_sync_safe_done: "安全 auth 同步完成：本机同步 {localSynced}，本机跳过 {localSkipped}；跨节点发送 {sent}，跳过 {skipped}。";
         readonly auth_sync_push_done: "auth 同步推送完成：已发送 {sent}，已跳过 {skipped}。";
         readonly auth_sync_status_title: "跨节点 auth 同步：";
         readonly auth_sync_status_node: "节点：{value}";
@@ -888,6 +893,7 @@ declare const MESSAGES: {
         readonly auth_sync_trace_missing: "用法：/auth sync trace <requestId>";
         readonly button_login_device: "🔑 设备登录";
         readonly button_auth_reload: "🔄 重载 auth";
+        readonly button_auth_safe_sync: "🧷 安全同步";
         readonly button_auth_refresh_all_confirm: "⚠️ 接受风险并刷新";
         readonly button_auth_enable: "✅";
         readonly button_auth_disable: "⏸️";

package/dist/i18n.js

@@ -141,8 +141,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]|sync <status|test|push all>|add <name>]',
-        usage_auth_sync: 'Usage: /auth sync <status|events [filter]|trace <requestId>|test|push all>',
+        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|safe|push all>|add <name>]',
+        usage_auth_sync: 'Usage: /auth sync <status|events [filter]|trace <requestId>|test|safe|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}',
@@ -210,6 +210,8 @@ const MESSAGES = {
         auth_sync_test_sent: 'Auth sync test complete: sent {sent}, replies {replied}.',
         auth_sync_test_missing: 'Missing replies: {value}',
         auth_sync_push_blocked_active: 'Cannot push auth sync while any runtime, approval, input, login, or auth mirror write is active.',
+        auth_sync_safe_starting: 'Safely syncing auth across local bot runtimes and cross-node peers...',
+        auth_sync_safe_done: 'Safe auth sync complete: local synced {localSynced}, local skipped {localSkipped}; cross-node sent {sent}, skipped {skipped}.',
         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}',
@@ -233,6 +235,7 @@ const MESSAGES = {
         auth_sync_trace_missing: 'Usage: /auth sync trace <requestId>',
         button_login_device: '🔑 Login',
         button_auth_reload: '🔄 Reload auth',
+        button_auth_safe_sync: '🧷 Safe sync',
         button_auth_refresh_all_confirm: '⚠️ Accept risk & refresh',
         button_auth_enable: '✅',
         button_auth_disable: '⏸️',
@@ -794,8 +797,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]|sync <status|test|push all>|add <名称>]',
-        usage_auth_sync: '用法：/auth sync <status|events [过滤]|trace <requestId>|test|push all>',
+        usage_auth: '用法：/auth [list [关键词]|filter <all|enabled|attention>|page <页码>|use <编号>|enable <编号>|disable <编号>|reload|refresh all [confirm]|sync <status|test|safe|push all>|add <名称>]',
+        usage_auth_sync: '用法：/auth sync <status|events [过滤]|trace <requestId>|test|safe|push all>',
         usage_auth_add: '用法：/auth add <名称>。名称只能包含字母、数字、点、短横线或下划线。',
         auth_list_title: 'Codex auth 文件：',
         auth_bot: 'Bot runtime：{value}',
@@ -863,6 +866,8 @@ const MESSAGES = {
         auth_sync_test_sent: 'auth sync 测试完成：已发送 {sent}，收到回应 {replied}。',
         auth_sync_test_missing: '未回应：{value}',
         auth_sync_push_blocked_active: '当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。',
+        auth_sync_safe_starting: '正在安全同步本机多 bot runtime 和跨节点 auth...',
+        auth_sync_safe_done: '安全 auth 同步完成：本机同步 {localSynced}，本机跳过 {localSkipped}；跨节点发送 {sent}，跳过 {skipped}。',
         auth_sync_push_done: 'auth 同步推送完成：已发送 {sent}，已跳过 {skipped}。',
         auth_sync_status_title: '跨节点 auth 同步：',
         auth_sync_status_node: '节点：{value}',
@@ -886,6 +891,7 @@ const MESSAGES = {
         auth_sync_trace_missing: '用法：/auth sync trace <requestId>',
         button_login_device: '🔑 设备登录',
         button_auth_reload: '🔄 重载 auth',
+        button_auth_safe_sync: '🧷 安全同步',
         button_auth_refresh_all_confirm: '⚠️ 接受风险并刷新',
         button_auth_enable: '✅',
         button_auth_disable: '⏸️',

package/dist/main.js

@@ -342,6 +342,16 @@ async function runServeCli() {
                 releaseAuthRefreshLease: (leaseId) => authSync?.releaseRefreshLease(leaseId)
                     ?? localAuthRefreshLease.release(leaseId),
                 getAuthSyncStatus: () => authSync?.getStatus() ?? null,
+                authSyncSafeAll: async () => {
+                    const local = await mirror.syncAllRuntimeCandidates();
+                    const remote = await authSync?.pushAll() ?? { sent: 0, skipped: 0 };
+                    return {
+                        localSynced: local.synced,
+                        localSkipped: local.skipped,
+                        sent: remote.sent,
+                        skipped: remote.skipped,
+                    };
+                },
                 authSyncPushAll: () => authSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
                 authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
                 statusUpdated: () => writeAggregateStatus(),
@@ -500,6 +510,16 @@ async function runServeCli() {
             releaseAuthRefreshLease: (leaseId) => singleAuthSync?.releaseRefreshLease(leaseId)
                 ?? singleLocalAuthRefreshLease.release(leaseId),
             getAuthSyncStatus: () => singleAuthSync?.getStatus() ?? null,
+            authSyncSafeAll: async () => {
+                const local = await singleMirror?.syncAllRuntimeCandidates() ?? { synced: 0, skipped: 0 };
+                const remote = await singleAuthSync?.pushAll() ?? { sent: 0, skipped: 0 };
+                return {
+                    localSynced: local.synced,
+                    localSkipped: local.skipped,
+                    sent: remote.sent,
+                    skipped: remote.skipped,
+                };
+            },
             authSyncPushAll: () => singleAuthSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
             authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
             statusUpdated: (status) => {

package/docs/release.md

@@ -0,0 +1,102 @@
+# FoxClaw Release Runbook
+
+This file is for maintainers. User upgrades are driven by `/update` or `foxclaw update`, but those commands install `@foxden-app/foxclaw@latest` from the npm registry. Pushing a PR branch or a normal commit does not make installed nodes receive a new version.
+
+## Release Rules
+
+- npm `latest` is the source of truth for `/update`.
+- The GitHub `Publish` workflow is triggered by `v*` tags and also supports manual dispatch; normal releases should use tags.
+- The tag name must match `v<package.json version>`. For example, `package.json` version `0.5.10` must be released with `v0.5.10`.
+- Versions already present on npm are not published again. Reinstalling the same version may report `0.5.10 -> 0.5.10` in Telegram; that means registry latest did not move.
+- `CHANGELOG.md` must contain the target version entry. `/update` reads that entry from the installed package and shows it as the upgrade notes.
+
+## Preflight
+
+Check the worktree and remote state:
+
+```bash
+git status --short --branch
+npm pkg get name version
+npm view @foxden-app/foxclaw version
+git tag --list 'v*' --sort=-v:refname | head
+```
+
+Confirm the target version and remote tag do not already exist:
+
+```bash
+npm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
+git ls-remote --tags origin refs/tags/v0.5.10
+```
+
+Run the same local checks as the publish workflow:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm pack --dry-run
+git diff --check
+```
+
+`npm pack --dry-run` runs `prepack` and lists the package contents. Confirm `CHANGELOG.md` is included.
+
+## Prepare The Version
+
+1. Update `package.json` and `package-lock.json`.
+2. Add a new top entry to `CHANGELOG.md` with both `### 中文` and `### English` sections.
+3. Commit the release metadata:
+
+```bash
+git add package.json package-lock.json CHANGELOG.md
+git commit -m "发布 0.5.10：short release summary"
+```
+
+## Push And Publish
+
+This repository uses lightweight tags:
+
+```bash
+git tag v0.5.10
+git push origin <branch>
+git push origin v0.5.10
+```
+
+Watch the publish workflow:
+
+```bash
+gh run list --repo foxden-app/foxclaw --workflow Publish --limit 5
+gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
+```
+
+After success, verify npm and GitHub Releases:
+
+```bash
+npm view @foxden-app/foxclaw version
+gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
+```
+
+## Verify `/update`
+
+On a node still running the previous version, send `/update`. Expected:
+
+```text
+FoxClaw upgraded and restarted: 0.5.9 -> 0.5.10.
+
+What changed:
+- ...
+```
+
+If the node is already on the latest version, another `/update` may report:
+
+```text
+FoxClaw upgraded and restarted: 0.5.10 -> 0.5.10.
+```
+
+That means it reinstalled the current npm latest, not that a newer version was available.
+
+## Failure Handling
+
+- If the workflow fails during version validation, check that the tag and `package.json` version match.
+- If npm says the version already exists, do not reuse that version; publish the next patch after fixing the metadata.
+- If npm publish succeeds but GitHub Release creation fails, rerun the workflow or repair the release notes manually.
+- Do not delete and republish npm versions. Prefer publishing a fixed patch release; use npm dist-tags for emergency latest rollback only when necessary.

package/docs/zh/release.md

@@ -0,0 +1,102 @@
+# FoxClaw 发布 runbook
+
+本文件给维护者使用。用户侧升级由 `/update` 或 `foxclaw update` 完成，但它们只会安装 npm registry 上的 `@foxden-app/foxclaw@latest`。推 PR、推普通分支或本地提交都不会让已安装节点收到新版。
+
+## 发布规则
+
+- npm `latest` 是 `/update` 的事实来源。
+- GitHub `Publish` workflow 由 `v*` tag 触发，也支持手动 dispatch；正常发布只使用 tag。
+- tag 名必须等于 `v<package.json version>`，例如 `package.json` 是 `0.5.10` 时只能推 `v0.5.10`。
+- npm 上已经存在的版本不会再次发布。重新安装同版本时，Telegram 可能显示 `0.5.10 -> 0.5.10`，这表示 registry latest 没有前进。
+- `CHANGELOG.md` 必须包含目标版本条目。`/update` 完成回报会从已安装包读取这个条目展示“更新内容”。
+
+## 发布前检查
+
+确认工作区和远端状态：
+
+```bash
+git status --short --branch
+npm pkg get name version
+npm view @foxden-app/foxclaw version
+git tag --list 'v*' --sort=-v:refname | head
+```
+
+确认目标版本还没有发布，也没有远端 tag：
+
+```bash
+npm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
+git ls-remote --tags origin refs/tags/v0.5.10
+```
+
+运行与发布 workflow 对齐的本地校验：
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm pack --dry-run
+git diff --check
+```
+
+`npm pack --dry-run` 会执行 `prepack` 构建，并列出 npm 包内容。确认输出里有 `CHANGELOG.md`。
+
+## 准备版本
+
+1. 更新 `package.json` 和 `package-lock.json` 的版本号。
+2. 在 `CHANGELOG.md` 顶部新增版本条目，包含 `### 中文` 和 `### English` 小节。
+3. 提交发布 commit，推荐格式：
+
+```bash
+git add package.json package-lock.json CHANGELOG.md
+git commit -m "发布 0.5.10：一句话说明"
+```
+
+## 推送并触发发布
+
+当前仓库使用 lightweight tag：
+
+```bash
+git tag v0.5.10
+git push origin <branch>
+git push origin v0.5.10
+```
+
+观察发布 workflow：
+
+```bash
+gh run list --repo foxden-app/foxclaw --workflow Publish --limit 5
+gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
+```
+
+成功后确认 npm 和 GitHub Release：
+
+```bash
+npm view @foxden-app/foxclaw version
+gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
+```
+
+## 验收 `/update`
+
+在仍安装旧版本的节点上发送 `/update`，期望看到：
+
+```text
+FoxClaw 已升级并重启：0.5.9 -> 0.5.10。
+
+更新内容：
+- ...
+```
+
+如果节点已经是最新版本，再次 `/update` 可能显示：
+
+```text
+FoxClaw 已升级并重启：0.5.10 -> 0.5.10。
+```
+
+这只表示重新安装了当前 npm latest，并不代表有新版本。
+
+## 发布失败处理
+
+- 如果 workflow 在版本校验失败，先检查 tag 和 `package.json` 是否一致。
+- 如果 npm 显示版本已存在，不要复用同一个版本号；修正后发布下一个 patch 版本。
+- 如果 npm publish 成功但 GitHub Release 创建失败，可以重新运行 workflow 或手动修复 release notes。
+- 已发布到 npm 的版本不要删除重发。需要撤回线上 latest 时，优先发布修复版；只有紧急情况下才考虑调整 npm dist-tag。

package/package.json

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