@foxden-app/foxclaw 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.6 - 2026-06-04
+
+### 中文
+- 新增后台主动 auth 刷新：已启用的 ChatGPT 候选 `last_refresh` 超过 9 天时，FoxClaw 每小时检查并在全局空闲后只刷新这批候选。
+- 主动刷新会先申请跨节点刷新锁；没有启用跨节点同步时使用同进程本地锁，避免同节点多个 bot 并发轮换 refresh token。
+- 跨节点刷新锁持有窗口延长到 10 分钟，刷新中会让 auth sync 处于非空闲状态，重复申请会被拒绝；完成后会私聊报告刷新、跳过和失败数量。
+- 中文/英文用户手册和跨节点同步文档补充 9 天主动刷新策略，明确 `/auth refresh all confirm` 仍是人工维护命令。
+
+### English
+- Added background proactive auth refresh: every hour FoxClaw checks enabled ChatGPT candidates whose `last_refresh` is older than 9 days and refreshes only that due batch after the node is globally idle.
+- Proactive refresh first requests the cross-node refresh lease; when cross-node sync is disabled, an in-process local lease prevents same-node bot runtimes from rotating refresh tokens concurrently.
+- Extended the cross-node refresh lease window to 10 minutes, marks auth sync non-idle while a lease is active, rejects duplicate lease requests, and reports refreshed/skipped/failed counts in private chat.
+- Updated the Chinese and English user manuals plus cross-node sync docs with the 9-day proactive policy, while keeping `/auth refresh all confirm` as a manual maintenance command.
+
 ## 0.5.5 - 2026-06-04
 
 ### 中文

package/dist/auth/cross_node_sync.js

@@ -8,7 +8,7 @@ const NONCE_RETENTION_MS = 7 * 24 * 60 * 60_000;
 const PULL_TIMEOUT_MS = 12_000;
 const TEST_TIMEOUT_MS = 8_000;
 const LEASE_TIMEOUT_MS = 8_000;
