@foxden-app/foxclaw 0.5.16 → 0.5.18

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.18 - 2026-06-08
+
+### 中文
+- `/auth` 面板按钮和 `/auth use <n>` 手动切换后会立即通过 Codex app-server 验证新 auth：ChatGPT 候选必须能返回 account 和 rate-limit usage，成功后马上写入该候选的额度快照，所以列表不再继续显示旧额度。
+- 如果切换后的 auth 无法读取、身份不匹配，或 Codex 没有返回有效 account/usage，FoxClaw 会把该候选标记为“需要登录修复”（`?`），恢复到切换前的 auth，并再次重启 Codex app-server，让当前 runtime 不停留在坏 auth 上。
+- 自动 auth 轮换也复用同一套切换后验证；验证失败的候选不会继续重试请求或参与后续轮询。
+
+### English
+- Manual auth switches from the `/auth` panel buttons and `/auth use <n>` now validate the newly selected auth through Codex app-server immediately. ChatGPT candidates must return account and rate-limit usage, and successful switches record a fresh quota snapshot so the list no longer keeps showing stale usage.
+- If the selected auth cannot be parsed, has an identity mismatch, or Codex does not return valid account/usage data, FoxClaw marks that candidate as “needs login repair” (`?`), restores the previous auth, and restarts Codex app-server again so the runtime does not remain on a bad auth.
+- Automatic auth rotation now uses the same post-switch validation; failed candidates are not used for retrying the request or for later polling.
+
+## 0.5.17 - 2026-06-08
+
+### 中文
+- `foxclaw <subcommand> --help` / `-h` 现在只打印帮助，不再继续执行 `install-systemd`、`start`、`restart` 等带副作用的子命令，避免一次查帮助意外触发服务重启。
+
+### English
+- `foxclaw <subcommand> --help` / `-h` now prints usage and stops before running side-effecting subcommands such as `install-systemd`, `start`, or `restart`, preventing an accidental service restart while checking help.
+
 ## 0.5.16 - 2026-06-08
 
 ### 中文

package/dist/controller/controller.d.ts

@@ -346,6 +346,8 @@ export declare class BridgeSessionCore {
     private readCodexAuthSwitchLabels;
     private codexAuthSwitchParams;
     private switchCodexAuthAndRestart;
+    private validateCurrentCodexAuthCandidate;
+    private formatAuthSwitchValidationLines;
     private recoverCodexAuthCandidate;
     private markCodexAuthCandidateNeedsRepair;
     private markCodexAuthCandidateActive;

package/dist/controller/controller.js

@@ -5362,14 +5362,16 @@ export class BridgeSessionCore {
         if (record.messageId !== null) {
             await this.editMessage(event.scopeId, record.messageId, switchingMessage, []);
         }
-        await this.switchCodexAuthAndRestart(event.scopeId, locale, candidate, false, false);
+        const outcome = await this.switchCodexAuthAndRestart(event.scopeId, locale, candidate, false, false);
         const state = await this.listCodexAuthState();
-        await this.refreshCurrentCodexAuthQuota(state);
         record.candidates = state.candidates;
         record.createdAt = Date.now();
         clampCodexAuthListOffset(record);
         if (record.messageId !== null) {
-            await this.editMessage(event.scopeId, record.messageId, renderAuthListMessage(locale, state, this.authDisplayBotLabel(), parseWeixinBridgeScope(event.scopeId) !== null, record), authChoiceKeyboard(locale, record));
+            await this.editMessage(event.scopeId, record.messageId, [
+                ...this.formatAuthSwitchValidationLines(locale, outcome),
+                renderAuthListMessage(locale, state, this.authDisplayBotLabel(), parseWeixinBridgeScope(event.scopeId) !== null, record),
+            ].filter(Boolean).join('\n\n'), authChoiceKeyboard(locale, record));
         }
     }
     async maybeRunPendingAuthRotation() {
@@ -5417,7 +5419,10 @@ export class BridgeSessionCore {
                 ...this.codexAuthSwitchParams(locale, fromLabel, toLabel),
                 error: formatShortStatusError(rotation.reason),
             }));
