@foxden-app/foxclaw 0.5.14 → 0.5.15

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.15 - 2026-06-08
+
+### 中文
+- `/auth` 现在会把已确认不可用、并且本机/跨节点同步恢复失败的候选标记为“需要登录修复”，用 `?` 按钮显示，并从自动轮换、主动刷新和 enabled 视图中排除。
+- 点击 `?` 会进入修复菜单，可选择“登录修复”对该候选执行设备码登录，成功后清除修复状态并重新参与轮换；也可选择“删除”，从 canonical 和所有本机 bot runtime 中删除该候选并清理额度缓存。
+- 删除 auth 候选现在走 auth mirror 统一删除，避免只删一个 runtime 后又被其他 runtime 或 canonical 副本恢复。
+
+### English
+- `/auth` now marks candidates that have been proven unusable and could not be recovered through local/cross-node sync as “needs login repair”, shows a `?` action, and excludes them from auto-rotation, proactive refresh, and the enabled filter.
+- Tapping `?` opens a repair menu: Login repair runs device-code login for that candidate and clears the repair state on success; Delete removes the candidate from canonical storage and all local bot runtimes while clearing quota cache.
+- Auth candidate deletion now flows through the auth mirror so deleting a candidate from one runtime is not undone by another runtime or canonical copy.
+
 ## 0.5.14 - 2026-06-08
 
 ### 中文

package/dist/auth/mirror.d.ts