-const LEASE_TTL_MS = 60_000;
+const LEASE_TTL_MS = 10 * 60_000;
 const REMOTE_ACCESS_TOKEN_MIN_TTL_MS = 60_000;
 export class CrossNodeAuthSync {
     config;
@@ -116,7 +116,9 @@ export class CrossNodeAuthSync {
             && !this.importProcessorActive
             && this.pendingPulls.size === 0
             && this.pendingLeases.size === 0
-            && this.pendingTests.size === 0;
+            && this.pendingTests.size === 0
+            && this.activeLocalLease === null
+            && this.activeRemoteLease === null;
     }
     async publishCandidate(candidateName) {
         if (!this.isReady())
@@ -263,6 +265,10 @@ export class CrossNodeAuthSync {
         return result;
     }
     async acquireRefreshLease(reason) {
+        this.expireLeases();
+        if (this.activeLocalLease || this.activeRemoteLease) {
+            return { ok: false, leaseId: null, reason: 'another refresh lease is active' };
+        }
         if (!this.isReady() || this.peers.length === 0) {
             const leaseId = crypto.randomUUID();
             this.activeLocalLease = { leaseId, expiresAt: Date.now() + LEASE_TTL_MS };

package/dist/controller/controller.d.ts

@@ -80,6 +80,8 @@ export declare class BridgeSessionCore {
     private approvalTimers;
     private submittedUserInputTimers;
     private selfUpdatePollTimer;
+    private proactiveAuthRefreshTimer;
+    private proactiveAuthRefreshInProgress;
     private attachedThreads;
     private botUsername;
     private lastError;
@@ -262,6 +264,11 @@ export declare class BridgeSessionCore {
     private pollSelfUpdateStatus;
     private formatSelfUpdateResult;
     private formatCodexUpdateResult;
+    private scheduleProactiveAuthRefresh;
+    private clearProactiveAuthRefreshTimer;
+    private runProactiveAuthRefresh;
+    private proactiveAuthRefreshLocale;
+    private notifyProactiveAuthRefresh;
     private handleAuthCommand;
     private handleAuthSyncCommand;
     private handleAuthRefreshAllCommand;
@@ -318,6 +325,7 @@ export declare class BridgeSessionCore {
     private recoverCodexAuthCandidate;
     private syncCodexAuthCandidate;
     private refreshAllCodexAuthCandidates;
+    private refreshCodexAuthCandidates;
     private buildNativeCollaborationMode;
     private buildCodexUsageStatusLines;
     private buildCodexLocalUsageStatusLines;

package/dist/controller/controller.js

@@ -30,6 +30,9 @@ const CODEX_AUTH_QUOTA_SNAPSHOT_FILENAME = 'codex-auth-quota.json';
 const CODEX_AUTH_LIST_PAGE_SIZE = 8;
 const CODEX_AUTH_LOW_QUOTA_PERCENT = 10;
 const CODEX_AUTH_STALE_CREDENTIAL_DAYS = 8;
+const CODEX_AUTH_PROACTIVE_REFRESH_DAYS = 9;
+const CODEX_AUTH_PROACTIVE_REFRESH_INTERVAL_MS = 60 * 60_000;
+const CODEX_AUTH_PROACTIVE_REFRESH_INITIAL_DELAY_MS = 5 * 60_000;
 const USER_INPUT_SUBMITTED_NOTICE_MS = 90_000;
 const SELF_UPDATE_STATUS_POLL_MS = 1000;
 const PLAN_IMPLEMENTATION_CODING_MESSAGE = 'Implement the plan.';
@@ -132,6 +135,8 @@ export class BridgeSessionCore {
     approvalTimers = new Map();
     submittedUserInputTimers = new Map();
     selfUpdatePollTimer = null;
+    proactiveAuthRefreshTimer = null;
+    proactiveAuthRefreshInProgress = false;
     attachedThreads = new Set();
     botUsername = null;
     lastError = null;
@@ -206,6 +211,7 @@ export class BridgeSessionCore {
         });
         this.updateStatus();
         this.scheduleSelfUpdateStatusPoll(0);
+        this.scheduleProactiveAuthRefresh(CODEX_AUTH_PROACTIVE_REFRESH_INITIAL_DELAY_MS);
     }
     /** Begin Telegram Bot API long-polling after handlers and Codex are ready. */
     async startTelegramPolling() {
@@ -249,6 +255,7 @@ export class BridgeSessionCore {
         }
         this.submittedUserInputTimers.clear();
         this.clearSelfUpdateStatusPoll();
+        this.clearProactiveAuthRefreshTimer();
         await this.app.stop({ terminateServer: false });
         this.updateStatus();
     }
@@ -3960,6 +3967,82 @@ export class BridgeSessionCore {
         }
         return status.codexUpdate ?? null;
     }
+    scheduleProactiveAuthRefresh(delayMs = CODEX_AUTH_PROACTIVE_REFRESH_INTERVAL_MS) {
+        if (this.proactiveAuthRefreshTimer) {
+            return;
+        }
+        this.proactiveAuthRefreshTimer = setTimeout(() => {
+            this.proactiveAuthRefreshTimer = null;
+            void this.runProactiveAuthRefresh().catch((error) => {
+                this.logger.warn('codex.auth_proactive_refresh_failed', { error: toErrorMeta(error) });
+            }).finally(() => {
+                this.scheduleProactiveAuthRefresh();
+            });
+        }, delayMs);
+        this.proactiveAuthRefreshTimer.unref();
+    }
+    clearProactiveAuthRefreshTimer() {
+        if (!this.proactiveAuthRefreshTimer) {
+            return;
+        }
+        clearTimeout(this.proactiveAuthRefreshTimer);
+        this.proactiveAuthRefreshTimer = null;
+    }
+    async runProactiveAuthRefresh() {
+        if (this.proactiveAuthRefreshInProgress || !this.canRunGlobalAuthRefresh()) {
+            return;
+        }
+        const state = await this.listCodexAuthState();
+        const dueCandidates = state.candidates.filter(candidate => !candidate.disabled
+            && candidate.credentialKind === 'chatgpt'
+            && candidate.credentialLastRefreshMs !== null
+            && candidate.credentialLastRefreshMs <= Date.now() - CODEX_AUTH_PROACTIVE_REFRESH_DAYS * 24 * 60 * 60_000);
+        if (dueCandidates.length === 0) {
+            return;
+        }
+        this.proactiveAuthRefreshInProgress = true;
+        const locale = this.proactiveAuthRefreshLocale();
+        await this.notifyProactiveAuthRefresh(locale, t(locale, 'auth_proactive_refresh_starting', {
+            value: dueCandidates.map(candidate => candidate.name).join(', '),
+        }));
+        let lease;
+        try {
+            lease = await this.coordinator?.acquireAuthRefreshLease?.(`proactive auth refresh: ${dueCandidates.map(candidate => candidate.name).join(', ')}`);
+            if (lease && !lease.ok) {
+                this.logger.warn('codex.auth_proactive_refresh_lease_failed', { reason: lease.reason });
+                await this.notifyProactiveAuthRefresh(locale, t(locale, 'auth_proactive_refresh_lease_failed', {
+                    error: lease.reason ?? t(locale, 'unknown'),
+                }));
+                return;
+            }
+            const result = await this.refreshCodexAuthCandidates(new Set(dueCandidates.map(candidate => candidate.name)));
+            await this.notifyProactiveAuthRefresh(locale, formatAuthRefreshAllResult(locale, result, 'proactive'));
+        }
+        finally {
+            await this.coordinator?.releaseAuthRefreshLease?.(lease?.leaseId ?? null);
+            this.proactiveAuthRefreshInProgress = false;
+        }
+    }
+    proactiveAuthRefreshLocale() {
+        const identity = this.bot.identity;
+        if (!identity)
+            return 'en';
+        const privateScope = this.store.getTelegramPrivateScope(identity);
+        if (!privateScope)
+            return 'en';
+        return this.localeForChat(privateScope.scopeId);
+    }
+    async notifyProactiveAuthRefresh(locale, message) {
+        const identity = this.bot.identity;
+        if (!identity)
+            return;
+        const privateScope = this.store.getTelegramPrivateScope(identity);
+        if (!privateScope)
+            return;
+        await this.bot.sendMessage(privateScope.chatId, message).catch((error) => {
+            this.logger.warn('codex.auth_proactive_refresh_notify_failed', { error: toErrorMeta(error) });
+        });
+    }
     async handleAuthCommand(scopeId, locale, args) {
         const action = args[0]?.toLowerCase() ?? 'list';
         if (action === 'sync') {
@@ -4902,12 +4985,18 @@ export class BridgeSessionCore {
         }
     }
     async refreshAllCodexAuthCandidates() {
+        return this.refreshCodexAuthCandidates();
+    }
+    async refreshCodexAuthCandidates(candidateNames = null) {
         if (this.authRefreshAllInProgress) {
             throw new UserFacingError('Auth refresh all is already running.');
         }
         const initialState = await this.listCodexAuthState();
         const result = { refreshed: [], skipped: [], failed: [] };
-        if (initialState.candidates.length === 0) {
+        const candidates = candidateNames
+            ? initialState.candidates.filter(candidate => candidateNames.has(candidate.name))
+            : initialState.candidates;
+        if (candidates.length === 0) {
             return result;
         }
         const authStat = await fs.lstat(initialState.authPath).catch(() => null);
@@ -4917,7 +5006,7 @@ export class BridgeSessionCore {
         let changedAuthTarget = false;
         this.authRefreshAllInProgress = true;
         try {
-            for (const candidate of initialState.candidates) {
+            for (const candidate of candidates) {
                 const before = await readChatGptAuthMetadata(candidate.path);
                 if (!before) {
                     result.skipped.push(candidate.name);
@@ -8104,8 +8193,8 @@ function authRefreshAllConfirmKeyboard(locale, record) {
         [{ text: t(locale, 'button_cancel'), callback_data: `auth:${record.localId}:refresh_all_cancel` }],
     ];
 }
-function formatAuthRefreshAllResult(locale, result) {
-    const lines = [t(locale, 'auth_refresh_all_done', {
+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),
             skipped: String(result.skipped.length),
             failed: String(result.failed.length),

package/dist/i18n.d.ts

@@ -186,6 +186,9 @@ declare const MESSAGES: {
         readonly auth_refresh_all_blocked_active: "Cannot refresh all auth candidates while any runtime, approval, input, login, or auth mirror write is active. Wait or use /interrupt first.";
         readonly auth_refresh_all_lease_failed: "Cross-node refresh lock was not granted: {error}";
         readonly auth_refresh_all_done: "Auth refresh all complete: {refreshed} refreshed, {skipped} skipped, {failed} failed.";
+        readonly auth_proactive_refresh_starting: "Proactive auth refresh started for candidates older than 9 days: {value}";
+        readonly auth_proactive_refresh_lease_failed: "Proactive auth refresh skipped because the cross-node refresh lock was not granted: {error}";
+        readonly auth_proactive_refresh_done: "Proactive auth refresh complete: {refreshed} refreshed, {skipped} skipped, {failed} failed.";
         readonly auth_refresh_all_refreshed: "Refreshed: {value}";
         readonly auth_refresh_all_skipped: "Skipped non-ChatGPT/invalid candidates: {value}";
         readonly auth_refresh_all_failed: "Failed: {value}";
@@ -817,6 +820,9 @@ declare const MESSAGES: {
         readonly auth_refresh_all_blocked_active: "当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能刷新全部 auth。请先等待，或使用 /interrupt。";
         readonly auth_refresh_all_lease_failed: "跨节点刷新锁未授予：{error}";
         readonly auth_refresh_all_done: "全部 auth 刷新完成：已刷新 {refreshed}，已跳过 {skipped}，失败 {failed}。";
+        readonly auth_proactive_refresh_starting: "开始主动刷新超过 9 天未更新的 auth 候选：{value}";
+        readonly auth_proactive_refresh_lease_failed: "主动 auth 刷新已跳过：跨节点刷新锁未授予：{error}";
+        readonly auth_proactive_refresh_done: "主动 auth 刷新完成：已刷新 {refreshed}，已跳过 {skipped}，失败 {failed}。";
         readonly auth_refresh_all_refreshed: "已刷新：{value}";
         readonly auth_refresh_all_skipped: "已跳过非 ChatGPT/无效候选：{value}";
         readonly auth_refresh_all_failed: "失败：{value}";

package/dist/i18n.js

@@ -184,6 +184,9 @@ const MESSAGES = {
         auth_refresh_all_blocked_active: 'Cannot refresh all auth candidates while any runtime, approval, input, login, or auth mirror write is active. Wait or use /interrupt first.',
         auth_refresh_all_lease_failed: 'Cross-node refresh lock was not granted: {error}',
         auth_refresh_all_done: 'Auth refresh all complete: {refreshed} refreshed, {skipped} skipped, {failed} failed.',
+        auth_proactive_refresh_starting: 'Proactive auth refresh started for candidates older than 9 days: {value}',
+        auth_proactive_refresh_lease_failed: 'Proactive auth refresh skipped because the cross-node refresh lock was not granted: {error}',
+        auth_proactive_refresh_done: 'Proactive auth refresh complete: {refreshed} refreshed, {skipped} skipped, {failed} failed.',
         auth_refresh_all_refreshed: 'Refreshed: {value}',
         auth_refresh_all_skipped: 'Skipped non-ChatGPT/invalid candidates: {value}',
         auth_refresh_all_failed: 'Failed: {value}',
@@ -815,6 +818,9 @@ const MESSAGES = {
         auth_refresh_all_blocked_active: '当前有任一 runtime、审批、待输入、登录或 auth 镜像写入在进行中，不能刷新全部 auth。请先等待，或使用 /interrupt。',
         auth_refresh_all_lease_failed: '跨节点刷新锁未授予：{error}',
         auth_refresh_all_done: '全部 auth 刷新完成：已刷新 {refreshed}，已跳过 {skipped}，失败 {failed}。',
+        auth_proactive_refresh_starting: '开始主动刷新超过 9 天未更新的 auth 候选：{value}',
+        auth_proactive_refresh_lease_failed: '主动 auth 刷新已跳过：跨节点刷新锁未授予：{error}',
+        auth_proactive_refresh_done: '主动 auth 刷新完成：已刷新 {refreshed}，已跳过 {skipped}，失败 {failed}。',
         auth_refresh_all_refreshed: '已刷新：{value}',
         auth_refresh_all_skipped: '已跳过非 ChatGPT/无效候选：{value}',
         auth_refresh_all_failed: '失败：{value}',

package/dist/main.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -27,6 +28,39 @@ const PROXY_ENV_KEYS = [
     'no_proxy',
 ];
 const STANDARD_NODE_PROXY_ENV_KEYS = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'];
+const LOCAL_AUTH_REFRESH_LEASE_TTL_MS = 10 * 60_000;
+function createLocalAuthRefreshLease() {
+    let active = null;
+    const expire = () => {
+        if (active && active.expiresAt <= Date.now()) {
+            active = null;
+        }
+    };
+    return {
+        isIdle: () => {
+            expire();
+            return active === null;
+        },
+        acquire: async (reason) => {
+            expire();
+            if (active) {
+                return {
+                    ok: false,
+                    leaseId: null,
+                    reason: `another local auth refresh lease is active: ${active.reason}`,
+                };
+            }
+            const leaseId = crypto.randomUUID();
+            active = { leaseId, reason, expiresAt: Date.now() + LOCAL_AUTH_REFRESH_LEASE_TTL_MS };
+            return { ok: true, leaseId };
+        },
+        release: async (leaseId) => {
+            if (leaseId && active?.leaseId === leaseId) {
+                active = null;
+            }
+        },
+    };
+}
 async function main() {
     if (isVersionCommand(command)) {
         console.log(readPackageVersion());
@@ -239,6 +273,7 @@ async function runServeCli() {
             const lastSelfUpdatePath = path.join(APP_HOME, 'runtime', 'last-self-update.json');
             let lastSelfUpdate = readSelfUpdateStatus(lastSelfUpdatePath);
             const runtimes = [];
+            const localAuthRefreshLease = createLocalAuthRefreshLease();
             const writeAggregateStatus = (running = true) => {
                 const statuses = runtimes.map((runtime) => runtime.core.getRuntimeStatus());
                 const weixinStatus = activeWeixinCore?.getRuntimeStatus() ?? null;
@@ -286,7 +321,7 @@ async function runServeCli() {
                 && mirror.isIdle();
             const coordinator = {
                 canSelfUpdate: () => authSyncLocalIdle()
-                    && (!authSync || authSync.isIdle()),
+                    && (authSync ? authSync.isIdle() : localAuthRefreshLease.isIdle()),
                 authCandidateUpdated: (runtimeId, candidateName) => mirror.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined),
                 recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                     const local = await mirror.recoverRuntimeCandidate(runtimeId, candidateName);
@@ -302,9 +337,9 @@ async function runServeCli() {
                     }) ?? false;
                 },
                 acquireAuthRefreshLease: (reason) => authSync?.acquireRefreshLease(reason)
-                    ?? Promise.resolve({ ok: true, leaseId: null }),
+                    ?? localAuthRefreshLease.acquire(reason),
                 releaseAuthRefreshLease: (leaseId) => authSync?.releaseRefreshLease(leaseId)
-                    ?? Promise.resolve(),
+                    ?? localAuthRefreshLease.release(leaseId),
                 getAuthSyncStatus: () => authSync?.getStatus() ?? null,
                 authSyncPushAll: () => authSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
                 authSyncTest: () => authSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),
@@ -438,11 +473,12 @@ async function runServeCli() {
         let singleMirror = null;
         let core = null;
         const singleAuthDir = config.codexAuthDir ?? config.codexHome ?? process.env.CODEX_AUTH_DIR ?? path.join(os.homedir(), '.codex');
+        const singleLocalAuthRefreshLease = createLocalAuthRefreshLease();
         const singleAuthSyncLocalIdle = () => Boolean(core?.isIdleForServiceUpdate())
             && (!singleMirror || singleMirror.isIdle());
         const singleCoordinator = config.authSyncEnabled ? {
             canSelfUpdate: () => singleAuthSyncLocalIdle()
-                && (!singleAuthSync || singleAuthSync.isIdle()),
+                && (singleAuthSync ? singleAuthSync.isIdle() : singleLocalAuthRefreshLease.isIdle()),
             authCandidateUpdated: (runtimeId, candidateName) => singleMirror?.syncRuntimeCandidate(runtimeId, candidateName).then(() => undefined) ?? Promise.resolve(),
             recoverAuthCandidate: async (runtimeId, candidateName, options = {}) => {
                 const local = await singleMirror?.recoverRuntimeCandidate(runtimeId, candidateName) ?? null;
@@ -459,9 +495,9 @@ async function runServeCli() {
                 }) ?? false;
             },
             acquireAuthRefreshLease: (reason) => singleAuthSync?.acquireRefreshLease(reason)
-                ?? Promise.resolve({ ok: true, leaseId: null }),
+                ?? singleLocalAuthRefreshLease.acquire(reason),
             releaseAuthRefreshLease: (leaseId) => singleAuthSync?.releaseRefreshLease(leaseId)
-                ?? Promise.resolve(),
+                ?? singleLocalAuthRefreshLease.release(leaseId),
             getAuthSyncStatus: () => singleAuthSync?.getStatus() ?? null,
             authSyncPushAll: () => singleAuthSync?.pushAll() ?? Promise.resolve({ sent: 0, skipped: 0 }),
             authSyncTest: () => singleAuthSync?.testPeers() ?? Promise.resolve({ sent: 0, replied: 0, missing: [] }),

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

@@ -10,13 +10,13 @@ Use it when:
 
 - You legally own and maintain the ChatGPT accounts and auth files.
 - Multiple machines run FoxClaw, and each machine has at least one Telegram bot.
-- You want auth files to stay fresh across nodes without routinely rotating refresh tokens.
+- You want auth files to stay fresh across nodes, and you allow FoxClaw to proactively refresh enabled ChatGPT candidates whose `last_refresh` is older than 9 days after it obtains the cross-node refresh lease.
 - The recommended default is one contact bot per node for cross-node sync. Other bots on the same node continue to use local auth mirroring.
 
 Do not use it when:
 
 - The auth source is untrusted, account ownership is unclear, or you do not control every machine administrator.
-- You plan to use `/auth refresh all` as a refresh-token keepalive.
+- You want to force refresh-token keepalive without a cross-node lease, while nodes are busy, or for disabled candidates.
 - The same bot token is being polled by multiple machines at the same time. That breaks Telegram update delivery and FoxClaw's assumptions.
 
 ## Design And Safety Model
@@ -25,7 +25,7 @@ Cross-node sync combines three active paths:
 
 - **Push**: after local login, Codex automatic refresh, or `/auth refresh all confirm` succeeds and passes usage validation, FoxClaw sends the newer candidate to peers.
 - **Pull**: before auth switch or reload, FoxClaw first searches local runtimes for a newer candidate. If none exists, it asks peers for a newer same-name, same-account candidate.
-- **Lease**: before `/auth refresh all confirm` rotates refresh tokens, FoxClaw requests a cross-node refresh lease. Any busy, denying, or non-responsive peer blocks the refresh.
+- **Lease**: before `/auth refresh all confirm` or the background 9-day proactive refresh rotates refresh tokens, FoxClaw requests a cross-node refresh lease. Any busy, denying, or non-responsive peer blocks the refresh.
 
 Safety boundaries:
 
@@ -200,4 +200,4 @@ With cross-node sync enabled, this command first requests a cross-node refresh l
 
 **Should I periodically run `/auth refresh all confirm` as keepalive?**
 
-No. Codex refreshes automatically when access tokens expire. Cross-node auth sync propagates auth files that have already refreshed successfully; Refresh all should remain a maintenance command, not a routine keepalive.
+Do not force it manually on a schedule. Codex refreshes automatically when access tokens expire, and FoxClaw now proactively refreshes enabled ChatGPT candidates whose `last_refresh` is older than 9 days after the node is globally idle and obtains the cross-node refresh lease. `/auth refresh all confirm` remains a manual maintenance command for cases where you explicitly accept refresh-token rotation risk.

package/docs/user-manual.md

@@ -419,7 +419,7 @@ The right-side `✅` / `⏸️` button controls whether the candidate participat
 
 `/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.
 
-OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token replay grace period. Codex refreshes automatically when an access token approaches expiry; when it cannot parse the access-token `exp`, current Codex uses a `last_refresh` fallback of about 8 days. The panel labels candidates without a refresh record in that interval as `not recently refreshed`, but this is only a maintenance hint. It does not prove expiry and does not trigger bulk keepalive refreshes. Do not use `/auth refresh all` as a routine keepalive command.
+OpenAI does not publish a fixed ChatGPT refresh-token lifetime or an old-token replay grace period. Codex refreshes automatically when an access token approaches expiry; when it cannot parse the access-token `exp`, current Codex uses a `last_refresh` fallback of about 8 days. The panel labels candidates without a refresh record in that interval as `not recently refreshed`. FoxClaw also checks once per hour in the background: if an enabled ChatGPT candidate has a `last_refresh` older than 9 days, FoxClaw proactively refreshes that batch only when every runtime is idle, no approvals/inputs/logins/auth mirror writes are active, and the node holds the cross-node refresh lease. The private bot chat reports the proactive refresh result, and newer candidates continue through same-node mirroring and cross-node sync.
 
 ### 6.4 Cross-Node Auth Sync
 
@@ -454,13 +454,13 @@ Safety boundaries:
 - FoxClaw only accepts sync files from bots listed in `AUTH_SYNC_PEERS`; wrong key, cluster, nonce, or payload validation never writes files.
 - Remote imports wait for global local idleness, temporarily switch to the candidate for app-server usage validation, and only then write the candidate.
 - A same-name candidate known to belong to a different account id is never overwritten.
-- Cross-node recovery only pulls an already-held valid peer copy. It does not automatically rotate refresh tokens; if no peer has a usable copy, it stops and asks you to maintain auth on one node manually.
+- Cross-node recovery only pulls an already-held valid peer copy and does not rotate refresh tokens during recovery. If no peer has a usable copy, it stops and asks you to maintain auth manually. The background 9-day proactive refresh separately requests the cross-node refresh lease and skips that cycle if the lease is not granted.
 
 Dual-active behavior:
 
 - Push: after local login, Codex automatic refresh, or `/auth refresh all` succeeds and passes local mirror validation, the newer candidate is encrypted and pushed to peers.
 - Pull: before auth switch or reload, FoxClaw first searches local runtimes for a newer same-account candidate; if none is found, it asks peers for a newer same-name same-account copy.
-- Lease: `/auth refresh all confirm` requests a cross-node refresh lease before rotating tokens. Any busy, denying, or non-responsive peer blocks the refresh.
+- Lease: `/auth refresh all confirm` and the background 9-day proactive refresh request a cross-node refresh lease before rotating tokens. Any busy, denying, or non-responsive peer blocks the refresh.
 
 Commands:
 

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

@@ -10,13 +10,13 @@
 
 - 这些 ChatGPT 账号和 auth 文件都由你合法拥有和维护。
 - 多台机器都运行 FoxClaw，并且每台机器至少有一个 Telegram bot。
-- 你希望 auth 文件在节点间自动保持较新，但不希望日常主动旋转 refresh token。
+- 你希望 auth 文件在节点间自动保持较新，并允许 FoxClaw 在已启用 ChatGPT 候选 `last_refresh` 超过 9 天时，持有跨节点刷新锁后主动刷新。
 - 默认推荐每台机器只选择一个“联系人 bot”参与跨节点同步；同一节点内其他 bot 继续使用原本的本机 auth 镜像。
 
 不适合：
 
 - 同步来源不可信、账号来源不合法，或你无法确认每台机器的管理员。
-- 希望用 `/auth refresh all` 当作 refresh token 保活工具。
+- 希望在没有跨节点锁、节点忙碌或候选被禁用时仍强制做 refresh token 保活。
 - 同一个 bot token 被多台机器同时 polling；这会破坏 Telegram update 分发和 FoxClaw 的运行假设。
 
 ## 设计与安全模型
@@ -25,7 +25,7 @@
 
 - **Push**：本节点登录、Codex 自动刷新或 `/auth refresh all confirm` 成功并通过本机 usage 验证后，把较新的候选加密发送给 peer。
 - **Pull**：本节点切换或重载 auth 前，如果本机其他 runtime 没有更新副本，会向 peer 请求同名、同账号的较新候选。
-- **Lease**：执行会旋转 refresh token 的 `/auth refresh all confirm` 前，先向 peer 申请跨节点刷新锁；任一 peer 忙碌、拒绝或无响应都会阻止刷新。
+- **Lease**：执行会旋转 refresh token 的 `/auth refresh all confirm` 或后台 9 天主动刷新前，先向 peer 申请跨节点刷新锁；任一 peer 忙碌、拒绝或无响应都会阻止刷新。
 
 安全边界：
 
@@ -200,4 +200,4 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 **要不要定期 `/auth refresh all confirm` 保活**
 
-不要。Codex 会按 access token 到期自动刷新。FoxClaw 的跨节点同步会同步“已经成功刷新的新 auth”，不应该把 refresh all 当作日常保活。
+不要手动定期强刷。Codex 会按 access token 到期自动刷新；FoxClaw 也会在已启用 ChatGPT 候选 `last_refresh` 超过 9 天时，等全局空闲并拿到跨节点刷新锁后主动刷新。`/auth refresh all confirm` 仍然是人工维护命令，用于你明确接受 refresh token 轮换风险的场景。

package/docs/zh/user-manual.md

@@ -419,7 +419,7 @@ Candidates: 2
 
 `/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 并显示摘要。
 
-OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放宽限期。Codex 会在 access token 临近到期时自动刷新；如果 access token 里无法解析 `exp`，Codex 当前使用 `last_refresh` 超过约 8 天作为兜底刷新条件。面板把超过 8 天没有刷新记录的候选标为“长期未刷新”，但这只是维护提醒，不代表 refresh token 已经过期，也不会触发批量保活刷新。不要把 `/auth refresh all` 当作日常保活命令。
+OpenAI 没有公开 ChatGPT refresh token 的固定有效期或旧 token 重放宽限期。Codex 会在 access token 临近到期时自动刷新；如果 access token 里无法解析 `exp`，Codex 当前使用 `last_refresh` 超过约 8 天作为兜底刷新条件。面板把超过 8 天没有刷新记录的候选标为“长期未刷新”。FoxClaw 还会在后台每小时检查一次：已启用的 ChatGPT 候选如果 `last_refresh` 超过 9 天，会在所有 runtime 空闲、没有审批/待输入/登录/auth 镜像写入，并且拿到跨节点刷新锁后，主动刷新这一批候选。主动刷新完成后会私聊通知，并把较新的候选继续镜像和跨节点同步。
 
 ### 6.4 跨节点 auth 同步
 
@@ -454,13 +454,13 @@ AUTH_SYNC_NODE_ID=workstation-a
 - 只接收 `AUTH_SYNC_PEERS` 中 peer bot 发来的同步文件；密钥、cluster、nonce 或 payload 校验失败时不会写盘。
 - 远端导入必须等本机全局空闲，再临时切换到待验证 auth、重启 app-server、读取 usage 验证成功后才写入候选。
 - 同名候选如果已知属于不同 account id，永远拒绝覆盖。
-- 跨节点恢复只拉取 peer 已持有的有效副本，不会自动触发 refresh token 轮换；找不到有效副本时会停止，提示你在一个节点手动维护授权。
+- 跨节点恢复只拉取 peer 已持有的有效副本，不会在恢复过程中直接轮换 refresh token；找不到有效副本时会停止，提示你人工维护授权。后台 9 天主动刷新会单独申请跨节点刷新锁，拿不到锁就跳过本轮。
 
 双主动流程：
 
 - push：本节点登录、Codex 自动刷新或 `/auth refresh all` 成功并通过本机镜像验证后，会主动把较新的候选加密推送给 peer。
 - pull：本节点切换或重载 auth 前如果发现本地候选不是最新，会先查本机其他 runtime；仍找不到时，再向 peer 拉取同名同账号的较新副本。
-- lease：执行会旋转 refresh token 的 `/auth refresh all confirm` 前，会向 peer 申请跨节点刷新锁。任一 peer 忙碌、拒绝或无响应都会阻止刷新。
+- lease：执行会旋转 refresh token 的 `/auth refresh all confirm` 或后台 9 天主动刷新前，会向 peer 申请跨节点刷新锁。任一 peer 忙碌、拒绝或无响应都会阻止刷新。
 
 命令：
 

package/package.json

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