@foxden-app/foxclaw 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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
+
+### 中文
+- 在 `/login_device`、`/auth add <name>` 和 `/auth` 面板设备登录返回内容中加入 ChatGPT 设备代码授权前置条件：在 ChatGPT 左下角用户名菜单进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。
+- README、安装指南、用户手册和故障排查补充同一指引，并强调 workspace 账号可能需要管理员允许设备码登录，以及设备代码不要分享给他人或粘贴到不可信页面。
+
+### English
+- Added a device-code authorization prerequisite to `/login_device`, `/auth add <name>`, and the `/auth` panel Login response: in ChatGPT, open the lower-left username menu, then Settings > Security, and enable device code authorization for Codex.
+- Added the same guidance to the README, install guide, user manual, and troubleshooting docs, including workspace-admin requirements and the warning not to share device codes or paste them into untrusted pages.
+
 ## 0.5.4 - 2026-06-04
 
 ### 中文

package/README.md

@@ -50,6 +50,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 
 - macOS 或 Linux，`codex` CLI 可用
 - Codex 已完成登录认证
+- 如果要通过 `/auth add` 或 `/login_device` 从 Telegram 发起设备码登录，需要先在 ChatGPT 左下角用户名菜单进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”
 - Node.js 24+
 - 一个 `@BotFather` 创建的 Telegram bot token
 - 你的 Telegram 数字用户 ID
@@ -129,6 +130,8 @@ FoxClaw 的一大特色是自动多账号切换。当一个账号触发用量限
 3. 用 `/auth` 查看所有候选账号状态。
 4. 用 `/auth enable <n>` / `/auth disable <n>` 控制哪些账号参与自动轮换。
 
+通过 `/auth add <name>` 或 `/login_device` 进行设备码登录前，需要在 ChatGPT 网页左下角点用户名，进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。设备代码等同于一次登录授权，切勿转发给他人或粘贴到不可信页面。
+
 候选较多时，`/auth` 每页显示 8 个账号，并提供翻页、`全部 / 已启用 / 需关注` 筛选。也可以用 `/auth list <关键词>` 搜索文件名，或用 `/auth page <页码>` 直接跳页。文本列表的额度窗口按 Codex 实际返回值展示，例如 `5h:20|7d:25` 或单月窗口 `30d:97`；按钮只显示紧凑的两个剩余数字，例如 `20|25`，未知值显示为 `—`。面板会省略候选名中重复的 `auth.json_` 前缀，磁盘文件名保持不变。
 
 当 Codex 报告用量限制错误时，FoxClaw 会自动：

package/README_EN.md

@@ -50,6 +50,7 @@ The minimum install needs one or more Telegram bot tokens, your numeric Telegram
 
 - macOS or Linux with a working `codex` CLI
 - Codex authenticated on the host machine
+- If you want to start device-code login from Telegram with `/auth add` or `/login_device`, first open the username menu in the lower-left corner of ChatGPT, then Settings > Security, and enable device code authorization for Codex
 - Node.js 24+
 - A Telegram bot token from `@BotFather`
 - Your Telegram numeric user id
@@ -129,6 +130,8 @@ Setup:
 3. Use `/auth` to view all candidate account statuses.
 4. Use `/auth enable <n>` / `/auth disable <n>` to control which accounts participate in auto-rotation.
 
