@foxden-app/foxclaw 0.5.10 → 0.5.12

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.12 - 2026-06-08
+
+### 中文
+- `/auth` 额度快照现在按 ChatGPT 额度身份合并，优先区分 `chatgpt_user_id`，其次区分 email，避免同一个 Team account 下不同 seat 显示成同一份额度。
+- 本机 auth mirror、跨节点 auth sync 和 `/auth refresh all` 会拒绝可识别为不同 ChatGPT 用户/邮箱的同名候选互相覆盖，即使它们共享同一个 account id。
+- 额度快照数据库新增 `quota_identity_id` 并自动兼容旧数据；文档同步说明 account id 与额度身份的区别。
+
+### English
+- `/auth` quota snapshots now merge by ChatGPT quota identity, preferring `chatgpt_user_id` and then email, so different seats under the same Team account do not display as one shared quota.
+- Same-node auth mirroring, cross-node auth sync, and `/auth refresh all` now refuse to overwrite same-name candidates when they are identifiable as different ChatGPT users/emails, even if they share the same account id.
+- Added a `quota_identity_id` quota-snapshot migration with backward compatibility for old data, and updated docs to distinguish account id from quota identity.
+
+## 0.5.11 - 2026-06-08
+
+### 中文
+- `/auth` 面板的 `Bot runtime` 现在显示 Telegram bot id，例如 `@WuguiAI2_Bot (bot8949529424)`，便于和 `~/.foxclaw/codex/telegram/<botid>/home` 对应。
+- `/auth` 面板新增“安全同步”按钮，并支持 `/auth sync safe`，可在全局空闲时安全打平本机多 bot auth，并把已校验的候选推送到跨节点 peer。
+- 本机 auth mirror 新增全量安全同步路径：只传播通过既有在线校验的刷新候选，同时补齐 canonical 中已知、同账号且更新的 runtime 副本。
+
+### English
+- The `/auth` panel now shows the Telegram bot id in `Bot runtime`, for example `@WuguiAI2_Bot (bot8949529424)`, making it easy to match the runtime with `~/.foxclaw/codex/telegram/<botid>/home`.
+- Added a Safe sync button to the `/auth` panel, plus `/auth sync safe`, to flatten same-node multi-bot auth while globally idle and push validated candidates to cross-node peers.
+- Added a full safe-sync path for the local auth mirror: it only propagates candidates that pass the existing online validation and fills runtime copies from newer same-account canonical candidates.
+
 ## 0.5.10 - 2026-06-08
 
 ### 中文

package/README.md

@@ -39,6 +39,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex，
 - 已经装好，想系统了解 `/help`、`/setup`、`/threads`、`/watch`、`/auth` 和账号轮转？看 [用户手册](./docs/zh/user-manual.md)。
 - 想把同一组合法 ChatGPT auth 候选同步到多台机器？看 [跨节点 auth 同步配置指南](./docs/zh/cross-node-auth-sync.md)。
 - 想了解每个版本改了什么？看 [更新日志](./CHANGELOG.md)。
+- 维护者准备发版？看 [发布 runbook](./docs/zh/release.md)。
 - Git、Node、`.env` 都玩得转？直接往下看快速设置。
 - 卡住了？看 [故障排查](./docs/zh/troubleshooting.md)。
 
@@ -104,7 +105,7 @@ FoxClaw 只响应 `TG_ALLOWED_USER_ID` 的消息——把机器人拉进群不
 **多账号管理：**
 - Codex 账户管理：`/account`、`/quota`、`/login_device`、`/auth add <name>`
 - 触发用量限制时自动在本地 `auth.json_*` 之间切换认证
-- `/auth` 面板分页查看、筛选、启用、禁用、搜索和切换候选账号；额度按真实窗口展示，多 bot 模式下会按账号 ID 汇总各 runtime 最近掌握的额度快照
+- `/auth` 面板分页查看、筛选、启用、禁用、搜索和切换候选账号；额度按真实窗口展示，多 bot 模式下会按 ChatGPT 额度身份汇总各 runtime 最近掌握的额度快照
 
 **线程与会话：**
 - `/threads`、`/open`、`/new`、`/where`、`/interrupt`——稳定的聊天-线程绑定