@@ -84,6 +84,7 @@ export declare class AuthCandidateMirror {
     readRuntimeCandidate(runtimeId: string, candidateName: string): Promise<AuthMirrorCandidateRecord | null>;
     listNewestCandidates(): Promise<AuthMirrorCandidateRecord[]>;
     syncRuntimeCandidate(runtimeId: string, candidateName: string): Promise<boolean>;
+    deleteCandidate(candidateName: string): Promise<boolean>;
     syncAllRuntimeCandidates(): Promise<AuthMirrorSyncAllResult>;
     recoverRuntimeCandidate(runtimeId: string, candidateName: string): Promise<AuthMirrorRecovery | null>;
     private scan;

package/dist/auth/mirror.js

@@ -126,6 +126,27 @@ export class AuthCandidateMirror {
             return false;
         return this.withActivity(() => this.propagateValidatedCandidate(runtime, candidateName));
     }
+    async deleteCandidate(candidateName) {
+        if (!isAuthCandidateName(candidateName))
+            return false;
+        return this.withActivity(async () => {
+            const directories = [
+                this.canonicalDir,
+                ...this.runtimes.map(runtime => runtime.authDir),
+            ];
+            for (const authDir of directories) {
+                await removeAuthCandidate(authDir, candidateName);
+            }
+            this.lastSyncedRefresh.delete(candidateName);
+            for (const key of [...this.lastValidationFailures.keys()]) {
+                if (key.endsWith(`:${candidateName}`)) {
+                    this.lastValidationFailures.delete(key);
+                }
+            }
+            this.logger.info('auth.mirror.deleted', { candidateName });
+            return true;
+        });
+    }
     async syncAllRuntimeCandidates() {
         return this.withActivity(async () => {
             let synced = 0;
@@ -687,6 +708,24 @@ async function pointAuthSymlink(dir, candidateName) {
     await fs.symlink(path.join(dir, candidateName), temporary);
     await fs.rename(temporary, path.join(dir, 'auth.json'));
 }
+async function removeAuthCandidate(dir, candidateName) {
+    const candidatePath = path.join(dir, candidateName);
+    const authPath = path.join(dir, 'auth.json');
+    const currentTarget = await resolveCurrentAuthCandidatePath(authPath);
+    await fs.rm(candidatePath, { force: true }).catch(() => undefined);
+    if (currentTarget === candidatePath) {
+        await fs.rm(authPath, { force: true }).catch(() => undefined);
+    }
+}
+async function resolveCurrentAuthCandidatePath(authPath) {
+    const stat = await fs.lstat(authPath).catch(() => null);
+    if (!stat)
+        return null;
+    if (stat.isSymbolicLink()) {
+        return resolveFinalPath(authPath);
+    }
+    return null;
+}
 async function removeValidationTempFiles(dir) {
     const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
     await Promise.all(entries

package/dist/controller/controller.d.ts

@@ -9,6 +9,7 @@ import type { SelfUpdateRuntime, SelfUpdateStatus } from '../update.js';
 export interface CoreCoordinator {
     canSelfUpdate?: () => boolean;
     authCandidateUpdated?: (runtimeId: string, candidateName: string) => Promise<void>;
+    authCandidateDeleted?: (runtimeId: string, candidateName: string) => Promise<void>;
     recoverAuthCandidate?: (runtimeId: string, candidateName: string, options?: {
         crossNode?: boolean;
     }) => Promise<boolean>;
@@ -295,6 +296,8 @@ export declare class BridgeSessionCore {
     private handleAuthToggleCommand;
     private findLatestAuthChoiceList;
     private handleAuthAddCommand;
+    private startAuthRepairLogin;
+    private deleteCodexAuthCandidate;
     private handleAccountCommand;
     private handleQuotaCommand;
     private handleQuotaNudgeCommand;
@@ -331,6 +334,8 @@ export declare class BridgeSessionCore {
     private requireReadyBinding;
     private handleAuthPanelActionCallback;
     private handleAuthListViewCallback;
+    private handleAuthRepairMenuCallback;
+    private handleAuthRepairActionCallback;
     private handleAuthToggleCallback;
     private handleAuthSwitchCallback;
     private maybeRunPendingAuthRotation;
@@ -342,6 +347,8 @@ export declare class BridgeSessionCore {
     private codexAuthSwitchParams;
     private switchCodexAuthAndRestart;
     private recoverCodexAuthCandidate;
+    private markCodexAuthCandidateNeedsRepair;
+    private markCodexAuthCandidateActive;
     private syncCodexAuthCandidate;
     private refreshAllCodexAuthCandidates;
     private refreshCodexAuthCandidates;

package/dist/controller/controller.js

@@ -1045,6 +1045,16 @@ export class BridgeSessionCore {
             await this.handleSettingsCallback(event, settingsMatch[1], settingsMatch[2], locale);
             return;
         }
+        const authRepairActionMatch = /^auth:([a-f0-9]+):repair_(login|delete|cancel):(\d+)$/.exec(event.data);
+        if (authRepairActionMatch) {
+            await this.handleAuthRepairActionCallback(event, authRepairActionMatch[1], authRepairActionMatch[2], Number.parseInt(authRepairActionMatch[3], 10), locale);
+            return;
+        }
+        const authRepairMatch = /^auth:([a-f0-9]+):repair:(\d+)$/.exec(event.data);
+        if (authRepairMatch) {
+            await this.handleAuthRepairMenuCallback(event, authRepairMatch[1], Number.parseInt(authRepairMatch[2], 10), locale);
+            return;
+        }
         const authToggleMatch = /^auth:([a-f0-9]+):toggle:(\d+)$/.exec(event.data);
         if (authToggleMatch) {
             await this.handleAuthToggleCallback(event, authToggleMatch[1], Number.parseInt(authToggleMatch[2], 10), locale);
@@ -1657,8 +1667,11 @@ export class BridgeSessionCore {
             if (!success) {
                 await this.restorePendingAuthAdd(pendingAuthAdd);
                 await this.sendMessage(scopeId, [
-                    t(locale, 'auth_add_failed', { value: pendingAuthAdd.name, error: params?.error ?? t(locale, 'unknown') }),
-                    t(locale, 'auth_add_reverted'),
+                    t(locale, pendingAuthAdd.mode === 'repair' ? 'auth_repair_failed' : 'auth_add_failed', {
+                        value: pendingAuthAdd.name,
+                        error: params?.error ?? t(locale, 'unknown'),
+                    }),
+                    t(locale, pendingAuthAdd.mode === 'repair' ? 'auth_repair_reverted' : 'auth_add_reverted'),
                 ].join('\n'));
                 return;
             }
@@ -1666,12 +1679,26 @@ export class BridgeSessionCore {
             if (!stat?.isFile()) {
                 await this.restorePendingAuthAdd(pendingAuthAdd);
                 await this.sendMessage(scopeId, [
-                    t(locale, 'auth_add_missing_file', { value: pendingAuthAdd.name }),
-                    t(locale, 'auth_add_reverted'),
+                    t(locale, pendingAuthAdd.mode === 'repair' ? 'auth_repair_missing_file' : 'auth_add_missing_file', { value: pendingAuthAdd.name }),
+                    t(locale, pendingAuthAdd.mode === 'repair' ? 'auth_repair_reverted' : 'auth_add_reverted'),
                 ].join('\n'));
                 return;
             }
-            const lines = [t(locale, 'auth_add_done', { value: pendingAuthAdd.name })];
+            if (pendingAuthAdd.mode === 'repair') {
+                const metadata = await readChatGptAuthMetadata(pendingAuthAdd.path);
+                if (!metadata || !chatGptAuthMetadataMatchesCandidateName(pendingAuthAdd.name, metadata)) {
+                    await this.restorePendingAuthAdd(pendingAuthAdd);
+                    await this.sendMessage(scopeId, [
+                        t(locale, 'auth_repair_identity_mismatch', { value: pendingAuthAdd.name }),
+                        t(locale, 'auth_repair_reverted'),
+                    ].join('\n'));
+                    return;
+                }
+                this.markCodexAuthCandidateActive(pendingAuthAdd.name);
+                this.store.setCodexAuthCandidateDisabled(pendingAuthAdd.name, false);
+                this.store.setCodexAuthCandidateDisabled(pendingAuthAdd.name, false, this.authRuntimeId());
+            }
+            const lines = [t(locale, pendingAuthAdd.mode === 'repair' ? 'auth_repair_done' : 'auth_add_done', { value: pendingAuthAdd.name })];
             try {
                 await this.coordinator?.authCandidateUpdated?.(this.authRuntimeId(), pendingAuthAdd.name);
             }
@@ -1692,6 +1719,7 @@ export class BridgeSessionCore {
         }
         const currentCandidate = (await this.listCodexAuthState()).candidates.find(candidate => candidate.isCurrent) ?? null;
         if (currentCandidate) {
+            this.markCodexAuthCandidateActive(currentCandidate.name);
             await this.syncCodexAuthCandidate(currentCandidate.name);
         }
         await this.sendMessage(scopeId, t(locale, 'login_completed'));
@@ -4340,6 +4368,7 @@ export class BridgeSessionCore {
         }
         const state = await this.listCodexAuthState();
         const dueCandidates = state.candidates.filter(candidate => !candidate.disabled
+            && candidate.state !== 'needs_repair'
             && candidate.credentialKind === 'chatgpt'
             && candidate.credentialLastRefreshMs !== null
             && candidate.credentialLastRefreshMs <= Date.now() - CODEX_AUTH_PROACTIVE_REFRESH_DAYS * 24 * 60 * 60_000);
@@ -4553,6 +4582,10 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, renderAuthListMessage(locale, state, this.authDisplayBotLabel(), parseWeixinBridgeScope(scopeId) !== null));
             return;
         }
+        if (candidate.state === 'needs_repair') {
+            await this.sendMessage(scopeId, t(locale, 'auth_candidate_needs_repair', { value: candidate.name }));
+            return;
+        }
         const switchLabels = await this.readCodexAuthSwitchLabels(candidate);
         await this.sendMessage(scopeId, t(locale, 'auth_switching', this.codexAuthSwitchParams(locale, switchLabels.fromLabel, switchLabels.toLabel)));
         await this.switchCodexAuthAndRestart(scopeId, locale, candidate, false);
@@ -4625,6 +4658,7 @@ export class BridgeSessionCore {
                 name: candidateName,
                 path: targetPath,
                 previousTargetPath: state.currentTargetPath,
+                mode: 'add',
                 createdAt: Date.now(),
             });
             await this.sendMessage(scopeId, [
@@ -4641,6 +4675,85 @@ export class BridgeSessionCore {
             throw error;
         }
     }
+    async startAuthRepairLogin(scopeId, locale, candidate) {
+        const state = await this.listCodexAuthState();
+        const target = state.candidates.find(entry => entry.name === candidate.name) ?? null;
+        if (!target) {
+            await this.sendMessage(scopeId, t(locale, 'auth_choice_expired'));
+            return;
+        }
+        await pointCodexAuthAtTarget(state.authDir, state.authPath, target.path);
+        this.pendingTurnErrors.clear();
+        this.attachedThreads.clear();
+        try {
+            await this.app.restart();
+            const login = await this.app.startDeviceLogin();
+            const oldLoginId = this.pendingLoginsByScope.get(scopeId);
+            if (oldLoginId) {
+                this.pendingLoginScopesById.delete(oldLoginId);
+                this.pendingAuthAddsByLoginId.delete(oldLoginId);
+            }
+            this.pendingLoginsByScope.set(scopeId, login.loginId);
+            this.pendingLoginScopesById.set(login.loginId, scopeId);
+            this.pendingAuthAddsByLoginId.set(login.loginId, {
+                loginId: login.loginId,
+                scopeId,
+                name: target.name,
+                path: target.path,
+                previousTargetPath: state.currentTargetPath,
+                mode: 'repair',
+                createdAt: Date.now(),
+            });
+            await this.sendMessage(scopeId, [
+                t(locale, 'auth_repair_started', { value: target.name }),
+                t(locale, 'login_device_prereq'),
+                t(locale, 'login_url', { value: login.verificationUrl }),
+                t(locale, 'login_code', { value: login.userCode }),
+                t(locale, 'login_id', { value: login.loginId }),
+                t(locale, 'login_cancel_hint', { value: login.loginId }),
+            ].join('\n'));
+        }
+        catch (error) {
+            await this.restoreAuthAfterAddFailure(state.authDir, state.authPath, state.currentTargetPath);
+            throw error;
+        }
+    }
+    async deleteCodexAuthCandidate(candidate) {
+        const wasCurrent = candidate.isCurrent;
+        const authDir = this.resolveAuthDir();
+        const authPath = path.join(authDir, 'auth.json');
+        let deletedByCoordinator = false;
+        try {
+            await this.coordinator?.authCandidateDeleted?.(this.authRuntimeId(), candidate.name);
+            deletedByCoordinator = Boolean(this.coordinator?.authCandidateDeleted);
+        }
+        catch (error) {
+            this.logger.warn('codex.auth_candidate_delete_sync_failed', {
+                candidate: candidate.name,
+                runtimeId: this.authRuntimeId(),
+                error: toErrorMeta(error),
+            });
+        }
+        if (!deletedByCoordinator) {
+            await fs.rm(candidate.path, { force: true }).catch(() => undefined);
+            if (wasCurrent) {
+                await fs.rm(authPath, { force: true }).catch(() => undefined);
+            }
+        }
+        this.store.deleteCodexAuthCandidate(candidate.name);
+        this.authRotationFailedTargets.delete(candidate.path);
+        const snapshots = await this.readCodexAuthQuotaSnapshots();
+        if (Object.prototype.hasOwnProperty.call(snapshots, candidate.name)) {
+            delete snapshots[candidate.name];
+            await this.writeCodexAuthQuotaSnapshots();
+        }
+        if (wasCurrent) {
+            this.pendingTurnErrors.clear();
+            this.attachedThreads.clear();
+            await this.app.restart();
+        }
+        return wasCurrent;
+    }
     async handleAccountCommand(scopeId, locale) {
         const account = await this.app.readAccount();
         const lines = [
@@ -5126,6 +5239,74 @@ export class BridgeSessionCore {
             await this.editMessage(event.scopeId, record.messageId, renderAuthListMessage(locale, state, this.authDisplayBotLabel(), parseWeixinBridgeScope(event.scopeId) !== null, record), authChoiceKeyboard(locale, record));
         }
     }
+    async handleAuthRepairMenuCallback(event, localId, index, locale) {
+        const record = this.pendingAuthChoiceLists.get(localId);
+        if (!record) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_choice_expired'));
+            return;
+        }
+        if (record.chatId !== event.scopeId || (record.messageId !== null && record.messageId !== event.messageId)) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_choice_mismatch'));
+            return;
+        }
+        const candidate = record.candidates[index];
+        if (!candidate) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'unsupported_action'));
+            return;
+        }
+        await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_repair_actions_short'));
+        if (record.messageId !== null) {
+            await this.editMessage(event.scopeId, record.messageId, t(locale, 'auth_repair_actions_message', { value: formatCodexAuthCandidateDisplayName(candidate.name) }), authRepairKeyboard(locale, record, index));
+        }
+    }
+    async handleAuthRepairActionCallback(event, localId, action, index, locale) {
+        const record = this.pendingAuthChoiceLists.get(localId);
+        if (!record) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_choice_expired'));
+            return;
+        }
+        if (record.chatId !== event.scopeId || (record.messageId !== null && record.messageId !== event.messageId)) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_choice_mismatch'));
+            return;
+        }
+        const candidate = record.candidates[index];
+        if (!candidate) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'unsupported_action'));
+            return;
+        }
+        if (action === 'cancel') {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'decision_recorded'));
+            const state = await this.listCodexAuthState();
+            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));
+            }
+            return;
+        }
+        if (this.hasLocalBlockingActivity()) {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_reload_blocked_active'));
+            return;
+        }
+        if (action === 'login') {
+            await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'login_device_started'));
+            if (record.messageId !== null) {
+                await this.editMessage(event.scopeId, record.messageId, t(locale, 'auth_repair_login_preparing', { value: candidate.name }), []);
+            }
+            await this.startAuthRepairLogin(event.scopeId, locale, candidate);
+            return;
+        }
+        await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_candidate_deleted_short'));
+        const restarted = await this.deleteCodexAuthCandidate(candidate);
+        const state = await this.listCodexAuthState();
+        record.candidates = state.candidates;
+        record.createdAt = Date.now();
+        clampCodexAuthListOffset(record);
+        if (record.messageId !== null) {
+            await this.editMessage(event.scopeId, record.messageId, `${t(locale, 'auth_candidate_deleted', { value: candidate.name })}${restarted ? `\n${t(locale, 'auth_delete_current_restarted')}` : ''}\n\n${renderAuthListMessage(locale, state, this.authDisplayBotLabel(), parseWeixinBridgeScope(event.scopeId) !== null, record)}`, authChoiceKeyboard(locale, record));
+        }
+    }
     async handleAuthToggleCallback(event, localId, index, locale) {
         const record = this.pendingAuthChoiceLists.get(localId);
         if (!record) {
@@ -5170,6 +5351,10 @@ export class BridgeSessionCore {
             await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'unsupported_action'));
             return;
         }