+Before using `/auth add <name>` or `/login_device` for device-code login, open ChatGPT, click the username menu in the lower-left corner, go to Settings > Security, and enable device code authorization for Codex. Treat the device code as a login grant: never forward it or paste it into an untrusted page.
+
 For larger inventories, `/auth` shows 8 candidates per page with paging and `All / Enabled / Attention` filters. Use `/auth list <keyword>` to search filenames or `/auth page <n>` to jump directly. Candidate rows use the quota windows reported by Codex, for example `5h:20|7d:25` or a single monthly window such as `30d:97`; buttons use compact remaining numbers such as `20|25`, with `—` for unknown values. The panel omits the repeated `auth.json_` prefix from candidate labels without renaming files on disk.
 
 When Codex reports a usage-limit error, FoxClaw automatically:

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') {
@@ -4175,6 +4258,7 @@ export class BridgeSessionCore {
             });
             await this.sendMessage(scopeId, [
                 t(locale, 'auth_add_started', { value: candidateName }),
+                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 }),
@@ -4227,6 +4311,7 @@ export class BridgeSessionCore {
         this.pendingLoginScopesById.set(login.loginId, scopeId);
         await this.sendMessage(scopeId, [
             t(locale, 'login_device_started'),
+            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 }),
@@ -4900,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);
@@ -4915,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);
@@ -8102,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}";
@@ -474,6 +477,7 @@ declare const MESSAGES: {
         readonly usage_quota_nudge: "Usage: /quota_nudge <credits|usage_limit> confirm";
         readonly quota_nudge_sent: "Nudge email requested.";
         readonly login_device_started: "Device login started.";
+        readonly login_device_prereq: "Prerequisite: in ChatGPT, open your username menu at the lower left, then Settings > Security, and enable device code authorization for Codex. For workspace accounts, an admin may need to allow device code login. Never share the device code.";
         readonly login_url: "URL: {value}";
         readonly login_code: "Code: {value}";
         readonly login_id: "Login id: {value}";
@@ -816,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}";
@@ -1104,6 +1111,7 @@ declare const MESSAGES: {
         readonly usage_quota_nudge: "用法：/quota_nudge <credits|usage_limit> confirm";
         readonly quota_nudge_sent: "已请求发送额度提醒邮件。";
         readonly login_device_started: "已开始设备码登录。";
+        readonly login_device_prereq: "前置条件：在 ChatGPT 左下角点用户名，进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。Workspace 账号可能需要管理员允许设备码登录。切勿分享设备代码。";
         readonly login_url: "地址：{value}";
         readonly login_code: "验证码：{value}";
         readonly login_id: "登录 ID：{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}',
@@ -472,6 +475,7 @@ const MESSAGES = {
         usage_quota_nudge: 'Usage: /quota_nudge <credits|usage_limit> confirm',
         quota_nudge_sent: 'Nudge email requested.',
         login_device_started: 'Device login started.',
+        login_device_prereq: 'Prerequisite: in ChatGPT, open your username menu at the lower left, then Settings > Security, and enable device code authorization for Codex. For workspace accounts, an admin may need to allow device code login. Never share the device code.',
         login_url: 'URL: {value}',
         login_code: 'Code: {value}',
         login_id: 'Login id: {value}',
@@ -814,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}',
@@ -1102,6 +1109,7 @@ const MESSAGES = {
         usage_quota_nudge: '用法：/quota_nudge <credits|usage_limit> confirm',
         quota_nudge_sent: '已请求发送额度提醒邮件。',
         login_device_started: '已开始设备码登录。',
+        login_device_prereq: '前置条件：在 ChatGPT 左下角点用户名，进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。Workspace 账号可能需要管理员允许设备码登录。切勿分享设备代码。',
         login_url: '地址：{value}',
         login_code: '验证码：{value}',
         login_id: '登录 ID：{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/install-for-beginners.md

@@ -71,6 +71,8 @@ Log in:
 codex login
 ```
 
+If you are logging in from a headless host, remote SSH session, WSL setup, or any environment where browser callback login is unreliable, you may use Codex device-code login later through FoxClaw's `/login_device`, `/auth add <name>`, or the Login button in the `/auth` panel. First open `https://chatgpt.com/`, click your username in the lower-left corner, go to Settings > Security, and enable device code authorization for Codex. Workspace accounts may require an admin to allow device-code login. Never share the device code or paste it into an untrusted page.
+
 Check the CLI exists:
 
 ```bash

package/docs/troubleshooting.md

@@ -156,6 +156,8 @@ If Codex is not logged in:
 codex login
 ```
 
+If FoxClaw's `/login_device`, `/auth add <name>`, or `/auth` panel Login button gives you a device code but the login page says it is not allowed, falls back to the regular browser flow, or cannot complete on a headless host, check ChatGPT security settings first: open `https://chatgpt.com/`, click your username in the lower-left corner, go to Settings > Security, and enable device code authorization for Codex. Workspace accounts may require an admin to allow device-code login. Treat the device code as a login grant and never share it.
+
 `codex --version` only verifies the command exists. To verify auth, run:
 
 ```bash

package/docs/user-manual.md

@@ -376,6 +376,10 @@ The safer path is adding candidates from the phone with `/auth add <name>`.
 - `/logout confirm`: logs out the current Codex account.
 - `/auth add <name>`: adds a candidate account. For example, `/auth add work` creates `auth.json_work` and starts device login.
 
+Device-code login is the Codex login path for headless hosts. Your ChatGPT account may not allow it by default. Before using `/login_device`, `/auth add <name>`, or the Login button in the `/auth` panel, open `https://chatgpt.com/`, click your username in the lower-left corner, go to Settings > Security, and enable device code authorization for Codex. Workspace or enterprise accounts may require a workspace admin to allow device-code login.
+
+Use this carefully: a device code can be stolen by phishing and acts as a login grant. Enter the code only on the ChatGPT/Codex login page you trust. Never send the device code to another person or paste it into an untrusted page.
+
 `/auth add <name>` flow:
 
 1. FoxClaw prepares `auth.json_<name>`.
@@ -415,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
 
@@ -450,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/install-for-beginners.md

@@ -69,6 +69,8 @@ npm install -g @openai/codex
 codex login
 ```
 
+如果你是在无头主机、远程 SSH、WSL 或没有可用浏览器回调的环境里登录，后续可能会使用 Codex 的设备码登录，包括 FoxClaw 的 `/login_device`、`/auth add <name>` 和 `/auth` 面板里的“设备登录”。先在浏览器打开 `https://chatgpt.com/`，左下角点用户名，进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。Workspace 账号可能需要管理员允许设备码登录。设备代码不要分享给任何人，也不要粘贴到不可信页面。
+
 检查命令是否存在：
 
 ```bash

package/docs/zh/troubleshooting.md

@@ -157,6 +157,8 @@ codex --version
 codex login
 ```
 
+如果你通过 FoxClaw 的 `/login_device`、`/auth add <name>` 或 `/auth` 面板“设备登录”拿到了设备码，但登录页面提示没有权限、退回普通浏览器流程，或无头环境无法完成登录，先检查 ChatGPT 安全设置：打开 `https://chatgpt.com/`，左下角点用户名，进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。Workspace 账号可能需要管理员在 workspace 权限里允许设备码登录。设备代码等同于登录授权，切勿分享给他人。
+
 `codex --version` 只证明命令存在。要验证认证真的可用，运行：
 
 ```bash

package/docs/zh/user-manual.md

@@ -376,6 +376,10 @@ cp -L ~/.codex/auth.json ~/.codex/auth.json_personal
 - `/logout confirm`：退出当前 Codex 登录。
 - `/auth add <name>`：新增一个候选账号，例如 `/auth add work` 会创建 `auth.json_work` 并发起设备码登录。
 
+设备码登录是无头主机上的 Codex 登录流程。默认情况下 ChatGPT 账号可能没有打开这个权限。使用 `/login_device`、`/auth add <name>` 或 `/auth` 面板里的“设备登录”按钮前，先在浏览器打开 `https://chatgpt.com/`，左下角点用户名，进入“设置 > 安全”，启用“为 Codex 启用设备代码授权”。如果是 workspace/企业账号，可能需要管理员在 workspace 权限里允许设备码登录。
+
+开启后仍要谨慎：设备代码可以被钓鱼页面窃取，等同于一次登录授权。只在你确认的 ChatGPT/Codex 登录页面输入设备代码，不要把设备代码发给别人，也不要粘贴到不可信网页。
+
 `/auth add <name>` 的流程：
 
 1. FoxClaw 准备 `auth.json_<name>`。
@@ -415,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 同步
 
@@ -450,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.4",
+  "version": "0.5.6",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",