@foxden-app/foxclaw 0.5.19 → 0.5.20

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.20 - 2026-06-08
+
+### 中文
+- 修复跨节点 auth 同步远端导入验证和普通消息并发时的竞态：验证远端候选会临时重启 Codex app-server，现在这段窗口会标记为非空闲。
+- 如果普通消息刚好在远端验证重启期间进入，FoxClaw 会提示稍后重发，不再把这条消息送进正在重启的 bridge 并报 `Codex app bridge stopped`。
+- 普通对话启动过程现在也计入非空闲状态，避免 auth 同步验证插入到新 turn 建立中的窗口。
+
+### English
+- Fixed a race between cross-node auth remote-import validation and ordinary messages. Remote candidate validation temporarily restarts Codex app-server, and that window is now marked non-idle.
+- If an ordinary message arrives during the validation restart window, FoxClaw asks the user to resend it shortly instead of sending it into a restarting bridge and reporting `Codex app bridge stopped`.
+- Starting an ordinary turn now also counts as non-idle, preventing auth sync validation from entering the small window while a new turn is being established.
+
 ## 0.5.19 - 2026-06-08
 
 ### 中文

package/dist/controller/controller.d.ts

@@ -70,6 +70,8 @@ export declare class BridgeSessionCore {
     private pendingAuthRotation;
     private authRotationInProgress;
     private authRefreshAllInProgress;
+    private externalAuthValidationInProgress;
+    private turnStartInProgress;
     private authRotationFailedTargets;
     private localUsageCache;
     private localUsageCacheLoaded;

package/dist/controller/controller.js

@@ -119,6 +119,8 @@ export class BridgeSessionCore {
     pendingAuthRotation = null;
     authRotationInProgress = false;
     authRefreshAllInProgress = false;
+    externalAuthValidationInProgress = false;
+    turnStartInProgress = 0;
     authRotationFailedTargets = new Set();
     localUsageCache = null;
     localUsageCacheLoaded = false;
@@ -245,6 +247,8 @@ export class BridgeSessionCore {
         this.commandUsageSequence = 0;
         this.pendingAuthRotation = null;
         this.authRefreshAllInProgress = false;
+        this.externalAuthValidationInProgress = false;
+        this.turnStartInProgress = 0;
         this.clearObservedThreadWatchers();
         this.releaseActiveTurnsForBridgeShutdown();
         this.bot.stop();
@@ -311,6 +315,10 @@ export class BridgeSessionCore {
                 await this.handleActiveTurnInboundMessage(event, locale, event.text.trim());
                 return;
             }
+            if (this.externalAuthValidationInProgress) {
+                await this.sendMessage(scopeId, t(locale, 'auth_sync_validation_busy'));
+                return;
+            }
             await this.startBoundTurnFromEvent(event, locale, event.text.trim());
             return;
         }
@@ -365,6 +373,10 @@ export class BridgeSessionCore {
             await this.handleActiveTurnInboundMessage(event, locale, decision.text);
             return;
         }
+        if (this.externalAuthValidationInProgress) {
+            await this.sendMessage(scopeId, t(locale, 'auth_sync_validation_busy'));
+            return;
+        }
         await this.startBoundTurnFromEvent(event, locale, decision.text);
     }
     async handleCommand(event, locale, name, args) {
@@ -2920,52 +2932,61 @@ export class BridgeSessionCore {
         return (await this.listCodexAuthState()).currentLabel;
     }
     async validateExternalCodexAuthCandidate(candidateName, rawAuth, expectedAccountId) {
-        if (!this.isIdleForServiceUpdate()) {
+        if (this.externalAuthValidationInProgress) {
             return { ok: false, reason: 'runtime is not idle' };
         }
-        const metadata = parseChatGptAuthMetadata(rawAuth);
-        if (!metadata || metadata.accountId !== expectedAccountId) {
-            return { ok: false, reason: 'remote auth account id mismatch' };
-        }
-        const state = await this.listCodexAuthState();
-        const existing = state.candidates.find(candidate => candidate.name === candidateName) ?? null;
-        if (existing) {
-            const existingMetadata = await readChatGptAuthMetadata(existing.path);
-            if (existingMetadata && existingMetadata.accountId !== expectedAccountId) {
-                return { ok: false, reason: 'same candidate belongs to a different account' };
-            }
+        if (!this.isIdleForServiceUpdate()) {
+            return { ok: false, reason: 'runtime is not idle' };
         }
-        const authStat = await fs.lstat(state.authPath).catch(() => null);
-        const originalRegularAuth = authStat?.isFile()
-            ? await fs.readFile(state.authPath, 'utf8').catch(() => null)
-            : null;
-        const tempPath = path.join(state.authDir, `.auth-sync-validate-${process.pid}-${Date.now()}.json`);
+        this.externalAuthValidationInProgress = true;
         try {
-            await fs.writeFile(tempPath, rawAuth, { encoding: 'utf8', mode: 0o600 });
-            await pointCodexAuthAtTarget(state.authDir, state.authPath, tempPath);
-            this.pendingTurnErrors.clear();
-            this.attachedThreads.clear();
-            await this.app.restart();
-            const account = await this.app.readAccount(false);
-            const rateLimits = await this.app.readAccountRateLimits();
-            if (!account || !rateLimits || !selectCodexRateLimitSnapshot(rateLimits)) {
-                return { ok: false, reason: 'Codex did not validate ChatGPT usage for remote auth' };
+            const metadata = parseChatGptAuthMetadata(rawAuth);
+            if (!metadata || metadata.accountId !== expectedAccountId) {
+                return { ok: false, reason: 'remote auth account id mismatch' };
+            }
+            const state = await this.listCodexAuthState();
+            const existing = state.candidates.find(candidate => candidate.name === candidateName) ?? null;
+            if (existing) {
+                const existingMetadata = await readChatGptAuthMetadata(existing.path);
+                if (existingMetadata && existingMetadata.accountId !== expectedAccountId) {
+                    return { ok: false, reason: 'same candidate belongs to a different account' };
+                }
+            }
+            const authStat = await fs.lstat(state.authPath).catch(() => null);
+            const originalRegularAuth = authStat?.isFile()
+                ? await fs.readFile(state.authPath, 'utf8').catch(() => null)
+                : null;
+            const tempPath = path.join(state.authDir, `.auth-sync-validate-${process.pid}-${Date.now()}.json`);
+            try {
+                await fs.writeFile(tempPath, rawAuth, { encoding: 'utf8', mode: 0o600 });
+                await pointCodexAuthAtTarget(state.authDir, state.authPath, tempPath);
+                this.pendingTurnErrors.clear();
+                this.attachedThreads.clear();
+                await this.app.restart();
+                const account = await this.app.readAccount(false);
+                const rateLimits = await this.app.readAccountRateLimits();
+                if (!account || !rateLimits || !selectCodexRateLimitSnapshot(rateLimits)) {
+                    return { ok: false, reason: 'Codex did not validate ChatGPT usage for remote auth' };
+                }
+                return { ok: true };
+            }
+            catch (error) {
+                return { ok: false, reason: formatUserError(error) };
+            }
+            finally {
+                await restoreCodexAuthTarget(state.authDir, state.authPath, state.currentTargetPath, originalRegularAuth).catch((error) => {
+                    this.logger.warn('codex.auth_sync_restore_failed', { error: toErrorMeta(error) });
+                });
+                await fs.rm(tempPath, { force: true }).catch(() => undefined);
+                this.pendingTurnErrors.clear();
+                this.attachedThreads.clear();
+                await this.app.restart().catch((error) => {
+                    this.logger.warn('codex.auth_sync_restart_restore_failed', { error: toErrorMeta(error) });
+                });
             }
-            return { ok: true };
-        }
-        catch (error) {
-            return { ok: false, reason: formatUserError(error) };
         }
         finally {
-            await restoreCodexAuthTarget(state.authDir, state.authPath, state.currentTargetPath, originalRegularAuth).catch((error) => {
-                this.logger.warn('codex.auth_sync_restore_failed', { error: toErrorMeta(error) });
-            });
-            await fs.rm(tempPath, { force: true }).catch(() => undefined);
-            this.pendingTurnErrors.clear();
-            this.attachedThreads.clear();
-            await this.app.restart().catch((error) => {
-                this.logger.warn('codex.auth_sync_restart_restore_failed', { error: toErrorMeta(error) });
-            });
+            this.externalAuthValidationInProgress = false;
         }
     }
     isIdleForServiceUpdate() {
@@ -2975,7 +2996,9 @@ export class BridgeSessionCore {
             && this.pendingMcpElicitations.size === 0
             && this.pendingLoginsByScope.size === 0
             && !this.authRotationInProgress
-            && !this.authRefreshAllInProgress;
+            && !this.authRefreshAllInProgress
+            && !this.externalAuthValidationInProgress
+            && this.turnStartInProgress === 0;
     }
     hasLocalBlockingActivity() {
         return !this.isIdleForServiceUpdate();
@@ -6913,36 +6936,46 @@ export class BridgeSessionCore {
     }
     async startBoundTurnFromEvent(event, locale, text) {
         const scopeId = event.scopeId;
-        this.clearPlanImplementationPromptsForScope(scopeId);
-        await this.stopWatchingScopeThread(scopeId);
-        const existingBinding = this.store.getBinding(scopeId);
-        const binding = existingBinding
-            ? await this.ensureThreadReady(scopeId, existingBinding)
-            : await this.createBinding(scopeId, null);
-        await this.sendTyping(scopeId);
-        const previewMessageId = 0;
+        if (this.externalAuthValidationInProgress) {
+            await this.sendMessage(scopeId, t(locale, 'auth_sync_validation_busy'));
+            return;
+        }
+        this.turnStartInProgress += 1;
         try {
-            const input = await this.buildTurnInput(binding, { ...event, text }, locale);
-            const turnState = await this.startTurnWithRecovery(scopeId, binding, input);
-            if (turnState.collaborationMode === 'plan') {
-                this.store.setChatCollaborationMode(scopeId, DEFAULT_COLLABORATION_MODE);
+            this.clearPlanImplementationPromptsForScope(scopeId);
+            await this.stopWatchingScopeThread(scopeId);
+            const existingBinding = this.store.getBinding(scopeId);
+            const binding = existingBinding
+                ? await this.ensureThreadReady(scopeId, existingBinding)
+                : await this.createBinding(scopeId, null);
+            await this.sendTyping(scopeId);
+            const previewMessageId = 0;
+            try {
+                const input = await this.buildTurnInput(binding, { ...event, text }, locale);
+                const turnState = await this.startTurnWithRecovery(scopeId, binding, input);
+                if (turnState.collaborationMode === 'plan') {
+                    this.store.setChatCollaborationMode(scopeId, DEFAULT_COLLABORATION_MODE);
+                }
+                await this.registerActiveTurn(scopeId, event.chatId, event.chatType, event.topicId, turnState.threadId, turnState.turnId, previewMessageId, {
+                    input,
+                    threadId: turnState.threadId,
+                    cwd: this.store.getBinding(scopeId)?.cwd ?? binding.cwd ?? this.config.defaultCwd,
+                    chatId: event.chatId,
+                    chatType: event.chatType,
+                    topicId: event.topicId,
+                    collaborationMode: turnState.collaborationMode,
+                    failedAuthTargets: new Set(),
+                }, turnState.collaborationMode);
             }
-            await this.registerActiveTurn(scopeId, event.chatId, event.chatType, event.topicId, turnState.threadId, turnState.turnId, previewMessageId, {
-                input,
-                threadId: turnState.threadId,
-                cwd: this.store.getBinding(scopeId)?.cwd ?? binding.cwd ?? this.config.defaultCwd,
-                chatId: event.chatId,
-                chatType: event.chatType,
-                topicId: event.topicId,
-                collaborationMode: turnState.collaborationMode,
-                failedAuthTargets: new Set(),
-            }, turnState.collaborationMode);
-        }
-        catch (error) {
-            if (previewMessageId > 0) {
-                await this.cleanupTransientPreview(scopeId, previewMessageId);
+            catch (error) {
+                if (previewMessageId > 0) {
+                    await this.cleanupTransientPreview(scopeId, previewMessageId);
+                }
+                throw error;
             }
-            throw error;
+        }
+        finally {
+            this.turnStartInProgress -= 1;
         }
     }
     async requestInterrupt(active) {

package/dist/i18n.d.ts

@@ -225,6 +225,7 @@ declare const MESSAGES: {
         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_validation_busy: "Auth sync is validating refreshed credentials and temporarily restarting Codex app-server. Wait a moment, then send this message again.";
         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.";
@@ -899,6 +900,7 @@ declare const MESSAGES: {
         readonly auth_add_reverted: "已恢复之前的 auth。";
         readonly auth_add_missing_file: "登录已完成，但没有创建新的 auth 文件：{value}";
         readonly auth_sync_disabled: "跨节点 auth 同步未启用。";
+        readonly auth_sync_validation_busy: "正在验证跨节点 auth，并临时重启 Codex app-server。请稍等片刻后再发送这条消息。";
         readonly auth_sync_test_sent: "auth sync 测试完成：已发送 {sent}，收到回应 {replied}。";
         readonly auth_sync_test_missing: "未回应：{value}";
         readonly auth_sync_push_blocked_active: "当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。";

package/dist/i18n.js

@@ -223,6 +223,7 @@ const MESSAGES = {
         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_validation_busy: 'Auth sync is validating refreshed credentials and temporarily restarting Codex app-server. Wait a moment, then send this message again.',
         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.',
@@ -897,6 +898,7 @@ const MESSAGES = {
         auth_add_reverted: '已恢复之前的 auth。',
         auth_add_missing_file: '登录已完成，但没有创建新的 auth 文件：{value}',
         auth_sync_disabled: '跨节点 auth 同步未启用。',
+        auth_sync_validation_busy: '正在验证跨节点 auth，并临时重启 Codex app-server。请稍等片刻后再发送这条消息。',
         auth_sync_test_sent: 'auth sync 测试完成：已发送 {sent}，收到回应 {replied}。',
         auth_sync_test_missing: '未回应：{value}',
         auth_sync_push_blocked_active: '当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能推送 auth 同步。',

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

@@ -166,7 +166,7 @@ Confirm that pending imports were processed, or that the candidate exists or has
 
 Note: `/auth sync push all` saying “sent” only means this node successfully handed encrypted packages to Telegram. It does not prove the peer wrote files. The peer imports only when it is globally idle, usage validation succeeds, same-name candidates belong to the same account id and compatible ChatGPT user/email identity, and the remote `last_refresh` is newer than the local copy. If the local file is already equal or newer, it will not change and `Last import` may remain empty.
 
-When cross-node sync is enabled, the contact bot private chat receives node-level notifications: local auth updates and the peers being contacted, received remote bundles and whether they were queued or immediately validated, import success/skip/failure reasons, recovery peer queries and peer replies, and a manual-intervention notice when every peer lacks an importable copy. Refresh/send/import bursts are grouped into short summaries so one candidate update does not produce separate start, receive, mirror-write, and completion messages. Recovery and manual-intervention notices remain explicit. Notifications never include auth contents, tokens, or encrypted bundle payloads.
+When cross-node sync is enabled, the contact bot private chat receives node-level notifications: local auth updates and the peers being contacted, received remote bundles and whether they were queued or immediately validated, import success/skip/failure reasons, recovery peer queries and peer replies, and a manual-intervention notice when every peer lacks an importable copy. Refresh/send/import bursts are grouped into short summaries so one candidate update does not produce separate start, receive, mirror-write, and completion messages. Recovery and manual-intervention notices remain explicit. Remote import validation temporarily restarts the local Codex app-server; during that restart window FoxClaw treats the runtime as non-idle and asks ordinary messages to be resent shortly instead of running them against a restarting bridge. Notifications never include auth contents, tokens, or encrypted bundle payloads.
 
 Starting in 0.5.2, `/auth sync status` separates sync-system `Last error` from per-auth `Candidate failures`. For example, a remote candidate that returns `token_invalidated` or has an expired access token is recorded under that candidate name only; current `auth.json` health is still determined by validating the current auth usage. `local candidate is already newer or equal` is a normal skip, not an error.
 

package/docs/user-manual.md

@@ -425,7 +425,7 @@ OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token r
 
 ### 6.4 Cross-Node Auth Sync
 
-Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`. The contact bot private chat reports send, receive, queue, import, failure, recovery-query, and manual-intervention states; refresh/send/import bursts are grouped into summaries, while recovery and manual-intervention notices remain explicit. Per-candidate validation failures are shown as candidate failures instead of overwriting the sync-system last error. Recent bot-to-bot traffic is also kept in an event ring so `/auth sync events [filter]` and `/auth sync trace <requestId>` can explain a specific candidate, peer, or request.
+Cross-node auth sync is disabled by default. It is for multiple machines you control that share the same legally owned ChatGPT auth candidate pool, so a token refreshed by Codex on one node can be copied to the others. v1 uses Telegram Bot-to-Bot private messages to carry encrypted files, so it does not require public IPs or FRP. The recommended default is one contact bot per node; other bots on the same node keep using local auth mirroring. In multi-bot mode, the default contact is the first token in `TG_BOT_TOKENS`. The contact bot private chat reports send, receive, queue, import, failure, recovery-query, and manual-intervention states; refresh/send/import bursts are grouped into summaries, while recovery and manual-intervention notices remain explicit. Remote import validation temporarily restarts the local Codex app-server; FoxClaw marks that window non-idle, and ordinary messages received during it get a short retry notice instead of running against a restarting bridge. Per-candidate validation failures are shown as candidate failures instead of overwriting the sync-system last error. Recent bot-to-bot traffic is also kept in an event ring so `/auth sync events [filter]` and `/auth sync trace <requestId>` can explain a specific candidate, peer, or request.
 
 For the full design, safety boundaries, `.env` examples, and troubleshooting, read the [Cross-Node Auth Sync Setup Guide](./cross-node-auth-sync.md).
 

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

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

package/docs/zh/user-manual.md

@@ -425,7 +425,7 @@ OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放
 
 ### 6.4 跨节点 auth 同步
 
-跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示；刷新、发送、导入密集发生时会合并成汇总，恢复和人工介入提示仍会明确发出。单个候选验证失败会作为“候选失败”显示，不会覆盖同步系统级最近错误。最近 bot-to-bot 通讯会保存在事件环里，可用 `/auth sync events [过滤]` 和 `/auth sync trace <requestId>` 追查某个候选、peer 或请求。
+跨节点 auth 同步默认关闭。它适合你在多台自己控制的机器上使用同一组合法 ChatGPT 账号候选，并希望某台机器上 Codex 自动刷新出的新 token 能同步到其他机器。v1 使用 Telegram Bot-to-Bot 私聊传输加密文件，不需要公网 IP 或 FRP。推荐每台机器选择一个联系人 bot；同一节点内其他 bot 继续使用本机 auth 镜像。多 bot 模式下，默认联系人是 `TG_BOT_TOKENS` 的第一个 token。联系人 bot 的私聊会报告发送、接收、排队、导入、失败、恢复查询和人工介入提示；刷新、发送、导入密集发生时会合并成汇总，恢复和人工介入提示仍会明确发出。远端导入验证会临时重启本机 Codex app-server；FoxClaw 会把这段窗口标记为非空闲，期间收到的普通消息会收到稍后重发提示，不再进入正在重启的 bridge。单个候选验证失败会作为“候选失败”显示，不会覆盖同步系统级最近错误。最近 bot-to-bot 通讯会保存在事件环里，可用 `/auth sync events [过滤]` 和 `/auth sync trace <requestId>` 追查某个候选、peer 或请求。
 
 完整设计、安全边界、`.env` 示例和排查步骤见 [跨节点 auth 同步配置指南](./cross-node-auth-sync.md)。
 

package/package.json

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