+        if (candidate.state === 'needs_repair') {
+            await this.handleAuthRepairMenuCallback(event, localId, index, locale);
+            return;
+        }
         await this.messaging.answerCallback(event.callbackQueryId, t(locale, 'auth_choice_recorded'));
         const switchLabels = await this.readCodexAuthSwitchLabels(candidate);
         const switchingMessage = t(locale, 'auth_switching', this.codexAuthSwitchParams(locale, switchLabels.fromLabel, switchLabels.toLabel));
@@ -5217,6 +5402,7 @@ export class BridgeSessionCore {
                     }
                     return false;
                 }
+                this.markCodexAuthCandidateNeedsRepair(current.name);
             }
             const selection = await this.selectNextCodexAuthCandidate(failedTargets);
             if (!selection) {
@@ -5291,7 +5477,9 @@ export class BridgeSessionCore {
         if (state.currentTargetPath) {
             failedTargets.add(state.currentTargetPath);
         }
-        const candidates = state.candidates.filter(candidate => !candidate.disabled && !failedTargets.has(candidate.path));
+        const candidates = state.candidates.filter(candidate => !candidate.disabled
+            && candidate.state !== 'needs_repair'
+            && !failedTargets.has(candidate.path));
         if (candidates.length === 0) {
             return null;
         }
@@ -5300,7 +5488,10 @@ export class BridgeSessionCore {
             : -1;
         for (let offset = 1; offset <= state.candidates.length; offset += 1) {
             const candidate = state.candidates[(currentIndex + offset + state.candidates.length) % state.candidates.length];
-            if (candidate && !candidate.disabled && !failedTargets.has(candidate.path)) {
+            if (candidate
+                && !candidate.disabled
+                && candidate.state !== 'needs_repair'
+                && !failedTargets.has(candidate.path)) {
                 return { candidate, fromLabel: state.currentLabel, toLabel: await authPathDisplayLabel(candidate.path) };
             }
         }
@@ -5308,7 +5499,7 @@ export class BridgeSessionCore {
         return candidate ? { candidate, fromLabel: state.currentLabel, toLabel: await authPathDisplayLabel(candidate.path) } : null;
     }
     async listCodexAuthState() {
-        const state = await listCodexAuthState(this.store.listDisabledCodexAuthCandidateNames(this.authRuntimeId()), this.resolveAuthDir());
+        const state = await listCodexAuthState(this.store.listDisabledCodexAuthCandidateNames(this.authRuntimeId()), this.store.listCodexAuthCandidateStates(this.authRuntimeId()), this.resolveAuthDir());
         const snapshots = await this.readCodexAuthQuotaSnapshots();
         const candidateQuotaIdentities = await this.readCodexAuthCandidateQuotaIdentities(state.candidates);
         state.candidates.forEach((candidate) => {
@@ -5374,6 +5565,12 @@ export class BridgeSessionCore {
             return false;
         }
     }
+    markCodexAuthCandidateNeedsRepair(candidateName) {
+        this.store.setCodexAuthCandidateState(candidateName, 'needs_repair');
+    }
+    markCodexAuthCandidateActive(candidateName) {
+        this.store.setCodexAuthCandidateState(candidateName, 'active');
+    }
     async syncCodexAuthCandidate(candidateName) {
         try {
             await this.coordinator?.authCandidateUpdated?.(this.authRuntimeId(), candidateName);
@@ -5410,7 +5607,7 @@ export class BridgeSessionCore {
         try {
             for (const candidate of candidates) {
                 const before = await readChatGptAuthMetadata(candidate.path);
-                if (!before || !chatGptAuthMetadataMatchesCandidateName(candidate.name, before)) {
+                if (candidate.disabled || candidate.state === 'needs_repair' || !before || !chatGptAuthMetadataMatchesCandidateName(candidate.name, before)) {
                     result.skipped.push(candidate.name);
                     continue;
                 }
@@ -5655,6 +5852,9 @@ export class BridgeSessionCore {
         if (!candidate) {
             return;
         }
+        if (candidate.state === 'needs_repair') {
+            return;
+        }
         try {
             const metadata = await readChatGptAuthMetadata(candidate.path);
             if (!metadata || !chatGptAuthMetadataMatchesCandidateName(candidate.name, metadata)) {
@@ -8234,7 +8434,7 @@ function parseActiveTurnKey(key) {
 function codexAuthDir(explicitAuthDir = null) {
     return explicitAuthDir || process.env.CODEX_AUTH_DIR || path.join(os.homedir(), '.codex');
 }
-async function listCodexAuthState(disabledNames = new Set(), explicitAuthDir = null) {
+async function listCodexAuthState(disabledNames = new Set(), candidateStates = new Map(), explicitAuthDir = null) {
     const authDir = codexAuthDir(explicitAuthDir);
     const authPath = path.join(authDir, 'auth.json');
     const currentTargetPath = await resolveCurrentAuthTarget(authDir, authPath);
@@ -8259,6 +8459,7 @@ async function listCodexAuthState(disabledNames = new Set(), explicitAuthDir = n
             path: candidatePath,
             isCurrent: currentTargetPath === candidatePath,
             disabled: disabledNames.has(entry.name),
+            state: candidateStates.get(entry.name) ?? 'active',
             mtimeMs: stat.mtimeMs,
             credentialKind: 'invalid',
             credentialLastRefreshMs: null,
@@ -8370,7 +8571,7 @@ async function restoreCodexAuthTarget(authDir, authPath, targetPath, regularAuth
     });
 }
 async function switchCodexAuth(targetPath, explicitAuthDir = null) {
-    const state = await listCodexAuthState(new Set(), explicitAuthDir);
+    const state = await listCodexAuthState(new Set(), new Map(), explicitAuthDir);
     const candidate = state.candidates.find(entry => entry.path === targetPath);
     if (!candidate) {
         throw new Error(`Auth candidate is no longer available: ${path.basename(targetPath)}`);
@@ -8446,7 +8647,7 @@ function filterCodexAuthCandidates(candidates, view) {
         .map((candidate, index) => ({ candidate, index }))
         .filter(({ candidate }) => !searchTerm || candidate.name.toLowerCase().includes(searchTerm))
         .filter(({ candidate }) => view.filter === 'all'
-        || (view.filter === 'enabled' && !candidate.disabled)
+        || (view.filter === 'enabled' && !candidate.disabled && candidate.state !== 'needs_repair')
         || (view.filter === 'attention' && codexAuthCandidateNeedsAttention(candidate)));
 }
 function renderAuthListMessage(locale, state, botLabel = null, includeWeixinCopyPaste = false, view = null) {
@@ -8505,12 +8706,12 @@ function authChoiceKeyboard(locale, record) {
     const page = codexAuthListPage(record.candidates, record);
     const rows = page.visible.map(({ candidate, index }) => [
         {
-            text: clipButtonText(`${candidate.isCurrent ? '✅ ' : '🔐 '}${formatAuthQuotaButtonPrefix(candidate.quota)}|${formatCodexAuthCandidateDisplayName(candidate.name)}${candidate.disabled ? ' · off' : ''}`),
-            callback_data: `auth:${record.localId}:${index}`,
+            text: clipButtonText(`${candidate.state === 'needs_repair' ? '? ' : candidate.isCurrent ? '✅ ' : '🔐 '}${formatAuthQuotaButtonPrefix(candidate.quota)}|${formatCodexAuthCandidateDisplayName(candidate.name)}${candidate.disabled ? ' · off' : ''}`),
+            callback_data: candidate.state === 'needs_repair' ? `auth:${record.localId}:repair:${index}` : `auth:${record.localId}:${index}`,
         },
         {
-            text: t(locale, candidate.disabled ? 'button_auth_disable' : 'button_auth_enable'),
-            callback_data: `auth:${record.localId}:toggle:${index}`,
+            text: candidate.state === 'needs_repair' ? '?' : t(locale, candidate.disabled ? 'button_auth_disable' : 'button_auth_enable'),
+            callback_data: candidate.state === 'needs_repair' ? `auth:${record.localId}:repair:${index}` : `auth:${record.localId}:toggle:${index}`,
         },
     ]);
     const navigationRow = [];
@@ -8555,6 +8756,9 @@ function authFilterButton(locale, record, filter) {
     };
 }
 function codexAuthCandidateHealth(candidate) {
+    if (candidate.state === 'needs_repair') {
+        return 'needs_repair';
+    }
     if (candidate.disabled) {
         return 'disabled';
     }
@@ -8589,6 +8793,7 @@ function codexAuthCandidateNeedsAttention(candidate) {
         || health === 'unknown'
         || health === 'low'
         || health === 'exhausted'
+        || health === 'needs_repair'
         || health === 'invalid';
 }
 function formatCodexAuthCandidateStatus(locale, candidate) {
@@ -8613,6 +8818,13 @@ function authRefreshAllConfirmKeyboard(locale, record) {
         [{ text: t(locale, 'button_cancel'), callback_data: `auth:${record.localId}:refresh_all_cancel` }],
     ];
 }
+function authRepairKeyboard(locale, record, index) {
+    return [
+        [{ text: t(locale, 'button_auth_repair_login'), callback_data: `auth:${record.localId}:repair_login:${index}` }],
+        [{ text: t(locale, 'button_auth_delete'), callback_data: `auth:${record.localId}:repair_delete:${index}` }],
+        [{ text: t(locale, 'button_cancel'), callback_data: `auth:${record.localId}:repair_cancel:${index}` }],
+    ];
+}
 function formatAuthRefreshAllResult(locale, result, mode = 'manual') {
     const lines = [t(locale, mode === 'proactive' ? 'auth_proactive_refresh_done' : 'auth_refresh_all_done', {
             refreshed: String(result.refreshed.length),

package/dist/i18n.d.ts

@@ -162,6 +162,7 @@ declare const MESSAGES: {
         readonly auth_candidate_status_enabled: "enabled";
         readonly auth_candidate_status_disabled: "disabled";
         readonly auth_candidate_health_disabled: "disabled";
+        readonly auth_candidate_health_needs_repair: "needs login repair";
         readonly auth_candidate_health_ready: "ready";
         readonly auth_candidate_health_low: "low quota";
         readonly auth_candidate_health_exhausted: "quota exhausted";
@@ -174,6 +175,19 @@ declare const MESSAGES: {
         readonly auth_candidate_disabled: "Disabled auth candidate for auto-rotation: {value}";
         readonly auth_candidate_enabled_short: "Auth enabled";
         readonly auth_candidate_disabled_short: "Auth disabled";
+        readonly auth_candidate_needs_repair: "{value} needs login repair. Open /auth and use the ? action to repair or delete it.";
+        readonly auth_repair_actions_short: "Repair actions";
+        readonly auth_repair_actions_message: "{value} has been verified unusable and could not be recovered from sync. Choose an action.";
+        readonly auth_repair_login_preparing: "Preparing device login repair for {value}...";
+        readonly auth_repair_started: "Device login repair started for {value}.";
+        readonly auth_repair_done: "Auth candidate repaired: {value}";
+        readonly auth_repair_failed: "Auth repair failed for {value}: {error}";
+        readonly auth_repair_missing_file: "Auth repair finished but {value} was not written.";
+        readonly auth_repair_identity_mismatch: "Auth repair finished, but the logged-in account does not match {value}.";
+        readonly auth_repair_reverted: "Restored previous auth. The candidate still needs repair.";
+        readonly auth_candidate_deleted: "Deleted auth candidate: {value}";
+        readonly auth_candidate_deleted_short: "Auth deleted";
+        readonly auth_delete_current_restarted: "The deleted candidate was current, so Codex app-server was restarted without it.";
         readonly auth_no_candidates: "No auth candidates found. Expected files like auth.json_personal in the auth dir.";
         readonly auth_choice_expired: "This auth list is no longer active";
         readonly auth_choice_mismatch: "Auth choice does not match this message";
@@ -239,6 +253,8 @@ declare const MESSAGES: {
         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_repair_login: "🔑 Login repair";
+        readonly button_auth_delete: "🗑️ Delete";
         readonly button_auth_enable: "✅";
         readonly button_auth_disable: "⏸️";
         readonly button_auth_filter_all: "All";
@@ -818,6 +834,7 @@ declare const MESSAGES: {
         readonly auth_candidate_status_enabled: "启用";
         readonly auth_candidate_status_disabled: "禁用";
         readonly auth_candidate_health_disabled: "已禁用";
+        readonly auth_candidate_health_needs_repair: "需要登录修复";
         readonly auth_candidate_health_ready: "正常";
         readonly auth_candidate_health_low: "额度偏低";
         readonly auth_candidate_health_exhausted: "额度耗尽";
@@ -830,6 +847,19 @@ declare const MESSAGES: {
         readonly auth_candidate_disabled: "已禁用 auth 候选自动轮换：{value}";
         readonly auth_candidate_enabled_short: "auth 已启用";
         readonly auth_candidate_disabled_short: "auth 已禁用";
+        readonly auth_candidate_needs_repair: "{value} 需要登录修复。打开 /auth 后使用 ? 操作修复或删除。";
+        readonly auth_repair_actions_short: "修复操作";
+        readonly auth_repair_actions_message: "{value} 已确认不可用，并且同步恢复失败。请选择处理方式。";
+        readonly auth_repair_login_preparing: "正在准备为 {value} 进行设备登录修复...";
+        readonly auth_repair_started: "已开始为 {value} 进行设备登录修复。";
+        readonly auth_repair_done: "auth 候选已修复：{value}";
+        readonly auth_repair_failed: "{value} 修复失败：{error}";
+        readonly auth_repair_missing_file: "修复流程已结束，但没有写入 {value}。";
+        readonly auth_repair_identity_mismatch: "修复流程已结束，但登录账号与 {value} 不匹配。";
+        readonly auth_repair_reverted: "已恢复之前的 auth。该候选仍需要修复。";
+        readonly auth_candidate_deleted: "已删除 auth 候选：{value}";
+        readonly auth_candidate_deleted_short: "auth 已删除";
+        readonly auth_delete_current_restarted: "被删除的候选是当前 auth，已在删除后重启 Codex app-server。";
         readonly auth_no_candidates: "没有找到 auth 候选文件。请在 auth 目录中放置类似 auth.json_personal 的文件。";
         readonly auth_choice_expired: "这个 auth 列表已经不再有效";
         readonly auth_choice_mismatch: "这个 auth 选择按钮不属于当前消息";
@@ -895,6 +925,8 @@ declare const MESSAGES: {
         readonly button_auth_reload: "🔄 重载 auth";
         readonly button_auth_safe_sync: "🧷 安全同步";
         readonly button_auth_refresh_all_confirm: "⚠️ 接受风险并刷新";
+        readonly button_auth_repair_login: "🔑 登录修复";
+        readonly button_auth_delete: "🗑️ 删除";
         readonly button_auth_enable: "✅";
         readonly button_auth_disable: "⏸️";
         readonly button_auth_filter_all: "全部";

package/dist/i18n.js

@@ -160,6 +160,7 @@ const MESSAGES = {
         auth_candidate_status_enabled: 'enabled',
         auth_candidate_status_disabled: 'disabled',
         auth_candidate_health_disabled: 'disabled',
+        auth_candidate_health_needs_repair: 'needs login repair',
         auth_candidate_health_ready: 'ready',
         auth_candidate_health_low: 'low quota',
         auth_candidate_health_exhausted: 'quota exhausted',
@@ -172,6 +173,19 @@ const MESSAGES = {
         auth_candidate_disabled: 'Disabled auth candidate for auto-rotation: {value}',
         auth_candidate_enabled_short: 'Auth enabled',
         auth_candidate_disabled_short: 'Auth disabled',
+        auth_candidate_needs_repair: '{value} needs login repair. Open /auth and use the ? action to repair or delete it.',
+        auth_repair_actions_short: 'Repair actions',
+        auth_repair_actions_message: '{value} has been verified unusable and could not be recovered from sync. Choose an action.',
+        auth_repair_login_preparing: 'Preparing device login repair for {value}...',
+        auth_repair_started: 'Device login repair started for {value}.',
+        auth_repair_done: 'Auth candidate repaired: {value}',
+        auth_repair_failed: 'Auth repair failed for {value}: {error}',
+        auth_repair_missing_file: 'Auth repair finished but {value} was not written.',
+        auth_repair_identity_mismatch: 'Auth repair finished, but the logged-in account does not match {value}.',
+        auth_repair_reverted: 'Restored previous auth. The candidate still needs repair.',
+        auth_candidate_deleted: 'Deleted auth candidate: {value}',
+        auth_candidate_deleted_short: 'Auth deleted',
+        auth_delete_current_restarted: 'The deleted candidate was current, so Codex app-server was restarted without it.',
         auth_no_candidates: 'No auth candidates found. Expected files like auth.json_personal in the auth dir.',
         auth_choice_expired: 'This auth list is no longer active',
         auth_choice_mismatch: 'Auth choice does not match this message',
@@ -237,6 +251,8 @@ const MESSAGES = {
         button_auth_reload: '🔄 Reload auth',
         button_auth_safe_sync: '🧷 Safe sync',
         button_auth_refresh_all_confirm: '⚠️ Accept risk & refresh',
+        button_auth_repair_login: '🔑 Login repair',
+        button_auth_delete: '🗑️ Delete',
         button_auth_enable: '✅',
         button_auth_disable: '⏸️',
         button_auth_filter_all: 'All',
@@ -816,6 +832,7 @@ const MESSAGES = {
         auth_candidate_status_enabled: '启用',
         auth_candidate_status_disabled: '禁用',
         auth_candidate_health_disabled: '已禁用',
+        auth_candidate_health_needs_repair: '需要登录修复',
         auth_candidate_health_ready: '正常',
         auth_candidate_health_low: '额度偏低',
         auth_candidate_health_exhausted: '额度耗尽',
@@ -828,6 +845,19 @@ const MESSAGES = {
         auth_candidate_disabled: '已禁用 auth 候选自动轮换：{value}',
         auth_candidate_enabled_short: 'auth 已启用',
         auth_candidate_disabled_short: 'auth 已禁用',
+        auth_candidate_needs_repair: '{value} 需要登录修复。打开 /auth 后使用 ? 操作修复或删除。',
+        auth_repair_actions_short: '修复操作',
+        auth_repair_actions_message: '{value} 已确认不可用，并且同步恢复失败。请选择处理方式。',
+        auth_repair_login_preparing: '正在准备为 {value} 进行设备登录修复...',
+        auth_repair_started: '已开始为 {value} 进行设备登录修复。',
+        auth_repair_done: 'auth 候选已修复：{value}',
+        auth_repair_failed: '{value} 修复失败：{error}',
+        auth_repair_missing_file: '修复流程已结束，但没有写入 {value}。',
+        auth_repair_identity_mismatch: '修复流程已结束，但登录账号与 {value} 不匹配。',
+        auth_repair_reverted: '已恢复之前的 auth。该候选仍需要修复。',
+        auth_candidate_deleted: '已删除 auth 候选：{value}',
+        auth_candidate_deleted_short: 'auth 已删除',
+        auth_delete_current_restarted: '被删除的候选是当前 auth，已在删除后重启 Codex app-server。',
         auth_no_candidates: '没有找到 auth 候选文件。请在 auth 目录中放置类似 auth.json_personal 的文件。',
         auth_choice_expired: '这个 auth 列表已经不再有效',
         auth_choice_mismatch: '这个 auth 选择按钮不属于当前消息',
@@ -893,6 +923,8 @@ const MESSAGES = {
         button_auth_reload: '🔄 重载 auth',
         button_auth_safe_sync: '🧷 安全同步',
         button_auth_refresh_all_confirm: '⚠️ 接受风险并刷新',
+        button_auth_repair_login: '🔑 登录修复',
+        button_auth_delete: '🗑️ 删除',
         button_auth_enable: '✅',
         button_auth_disable: '⏸️',
         button_auth_filter_all: '全部',

package/dist/main.js

@@ -324,6 +324,7 @@ async function runServeCli() {
                 canSelfUpdate: () => authSyncLocalIdle()
                     && (authSync ? authSync.isIdle() : localAuthRefreshLease.isIdle()),
                 authCandidateUpdated: (runtimeId, candidateName) => mirror.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined),
+                authCandidateDeleted: (_runtimeId, candidateName) => mirror.deleteCandidate(candidateName).then(() => undefined),
                 recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                     const local = await mirror.recoverRuntimeCandidate(runtimeId, candidateName);
                     if (local)
@@ -492,6 +493,7 @@ async function runServeCli() {
             canSelfUpdate: () => singleAuthSyncLocalIdle()
                 && (singleAuthSync ? singleAuthSync.isIdle() : singleLocalAuthRefreshLease.isIdle()),
             authCandidateUpdated: (runtimeId, candidateName) => singleMirror?.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined) ?? Promise.resolve(),
+            authCandidateDeleted: (_runtimeId, candidateName) => singleMirror?.deleteCandidate(candidateName).then(() => undefined) ?? Promise.resolve(),
             recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                 const local = await singleMirror?.recoverRuntimeCandidate(runtimeId, candidateName) ?? null;
                 if (local)

package/dist/store/database.d.ts

@@ -37,6 +37,7 @@ export interface CodexAuthQuotaSnapshotRecord {
     secondaryRemainingPercent: number | null;
     updatedAt: number;
 }
+export type CodexAuthCandidateState = 'active' | 'needs_repair';
 export declare class BridgeStore {
     private db;
     constructor(dbPath: string);
@@ -117,7 +118,10 @@ export declare class BridgeStore {
     getWeixinContextToken(scopeId: string): string | null;
     setWeixinContextToken(scopeId: string, contextToken: string): void;
     listDisabledCodexAuthCandidateNames(runtimeId?: string): Set<string>;
+    listCodexAuthCandidateStates(runtimeId?: string): Map<string, CodexAuthCandidateState>;
     setCodexAuthCandidateDisabled(name: string, disabled: boolean, runtimeId?: string): void;
+    setCodexAuthCandidateState(name: string, state: CodexAuthCandidateState, runtimeId?: string): void;
+    deleteCodexAuthCandidate(name: string): void;
     setCodexAuthQuotaSnapshot(runtimeId: string, candidateName: string, accountId: string, quotaIdentityId: string, snapshot: Pick<CodexAuthQuotaSnapshotRecord, 'capturedAtMs' | 'planType' | 'primaryWindowDurationMins' | 'primaryRemainingPercent' | 'secondaryWindowDurationMins' | 'secondaryRemainingPercent'>): void;
     listCodexAuthQuotaSnapshots(quotaIdentityIds: string[]): CodexAuthQuotaSnapshotRecord[];
     private ensureColumn;

package/dist/store/database.js

@@ -169,12 +169,14 @@ export class BridgeStore {
       CREATE TABLE IF NOT EXISTS codex_auth_candidates (
         name TEXT PRIMARY KEY,
         disabled INTEGER NOT NULL DEFAULT 0,
+        state TEXT NOT NULL DEFAULT 'active',
         updated_at INTEGER NOT NULL
       );
       CREATE TABLE IF NOT EXISTS codex_auth_candidate_runtime (
         runtime_id TEXT NOT NULL,
         name TEXT NOT NULL,
         disabled INTEGER NOT NULL DEFAULT 0,
+        state TEXT NOT NULL DEFAULT 'active',
         updated_at INTEGER NOT NULL,
         PRIMARY KEY (runtime_id, name)
       );
@@ -207,6 +209,8 @@ export class BridgeStore {
         this.ensureColumn('pending_approvals', 'payload_json', 'TEXT');
         this.ensureColumn('pending_user_inputs', 'status', "TEXT NOT NULL DEFAULT 'pending'");
         this.ensureColumn('pending_user_inputs', 'submitted_at', 'INTEGER');
+        this.ensureColumn('codex_auth_candidates', 'state', "TEXT NOT NULL DEFAULT 'active'");
+        this.ensureColumn('codex_auth_candidate_runtime', 'state', "TEXT NOT NULL DEFAULT 'active'");
         this.ensureColumn('codex_auth_quota_snapshots', 'plan_type', 'TEXT');
         this.ensureColumn('codex_auth_quota_snapshots', 'primary_window_duration_mins', 'REAL');
         this.ensureColumn('codex_auth_quota_snapshots', 'secondary_window_duration_mins', 'REAL');
@@ -835,21 +839,60 @@ export class BridgeStore {
         const rows = this.db.prepare('SELECT name FROM codex_auth_candidates WHERE disabled = 1').all();
         return new Set(rows.map(row => String(row.name)));
     }
+    listCodexAuthCandidateStates(runtimeId = 'default') {
+        const states = new Map();
+        const globalRows = this.db.prepare('SELECT name, state FROM codex_auth_candidates').all();
+        for (const row of globalRows) {
+            states.set(String(row.name), normalizeCodexAuthCandidateState(row.state));
+        }
+        if (runtimeId !== 'default') {
+            const runtimeRows = this.db.prepare('SELECT name, state FROM codex_auth_candidate_runtime WHERE runtime_id = ?').all(runtimeId);
+            for (const row of runtimeRows) {
+                states.set(String(row.name), normalizeCodexAuthCandidateState(row.state));
+            }
+        }
+        return states;
+    }
     setCodexAuthCandidateDisabled(name, disabled, runtimeId = 'default') {
         if (runtimeId !== 'default') {
             this.db.prepare(`
-        INSERT INTO codex_auth_candidate_runtime (runtime_id, name, disabled, updated_at)
-        VALUES (?, ?, ?, ?)
+        INSERT INTO codex_auth_candidate_runtime (runtime_id, name, disabled, state, updated_at)
+        VALUES (?, ?, ?, 'active', ?)
         ON CONFLICT(runtime_id, name) DO UPDATE SET disabled = excluded.disabled, updated_at = excluded.updated_at
       `).run(runtimeId, name, disabled ? 1 : 0, Date.now());
             return;
         }
         this.db.prepare(`
-      INSERT INTO codex_auth_candidates (name, disabled, updated_at)
-      VALUES (?, ?, ?)
+      INSERT INTO codex_auth_candidates (name, disabled, state, updated_at)
+      VALUES (?, ?, 'active', ?)
       ON CONFLICT(name) DO UPDATE SET disabled = excluded.disabled, updated_at = excluded.updated_at
     `).run(name, disabled ? 1 : 0, Date.now());
     }
+    setCodexAuthCandidateState(name, state, runtimeId = 'default') {
+        if (runtimeId !== 'default') {
+            this.db.prepare(`
+        INSERT INTO codex_auth_candidate_runtime (runtime_id, name, disabled, state, updated_at)
+        VALUES (?, ?, 0, ?, ?)
+        ON CONFLICT(runtime_id, name) DO UPDATE SET state = excluded.state, updated_at = excluded.updated_at
+      `).run(runtimeId, name, state, Date.now());
+            return;
+        }
+        this.db.prepare(`
+      INSERT INTO codex_auth_candidates (name, disabled, state, updated_at)
+      VALUES (?, 0, ?, ?)
+      ON CONFLICT(name) DO UPDATE SET state = excluded.state, updated_at = excluded.updated_at
+    `).run(name, state, Date.now());
+        this.db.prepare(`
+      UPDATE codex_auth_candidate_runtime
+      SET state = ?, updated_at = ?
+      WHERE name = ?
+    `).run(state, Date.now(), name);
+    }
+    deleteCodexAuthCandidate(name) {
+        this.db.prepare('DELETE FROM codex_auth_candidates WHERE name = ?').run(name);
+        this.db.prepare('DELETE FROM codex_auth_candidate_runtime WHERE name = ?').run(name);
+        this.db.prepare('DELETE FROM codex_auth_quota_snapshots WHERE candidate_name = ?').run(name);
+    }
     setCodexAuthQuotaSnapshot(runtimeId, candidateName, accountId, quotaIdentityId, snapshot) {
         this.db.prepare(`
       INSERT INTO codex_auth_quota_snapshots (
@@ -932,6 +975,9 @@ function nullableNumber(value) {
 function nullableString(value) {
     return typeof value === 'string' && value.trim() ? value : null;
 }
+function normalizeCodexAuthCandidateState(value) {
+    return value === 'needs_repair' ? 'needs_repair' : 'active';
+}
 function normalizeCollaborationMode(value) {
     return value === 'default' || value === 'plan' ? value : null;
 }

package/docs/user-manual.md

@@ -415,7 +415,9 @@ Quota remaining: window:percent|auth
 [🔄 Reload auth]
 ```
 
-The right-side `✅` / `⏸️` button controls whether the candidate participates in auto-rotation. Tapping it toggles enabled/disabled, and the refreshed list shows the new state. Tapping a candidate switches auth, restarts that runtime, and refreshes the same panel with its buttons intact so you can switch again immediately. `--` means no quota snapshot has been observed for that candidate yet. Health summaries distinguish ready, low quota, quota exhausted, quota unknown, not recently refreshed, API key, and invalid auth file states.
+The right-side `✅` / `⏸️` button controls whether the candidate participates in auto-rotation. Tapping it toggles enabled/disabled, and the refreshed list shows the new state. Tapping a candidate switches auth, restarts that runtime, and refreshes the same panel with its buttons intact so you can switch again immediately. `--` means no quota snapshot has been observed for that candidate yet. Health summaries distinguish ready, low quota, quota exhausted, quota unknown, not recently refreshed, API key, invalid auth file, and needs login repair states.
+
+When an auth candidate has already failed while in use and FoxClaw cannot recover a newer same-account credential from local mirror or cross-node sync, it is marked as `needs login repair`. These candidates are skipped by auto-rotation and proactive refresh, and are hidden from the `Enabled` filter. Their row shows a `?` action. Tapping it opens two choices: Login repair starts device-code login with that candidate selected; Delete removes the candidate from canonical storage and all local bot runtimes, and clears cached quota for it.
 
 `/auth refresh all` is a command-only maintenance action because ChatGPT refresh tokens are rotated. It is allowed only when every Telegram runtime, the Weixin runtime, approvals, inputs, logins, and auth mirroring are idle. The command first shows a risk confirmation: if OpenAI/Codex consumes an old 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. After confirmation, FoxClaw visits every ChatGPT candidate, asks Codex to force-refresh tokens with `account/read refreshToken=true`, verifies the result through the usage endpoint, mirrors successful candidates, restores the original current auth, and shows a summary.
 

package/docs/zh/user-manual.md

@@ -415,7 +415,9 @@ Candidates: 2
 [🔄 Reload auth]
 ```
 
-右侧 `✅` / `⏸️` 表示当前是否参与自动轮转。点一下会切换启用/禁用，列表刷新后图标会随状态变化。点击候选会切换 auth、重启对应 runtime，并在原消息上刷新面板且保留按钮，因此可以立即连续切换。`--` 表示该候选还没有额度历史快照。健康摘要会区分正常、额度偏低、额度耗尽、额度未知、长期未刷新、API key 和无效 auth 文件。
+右侧 `✅` / `⏸️` 表示当前是否参与自动轮转。点一下会切换启用/禁用，列表刷新后图标会随状态变化。点击候选会切换 auth、重启对应 runtime，并在原消息上刷新面板且保留按钮，因此可以立即连续切换。`--` 表示该候选还没有额度历史快照。健康摘要会区分正常、额度偏低、额度耗尽、额度未知、长期未刷新、API key、无效 auth 文件和需要登录修复。
+
+当某个候选在实际使用中已经失败，并且 FoxClaw 无法从本机 mirror 或跨节点同步恢复同账号较新凭据时，会标为“需要登录修复”。这类候选不会参与自动轮转和后台主动刷新，也不会出现在“已启用”筛选里。它的按钮会显示 `?`。点击后有两个选择：`登录修复` 会在选中该候选的状态下启动设备码登录；`删除` 会从 canonical 和所有本机 bot runtime 中删除这个候选，并清理它的额度缓存。
 
 `/auth refresh all` 是仅命令入口的维护操作，因为 ChatGPT refresh token 会被轮换。只有所有 Telegram runtime、微信 runtime、审批、待输入、登录流程和 auth 镜像写入都空闲时才允许执行。命令会先显示风险确认：如果 OpenAI/Codex 已经消费旧 refresh token，但因为网络、进程或磁盘故障导致新 token 没能成功保存，该候选可能需要重新设备登录，甚至重新手机号验证。确认后，它会逐个访问 ChatGPT 候选，让 Codex 通过 `account/read refreshToken=true` 强制刷新 token，再用 usage 接口验证，成功后镜像到其他 bot home，最后恢复原本的当前 auth 并显示摘要。
 

package/package.json

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