package/README_EN.md

@@ -39,6 +39,7 @@ FoxClaw is more than message forwarding. It provides Telegram panels for Codex w
 - Already installed and want the full command guide for `/help`, `/setup`, `/threads`, `/watch`, `/auth`, and auth rotation? Read the [User Manual](./docs/user-manual.md).
 - Want to sync the same legally owned ChatGPT auth candidate pool across multiple machines? Read the [Cross-Node Auth Sync Setup Guide](./docs/cross-node-auth-sync.md).
 - Want to see what changed in each release? Read the [Changelog](./CHANGELOG.md).
+- Maintaining a release? Use the [Release Runbook](./docs/release.md).
 - Already comfortable with Git, Node, and `.env` files? Use the quick setup below.
 - Something failed? Check [Troubleshooting](./docs/troubleshooting.md).
 
@@ -104,7 +105,7 @@ FoxClaw accepts messages only from `TG_ALLOWED_USER_ID`. Putting the bot in a gr
 **Multi-account management:**
 - Codex account controls: `/account`, `/quota`, `/login_device`, `/auth add <name>`
 - Automatic auth rotation across local `auth.json_*` files when a usage limit is hit — seamless account switching
-- Paginated `/auth` panel to filter, enable, disable, search, and switch candidate accounts; quota uses observed window lengths, and multi-bot mode merges recent snapshots by account ID across runtimes
+- Paginated `/auth` panel to filter, enable, disable, search, and switch candidate accounts; quota uses observed window lengths, and multi-bot mode merges recent snapshots by ChatGPT quota identity across runtimes
 
 **Threads and sessions:**
 - `/threads`, `/open`, `/new`, `/where`, `/interrupt` — sticky chat-to-thread binding

package/dist/auth/cross_node_sync.d.ts

@@ -226,6 +226,7 @@ export declare class CrossNodeAuthSync {
     publishDigest(): Promise<void>;
     requestRecovery(candidateName: string, current?: {
         accountId: string | null;
+        quotaIdentityId?: string | null;
         lastRefreshMs: number | null;
     }): Promise<boolean>;
     acquireRefreshLease(reason: string): Promise<AuthSyncLeaseResult>;

package/dist/auth/cross_node_sync.js

@@ -275,6 +275,7 @@ export class CrossNodeAuthSync {
                 requestId,
                 candidateName,
                 accountId: current?.accountId ?? null,
+                quotaIdentityId: current?.quotaIdentityId ?? null,
                 lastRefreshMs: current?.lastRefreshMs ?? null,
             }).catch((error) => {
                 clearTimeout(timer);
@@ -519,6 +520,18 @@ export class CrossNodeAuthSync {
             });
             return;
         }