-            await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true);
+            const outcome = await this.switchCodexAuthAndRestart(rotation.scopeId, locale, candidate, true);
+            if (!outcome.ok) {
+                return false;
+            }
             if (rotation.retry) {
                 await this.retryTurnAfterAuthRotation(rotation.scopeId, locale, rotation.retry);
                 return true;
@@ -5533,15 +5538,61 @@ export class BridgeSessionCore {
         };
     }
     async switchCodexAuthAndRestart(scopeId, locale, candidate, automatic, sendResult = true) {
+        const authDir = this.resolveAuthDir();
+        const initialState = await listCodexAuthState(new Set(), new Map(), authDir);
+        const authStat = await fs.lstat(initialState.authPath).catch(() => null);
+        const originalRegularAuth = authStat?.isFile()
+            ? await fs.readFile(initialState.authPath, 'utf8').catch(() => null)
+            : null;
         const recovered = await this.recoverCodexAuthCandidate(candidate.name, { crossNode: automatic });
-        const result = await switchCodexAuth(candidate.path, this.resolveAuthDir());
+        const result = await switchCodexAuth(candidate.path, authDir);
         this.authRotationFailedTargets.delete(candidate.path);
         this.pendingTurnErrors.clear();
         this.attachedThreads.clear();
         await this.app.restart();
+        const validation = await this.validateCurrentCodexAuthCandidate(candidate);
+        if (!validation.ok) {
+            this.markCodexAuthCandidateNeedsRepair(candidate.name);
+            let restoredPrevious = false;
+            try {
+                await restoreCodexAuthTarget(initialState.authDir, initialState.authPath, initialState.currentTargetPath, originalRegularAuth);
+                this.pendingTurnErrors.clear();
+                this.attachedThreads.clear();
+                await this.app.restart();
+                restoredPrevious = true;
+            }
+            catch (error) {
+                this.logger.warn('codex.auth_switch_restore_failed', {
+                    candidate: candidate.name,
+                    error: toErrorMeta(error),
+                });
+            }
+            const outcome = {
+                ...result,
+                ok: false,
+                candidateName: candidate.name,
+                recovered,
+                error: validation.error,
+                restoredPrevious,
+            };
+            if (sendResult) {
+                const lines = this.formatAuthSwitchValidationLines(locale, outcome);
+                await this.sendMessage(scopeId, lines.join('\n'));
+            }
+            return outcome;
+        }
+        this.markCodexAuthCandidateActive(candidate.name);
         await this.syncCodexAuthCandidate(candidate.name);
+        const outcome = {
+            ...result,
+            ok: true,
+            candidateName: candidate.name,
+            recovered,
+            error: null,
+            restoredPrevious: false,
+        };
         if (!sendResult) {
-            return;
+            return outcome;
         }
         const lines = [t(locale, automatic ? 'auth_auto_done' : 'auth_switch_done', this.codexAuthSwitchParams(locale, result.fromLabel, result.toLabel))];
         if (recovered) {
@@ -5549,6 +5600,56 @@ export class BridgeSessionCore {
         }
         lines.push(...await this.buildCodexUsageStatusLines(locale));
         await this.sendMessage(scopeId, lines.join('\n'));
+        return outcome;
+    }
+    async validateCurrentCodexAuthCandidate(candidate) {
+        try {
+            if (await isCodexApiKeyAuthCandidate(candidate.path)) {
+                const account = await this.app.readAccount(false);
+                if (!account) {
+                    return { ok: false, error: 'Codex did not return account info after switch' };
+                }
+                return { ok: true };
+            }
+            const metadata = await readChatGptAuthMetadata(candidate.path);
+            if (!metadata) {
+                return { ok: false, error: 'candidate is not a readable ChatGPT auth file' };
+            }
+            if (!chatGptAuthMetadataMatchesCandidateName(candidate.name, metadata)) {
+                return { ok: false, error: 'candidate auth identity does not match candidate name' };
+            }
+            const [account, rateLimits] = await Promise.all([
+                this.app.readAccount(false),
+                this.app.readAccountRateLimits(),
+            ]);
+            if (!account) {
+                return { ok: false, error: 'Codex did not return account info after switch' };
+            }
+            if (account.type !== 'chatgpt') {
+                return { ok: false, error: `Codex account type is ${account.type || 'unknown'}, expected ChatGPT` };
+            }
+            const snapshot = selectCodexRateLimitSnapshot(rateLimits);
+            if (!snapshot) {
+                return { ok: false, error: 'Codex did not return ChatGPT rate limits after switch' };
+            }
+            await this.recordCodexAuthQuotaSnapshot(candidate.name, metadata, snapshot);
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, error: formatUserError(error) };
+        }
+    }
+    formatAuthSwitchValidationLines(locale, outcome) {
+        if (outcome.ok) {
+            return [];
+        }
+        return [
+            t(locale, 'auth_switch_validation_failed', {
+                value: outcome.candidateName,
+                error: outcome.error ?? t(locale, 'unknown'),
+            }),
+            outcome.restoredPrevious ? t(locale, 'auth_switch_validation_reverted') : '',
+        ].filter(Boolean);
     }
     async recoverCodexAuthCandidate(candidateName, options = { crossNode: true }) {
         if (!this.coordinator?.recoverAuthCandidate) {

package/dist/i18n.d.ts

@@ -194,6 +194,8 @@ declare const MESSAGES: {
         readonly auth_choice_recorded: "Auth selected";
         readonly auth_switching: "Switching Codex auth: {from} -> {to}...";
         readonly auth_switch_done: "Codex auth switched: {from} -> {to}.";
+        readonly auth_switch_validation_failed: "Selected auth failed validation: {error}. Marked {value} for login repair.";
+        readonly auth_switch_validation_reverted: "Restored the previous auth after the failed switch.";
         readonly auth_recovered_newer_candidate: "Recovered a newer same-account credential for {value} from another Codex home before reload.";
         readonly auth_refresh_all_confirm_short: "Review refresh all risk first.";
         readonly auth_refresh_all_confirm_message: "Refresh all will rotate ChatGPT refresh tokens for every candidate. If OpenAI/Codex consumes a refresh token but the new token cannot be saved because of network, process, or disk failure, that candidate may require device login or phone verification again.\n\nOnly continue when every bot is idle and you accept this risk.";
@@ -866,6 +868,8 @@ declare const MESSAGES: {
         readonly auth_choice_recorded: "已选择 auth";
         readonly auth_switching: "正在切换 Codex auth：{from} -> {to}...";
         readonly auth_switch_done: "Codex auth 已切换：{from} -> {to}。";
+        readonly auth_switch_validation_failed: "选中的 auth 验证失败：{error}。已将 {value} 标记为需要登录修复。";
+        readonly auth_switch_validation_reverted: "已在切换失败后恢复到之前的 auth。";
         readonly auth_recovered_newer_candidate: "重载前已从其他 Codex home 恢复 {value} 的同账号较新凭据。";
         readonly auth_refresh_all_confirm_short: "请先确认刷新全部风险。";
         readonly auth_refresh_all_confirm_message: "刷新全部会轮换每个 ChatGPT 候选的 refresh token。如果 OpenAI/Codex 已经消费旧 refresh token，但因为网络、进程或磁盘故障导致新 token 没能成功保存，该候选可能需要重新设备登录，甚至重新手机号验证。\n\n只有在所有 bot 都空闲，并且你能接受这个风险时，才继续。";

package/dist/i18n.js

@@ -192,6 +192,8 @@ const MESSAGES = {
         auth_choice_recorded: 'Auth selected',
         auth_switching: 'Switching Codex auth: {from} -> {to}...',
         auth_switch_done: 'Codex auth switched: {from} -> {to}.',
+        auth_switch_validation_failed: 'Selected auth failed validation: {error}. Marked {value} for login repair.',
+        auth_switch_validation_reverted: 'Restored the previous auth after the failed switch.',
         auth_recovered_newer_candidate: 'Recovered a newer same-account credential for {value} from another Codex home before reload.',
         auth_refresh_all_confirm_short: 'Review refresh all risk first.',
         auth_refresh_all_confirm_message: 'Refresh all will rotate ChatGPT refresh tokens for every candidate. If OpenAI/Codex consumes a refresh token but the new token cannot be saved because of network, process, or disk failure, that candidate may require device login or phone verification again.\n\nOnly continue when every bot is idle and you accept this risk.',
@@ -864,6 +866,8 @@ const MESSAGES = {
         auth_choice_recorded: '已选择 auth',
         auth_switching: '正在切换 Codex auth：{from} -> {to}...',
         auth_switch_done: 'Codex auth 已切换：{from} -> {to}。',
+        auth_switch_validation_failed: '选中的 auth 验证失败：{error}。已将 {value} 标记为需要登录修复。',
+        auth_switch_validation_reverted: '已在切换失败后恢复到之前的 auth。',
         auth_recovered_newer_candidate: '重载前已从其他 Codex home 恢复 {value} 的同账号较新凭据。',
         auth_refresh_all_confirm_short: '请先确认刷新全部风险。',
         auth_refresh_all_confirm_message: '刷新全部会轮换每个 ChatGPT 候选的 refresh token。如果 OpenAI/Codex 已经消费旧 refresh token，但因为网络、进程或磁盘故障导致新 token 没能成功保存，该候选可能需要重新设备登录，甚至重新手机号验证。\n\n只有在所有 bot 都空闲，并且你能接受这个风险时，才继续。',

package/dist/main.js

@@ -66,7 +66,7 @@ async function main() {
         console.log(readPackageVersion());
         return;
     }
-    if (isHelpCommand(command)) {
+    if (isHelpCommand(command) || hasHelpFlag()) {
         printUsage();
         return;
     }
@@ -149,6 +149,9 @@ function isVersionCommand(value) {
 function isHelpCommand(value) {
     return value === 'help' || value === '--help' || value === '-h';
 }
+function hasHelpFlag() {
+    return process.argv.slice(3).some(isHelpCommand);
+}
 function readPackageVersion() {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));

package/package.json

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