+        if (!quotaIdentitiesCompatible(record.accountId, record.quotaIdentityId, message.quotaIdentityId ?? null)) {
+            await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'quota identity mismatch' });
+            this.recordEvent({ direction: 'local', kind: 'pull.response', stage: 'account_mismatch', peer, requestId: message.requestId, candidateName: message.candidateName, detail: 'quota identity mismatch' });
+            this.notify({
+                kind: 'pull_response_sent',
+                candidateName: message.candidateName,
+                peer,
+                result: 'account_mismatch',
+                reason: 'quota identity mismatch',
+            });
+            return;
+        }
         if (message.lastRefreshMs !== null && record.lastRefreshMs <= message.lastRefreshMs) {
             await this.sendToPeer(peer, { kind: 'pull.response', requestId: message.requestId, bundle: null, reason: 'not newer' });
             this.recordEvent({ direction: 'local', kind: 'pull.response', stage: 'not_newer', peer, requestId: message.requestId, candidateName: message.candidateName, detail: 'not newer' });
@@ -728,6 +741,9 @@ export class CrossNodeAuthSync {
         if (!metadata || metadata.accountId !== bundle.accountId || metadata.lastRefreshMs !== bundle.lastRefreshMs) {
             return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote bundle metadata mismatch for ${bundle.candidateName}`);
         }
+        if (bundle.quotaIdentityId && metadata.quotaIdentityId !== bundle.quotaIdentityId) {
+            return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote bundle quota identity mismatch for ${bundle.candidateName}`);
+        }
         if (sha256(bundle.rawAuth) !== bundle.authSha256) {
             return this.rejectImport(bundle, sourceNodeId, source, fromPeer, mode, `remote bundle hash mismatch for ${bundle.candidateName}`);
         }
@@ -1078,6 +1094,7 @@ function bundleFromRecord(record) {
     return {
         candidateName: record.candidateName,
         accountId: record.accountId,
+        quotaIdentityId: record.quotaIdentityId,
         lastRefreshMs: record.lastRefreshMs,
         rawAuth: record.raw,
         authSha256: sha256(record.raw),
@@ -1087,11 +1104,18 @@ function isValidBundle(value) {
     return typeof value.candidateName === 'string'
         && isAuthCandidateName(value.candidateName)
         && typeof value.accountId === 'string'
+        && (value.quotaIdentityId === undefined || value.quotaIdentityId === null || typeof value.quotaIdentityId === 'string')
         && typeof value.lastRefreshMs === 'number'
         && Number.isFinite(value.lastRefreshMs)
         && typeof value.rawAuth === 'string'
         && typeof value.authSha256 === 'string';
 }
+function quotaIdentitiesCompatible(accountId, left, right) {
+    if (!left || !right || left === accountId || right === accountId) {
+        return true;
+    }
+    return left === right;
+}
 function decodeSharedKey(raw) {
     const value = raw.trim();
     const candidates = [];

package/dist/auth/mirror.d.ts

@@ -32,6 +32,9 @@ export interface AuthMirrorValidationResult {
 }
 export interface ChatGptAuthMetadata {
     accountId: string;
+    quotaIdentityId: string;
+    userId: string | null;
+    email: string | null;
     lastRefreshMs: number;
 }
 export interface ChatGptAuthRecord extends ChatGptAuthMetadata {
@@ -52,6 +55,10 @@ export interface AuthMirrorSyncedEvent {
     status: AuthMirrorStatus;
     record: AuthMirrorCandidateRecord;
 }
+export interface AuthMirrorSyncAllResult {
+    synced: number;
+    skipped: number;
+}
 export interface AuthMirrorHooks {
     onSynced?: (event: AuthMirrorSyncedEvent) => Promise<void> | void;
 }
@@ -77,8 +84,10 @@ export declare class AuthCandidateMirror {
     readRuntimeCandidate(runtimeId: string, candidateName: string): Promise<AuthMirrorCandidateRecord | null>;
     listNewestCandidates(): Promise<AuthMirrorCandidateRecord[]>;
     syncRuntimeCandidate(runtimeId: string, candidateName: string): Promise<boolean>;
+    syncAllRuntimeCandidates(): Promise<AuthMirrorSyncAllResult>;
     recoverRuntimeCandidate(runtimeId: string, candidateName: string): Promise<AuthMirrorRecovery | null>;
     private scan;
+    private distributeCanonicalCandidates;
     importExternalCandidate(candidateName: string, raw: string, source: {
         nodeId: string;
         label?: string | null;

package/dist/auth/mirror.js

@@ -126,6 +126,28 @@ export class AuthCandidateMirror {
             return false;
         return this.withActivity(() => this.propagateValidatedCandidate(runtime, candidateName));
     }
+    async syncAllRuntimeCandidates() {
+        return this.withActivity(async () => {
+            let synced = 0;
+            let skipped = 0;
+            for (const runtime of this.runtimes) {
+                const names = await listAuthCandidateNames(runtime.authDir);
+                for (const name of names) {
+                    if (await this.propagateValidatedCandidate(runtime, name)) {
+                        synced += 1;
+                    }
+                    else {
+                        skipped += 1;
+                    }
+                }
+            }
+            const distributed = await this.distributeCanonicalCandidates();
+            return {
+                synced: synced + distributed.synced,
+                skipped: skipped + distributed.skipped,
+            };
+        });
+    }
     async recoverRuntimeCandidate(runtimeId, candidateName) {
         if (!isAuthCandidateName(candidateName))
             return null;
@@ -139,7 +161,7 @@ export class AuthCandidateMirror {
                 return null;
             const sources = await this.collectAuthRecords();
             const newest = sources
-                .filter(entry => entry.record.accountId === destination.accountId)
+                .filter(entry => authRecordsCompatible(entry.record, destination))
                 .reduce((current, entry) => (!current || entry.record.lastRefreshMs > current.record.lastRefreshMs ? entry : current), null);
             if (!newest || newest.record.lastRefreshMs <= destination.lastRefreshMs) {
                 return null;
@@ -169,6 +191,33 @@ export class AuthCandidateMirror {
             }
         });
     }
+    async distributeCanonicalCandidates() {
+        let synced = 0;
+        let skipped = 0;
+        for (const name of await listAuthCandidateNames(this.canonicalDir)) {
+            const canonical = await readChatGptAuthRecord(path.join(this.canonicalDir, name));
+            if (!canonical) {
+                skipped += this.runtimes.length;
+                continue;
+            }
+            for (const runtime of this.runtimes) {
+                const destinationPath = path.join(runtime.authDir, name);
+                const destination = await readChatGptAuthRecord(destinationPath);
+                if (destination && !authRecordsCompatible(destination, canonical)) {
+                    skipped += 1;
+                    this.logger.warn('auth.mirror.distribution_conflict', { runtimeId: runtime.id, name });
+                    continue;
+                }
+                if (destination && destination.lastRefreshMs >= canonical.lastRefreshMs) {
+                    skipped += 1;
+                    continue;
+                }
+                await atomicWrite(destinationPath, canonical.raw);
+                synced += 1;
+            }
+        }
+        return { synced, skipped };
+    }
     async importExternalCandidate(candidateName, raw, source) {
         if (!isAuthCandidateName(candidateName)) {
             return { ok: false, imported: false, reason: 'invalid candidate name' };
@@ -185,9 +234,9 @@ export class AuthCandidateMirror {
                 }
                 const existing = (await this.collectAuthRecords())
                     .filter(entry => entry.candidateName === candidateName);
-                const conflicting = existing.find(entry => entry.record.accountId !== metadata.accountId);
+                const conflicting = existing.find(entry => !authRecordsCompatible(entry.record, metadata));
                 if (conflicting) {
-                    return { ok: false, imported: false, reason: 'same candidate belongs to a different account' };
+                    return { ok: false, imported: false, reason: 'same candidate belongs to a different account or ChatGPT user' };
                 }
                 const newest = existing.reduce((current, entry) => (!current || entry.record.lastRefreshMs > current.record.lastRefreshMs ? entry : current), null);
                 const previousRefresh = Math.max(newest?.record.lastRefreshMs ?? 0, this.lastSyncedRefresh.get(candidateName) ?? 0);
@@ -239,7 +288,7 @@ export class AuthCandidateMirror {
                 return false;
             const canonicalPath = path.join(this.canonicalDir, name);
             const canonical = await readChatGptAuthRecord(canonicalPath);
-            if (canonical && canonical.accountId !== record.accountId) {
+            if (canonical && !authRecordsCompatible(canonical, record)) {
                 this.logger.warn('auth.mirror.account_conflict', { runtimeId: runtime.id, name });
                 return false;
             }
@@ -373,8 +422,8 @@ export class AuthCandidateMirror {
         })))).filter((entry) => entry.record !== null);
         if (records.length === 0)
             return;
-        const accountIds = new Set(records.map((entry) => entry.record.accountId));
-        if (accountIds.size !== 1) {
+        const reference = records[0].record;
+        if (records.some(entry => !authRecordsCompatible(reference, entry.record))) {
             this.logger.warn('auth.mirror.startup_conflict', { name });
             return;
         }
@@ -495,7 +544,72 @@ export function parseChatGptAuthMetadata(raw) {
         const lastRefreshMs = typeof parsed.last_refresh === 'string' ? Date.parse(parsed.last_refresh) : NaN;
         if (!accountId || !Number.isFinite(lastRefreshMs))
             return null;
-        return { accountId, lastRefreshMs };
+        const accessClaims = decodeJwtPayload(parsed.tokens?.access_token);
+        const idClaims = decodeJwtPayload(parsed.tokens?.id_token);
+        const userId = firstStringClaim(accessClaims, idClaims, 'https://api.openai.com/auth.chatgpt_user_id', 'https://api.openai.com/auth.user_id');
+        const email = firstStringClaim(accessClaims, idClaims, 'https://api.openai.com/profile.email', 'email');
+        return {
+            accountId,
+            quotaIdentityId: chatGptQuotaIdentityId(accountId, userId, email),
+            userId,
+            email,
+            lastRefreshMs,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function chatGptQuotaIdentityId(accountId, userId, email) {
+    if (userId) {
+        return `${accountId}:user:${userId}`;
+    }
+    if (email) {
+        return `${accountId}:email:${email.toLowerCase()}`;
+    }
+    return accountId;
+}
+function authRecordsCompatible(left, right) {
+    if (left.accountId !== right.accountId) {
+        return false;
+    }
+    if (!isSpecificQuotaIdentity(left) || !isSpecificQuotaIdentity(right)) {
+        return true;
+    }
+    return left.quotaIdentityId === right.quotaIdentityId;
+}
+function isSpecificQuotaIdentity(metadata) {
+    return metadata.quotaIdentityId !== metadata.accountId;
+}
+function firstStringClaim(primary, secondary, ...keys) {
+    for (const claims of [primary, secondary]) {
+        if (!claims) {
+            continue;
+        }
+        for (const key of keys) {
+            const value = claims[key];
+            if (typeof value === 'string' && value.trim()) {
+                return value;
+            }
+        }
+    }
+    return null;
+}
+function decodeJwtPayload(token) {
+    if (typeof token !== 'string') {
+        return null;
+    }
+    const parts = token.split('.');
+    if (parts.length < 2 || !parts[1]) {
+        return null;
+    }
+    try {
+        const base64 = parts[1].replaceAll('-', '+').replaceAll('_', '/');
+        const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+        const parsed = JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
     }
     catch {
         return null;

package/dist/controller/controller.d.ts

@@ -19,6 +19,12 @@ export interface CoreCoordinator {
     }>;
     releaseAuthRefreshLease?: (leaseId: string | null) => Promise<void>;
     getAuthSyncStatus?: () => RuntimeStatus['authSync'];
+    authSyncSafeAll?: () => Promise<{
+        localSynced: number;
+        localSkipped: number;
+        sent: number;
+        skipped: number;
+    }>;
     authSyncPushAll?: () => Promise<{
         sent: number;
         skipped: number;
@@ -283,6 +289,7 @@ export declare class BridgeSessionCore {
     private notifyProactiveAuthRefresh;
     private handleAuthCommand;
     private handleAuthSyncCommand;
+    private runAuthSafeSyncAll;
     private handleAuthRefreshAllCommand;
     private handleAuthUseCommand;
     private handleAuthToggleCommand;
@@ -350,8 +357,8 @@ export declare class BridgeSessionCore {
     private refreshCurrentCodexAuthQuota;
     private applySharedCodexAuthQuotaSnapshots;
     private recordCodexAuthQuotaSnapshot;
-    private readCodexAuthCandidateAccountIds;
-    private codexAuthQuotaSnapshotMatchesAccount;
+    private readCodexAuthCandidateQuotaIdentities;
+    private codexAuthQuotaSnapshotMatchesIdentity;
     private readCodexAuthQuotaSnapshots;
     private writeCodexAuthQuotaSnapshots;
     private codexAuthQuotaSnapshotPath;