@foxden-app/foxclaw 0.5.11 → 0.5.12

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.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
 
 ### 中文

package/README.md

@@ -105,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

@@ -105,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 {

package/dist/auth/mirror.js

@@ -161,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;
@@ -203,7 +203,7 @@ export class AuthCandidateMirror {
             for (const runtime of this.runtimes) {
                 const destinationPath = path.join(runtime.authDir, name);
                 const destination = await readChatGptAuthRecord(destinationPath);
-                if (destination && destination.accountId !== canonical.accountId) {
+                if (destination && !authRecordsCompatible(destination, canonical)) {
                     skipped += 1;
                     this.logger.warn('auth.mirror.distribution_conflict', { runtimeId: runtime.id, name });
                     continue;
@@ -234,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);
@@ -288,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;
             }
@@ -422,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;
         }
@@ -544,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

@@ -357,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;

package/dist/controller/controller.js

@@ -5310,15 +5310,15 @@ export class BridgeSessionCore {
     async listCodexAuthState() {
         const state = await listCodexAuthState(this.store.listDisabledCodexAuthCandidateNames(this.authRuntimeId()), this.resolveAuthDir());
         const snapshots = await this.readCodexAuthQuotaSnapshots();
-        const candidateAccountIds = await this.readCodexAuthCandidateAccountIds(state.candidates);
+        const candidateQuotaIdentities = await this.readCodexAuthCandidateQuotaIdentities(state.candidates);
         state.candidates.forEach((candidate) => {
-            const candidateAccountId = candidateAccountIds.get(candidate.name) ?? null;
+            const candidateQuotaIdentity = candidateQuotaIdentities.get(candidate.name) ?? null;
             const snapshot = snapshots[candidate.name] ?? null;
-            candidate.quota = this.codexAuthQuotaSnapshotMatchesAccount(snapshot, candidateAccountId)
+            candidate.quota = this.codexAuthQuotaSnapshotMatchesIdentity(snapshot, candidateQuotaIdentity)
                 ? snapshot
                 : null;
         });
-        await this.applySharedCodexAuthQuotaSnapshots(state, candidateAccountIds);
+        await this.applySharedCodexAuthQuotaSnapshots(state, candidateQuotaIdentities);
         return state;
     }
     resolveAuthDir() {
@@ -5427,13 +5427,13 @@ export class BridgeSessionCore {
                         throw new Error('Codex did not return ChatGPT rate limits after refresh');
                     }
                     const after = await readChatGptAuthMetadata(candidate.path);
-                    if (!after || after.accountId !== before.accountId) {
-                        throw new Error('refreshed auth account id did not match the original candidate');
+                    if (!after || !chatGptAuthMetadataCompatible(before, after)) {
+                        throw new Error('refreshed auth identity did not match the original candidate');
                     }
                     if (after.lastRefreshMs <= before.lastRefreshMs) {
                         throw new Error('Codex did not advance last_refresh');
                     }
-                    await this.recordCodexAuthQuotaSnapshot(candidate.name, after.accountId, snapshot);
+                    await this.recordCodexAuthQuotaSnapshot(candidate.name, after, snapshot);
                     await this.syncCodexAuthCandidate(candidate.name);
                     result.refreshed.push(candidate.name);
                 }
@@ -5659,9 +5659,9 @@ export class BridgeSessionCore {
             if (!snapshot) {
                 return;
             }
-            const quota = authQuotaSnapshotFromRateLimit(snapshot, metadata?.accountId ?? null);
+            const quota = authQuotaSnapshotFromRateLimit(snapshot, metadata?.accountId ?? null, metadata?.quotaIdentityId ?? null);
             candidate.quota = quota;
-            await this.recordCodexAuthQuotaSnapshot(candidate.name, metadata?.accountId ?? null, snapshot);
+            await this.recordCodexAuthQuotaSnapshot(candidate.name, metadata, snapshot);
             await this.applySharedCodexAuthQuotaSnapshots(state);
             await this.syncCodexAuthCandidate(candidate.name);
         }
@@ -5669,36 +5669,36 @@ export class BridgeSessionCore {
             this.logger.warn('codex.auth_quota_refresh_failed', { error: formatUserError(error) });
         }
     }
-    async applySharedCodexAuthQuotaSnapshots(state, candidateAccountIds) {
-        const accountIds = candidateAccountIds ?? await this.readCodexAuthCandidateAccountIds(state.candidates);
-        const uniqueAccountIds = [...new Set(accountIds.values())];
-        if (uniqueAccountIds.length === 0) {
+    async applySharedCodexAuthQuotaSnapshots(state, candidateQuotaIdentities) {
+        const quotaIdentities = candidateQuotaIdentities ?? await this.readCodexAuthCandidateQuotaIdentities(state.candidates);
+        const uniqueQuotaIdentityIds = [...new Set([...quotaIdentities.values()].map(identity => identity.quotaIdentityId))];
+        if (uniqueQuotaIdentityIds.length === 0) {
             return;
         }
-        const snapshotsByAccount = new Map();
-        for (const record of this.store.listCodexAuthQuotaSnapshots(uniqueAccountIds)) {
+        const snapshotsByIdentity = new Map();
+        for (const record of this.store.listCodexAuthQuotaSnapshots(uniqueQuotaIdentityIds)) {
             if (!isFiniteCodexAuthQuotaSnapshotRecord(record)) {
                 continue;
             }
-            snapshotsByAccount.set(record.accountId, mergeCodexAuthQuotaSnapshots(snapshotsByAccount.get(record.accountId) ?? null, codexAuthQuotaSnapshotFromRecord(record)));
+            snapshotsByIdentity.set(record.quotaIdentityId, mergeCodexAuthQuotaSnapshots(snapshotsByIdentity.get(record.quotaIdentityId) ?? null, codexAuthQuotaSnapshotFromRecord(record)));
         }
         for (const candidate of state.candidates) {
-            const accountId = accountIds.get(candidate.name);
-            if (!accountId) {
+            const quotaIdentity = quotaIdentities.get(candidate.name);
+            if (!quotaIdentity) {
                 continue;
             }
-            candidate.quota = mergeCodexAuthQuotaSnapshots(candidate.quota, snapshotsByAccount.get(accountId) ?? null);
+            candidate.quota = mergeCodexAuthQuotaSnapshots(candidate.quota, snapshotsByIdentity.get(quotaIdentity.quotaIdentityId) ?? null);
         }
     }
-    async recordCodexAuthQuotaSnapshot(candidateName, accountId, snapshot) {
-        const quota = authQuotaSnapshotFromRateLimit(snapshot, accountId);
+    async recordCodexAuthQuotaSnapshot(candidateName, metadata, snapshot) {
+        const quota = authQuotaSnapshotFromRateLimit(snapshot, metadata?.accountId ?? null, metadata?.quotaIdentityId ?? null);
         this.authQuotaSnapshots[candidateName] = quota;
-        if (accountId) {
-            this.store.setCodexAuthQuotaSnapshot(this.authRuntimeId(), candidateName, accountId, quota);
+        if (metadata) {
+            this.store.setCodexAuthQuotaSnapshot(this.authRuntimeId(), candidateName, metadata.accountId, metadata.quotaIdentityId, quota);
         }
         await this.writeCodexAuthQuotaSnapshots();
     }
-    async readCodexAuthCandidateAccountIds(candidates) {
+    async readCodexAuthCandidateQuotaIdentities(candidates) {
         const entries = await Promise.all(candidates.map(async (candidate) => {
             const metadata = await readChatGptAuthMetadata(candidate.path);
             candidate.credentialKind = metadata
@@ -5707,24 +5707,28 @@ export class BridgeSessionCore {
                     ? 'api-key'
                     : 'invalid';
             candidate.credentialLastRefreshMs = metadata?.lastRefreshMs ?? null;
-            return [candidate.name, metadata?.accountId ?? null];
+            return [candidate.name, metadata ? {
+                    accountId: metadata.accountId,
+                    quotaIdentityId: metadata.quotaIdentityId,
+                } : null];
         }));
-        const accountIds = new Map();
-        for (const [name, accountId] of entries) {
-            if (accountId) {
-                accountIds.set(name, accountId);
+        const quotaIdentities = new Map();
+        for (const [name, quotaIdentity] of entries) {
+            if (quotaIdentity) {
+                quotaIdentities.set(name, quotaIdentity);
             }
         }
-        return accountIds;
+        return quotaIdentities;
     }
-    codexAuthQuotaSnapshotMatchesAccount(snapshot, accountId) {
+    codexAuthQuotaSnapshotMatchesIdentity(snapshot, identity) {
         if (!snapshot) {
             return false;
         }
-        if (!snapshot.accountId) {
-            return accountId === null;
+        const snapshotIdentityId = snapshot.quotaIdentityId ?? snapshot.accountId ?? null;
+        if (!snapshotIdentityId) {
+            return identity === null;
         }
-        return accountId !== null && snapshot.accountId === accountId;
+        return identity !== null && snapshotIdentityId === identity.quotaIdentityId;
     }
     async readCodexAuthQuotaSnapshots() {
         if (this.authQuotaSnapshotsLoaded) {
@@ -9368,10 +9372,11 @@ function formatRemainingUsagePercent(usedPercent) {
     const remainingPercent = remainingUsagePercent(usedPercent);
     return remainingPercent === null ? '?' : formatUsagePercent(remainingPercent);
 }
-function authQuotaSnapshotFromRateLimit(snapshot, accountId = null) {
+function authQuotaSnapshotFromRateLimit(snapshot, accountId = null, quotaIdentityId = null) {
     return {
         capturedAtMs: Date.now(),
         accountId,
+        quotaIdentityId,
         planType: snapshot.planType,
         primaryWindowDurationMins: snapshot.primary?.windowDurationMins ?? null,
         primaryRemainingPercent: snapshot.primary ? remainingUsagePercent(snapshot.primary.usedPercent) : null,
@@ -9383,6 +9388,7 @@ function codexAuthQuotaSnapshotFromRecord(record) {
     return {
         capturedAtMs: record.capturedAtMs,
         accountId: record.accountId,
+        quotaIdentityId: record.quotaIdentityId,
         planType: record.planType,
         primaryWindowDurationMins: record.primaryWindowDurationMins,
         primaryRemainingPercent: record.primaryRemainingPercent,
@@ -9402,6 +9408,7 @@ function mergeCodexAuthQuotaSnapshots(current, incoming) {
     return {
         ...freshest,
         accountId: freshest.accountId ?? older.accountId ?? null,
+        quotaIdentityId: freshest.quotaIdentityId ?? older.quotaIdentityId ?? null,
     };
 }
 function isFiniteCodexAuthQuotaSnapshotRecord(record) {
@@ -9450,6 +9457,7 @@ function isCodexAuthQuotaSnapshot(value) {
     return typeof snapshot.capturedAtMs === 'number'
         && Number.isFinite(snapshot.capturedAtMs)
         && (snapshot.accountId === undefined || snapshot.accountId === null || typeof snapshot.accountId === 'string')
+        && (snapshot.quotaIdentityId === undefined || snapshot.quotaIdentityId === null || typeof snapshot.quotaIdentityId === 'string')
         && (snapshot.planType === undefined || isNullableString(snapshot.planType))
         && (snapshot.primaryWindowDurationMins === undefined || isNullableFiniteNumber(snapshot.primaryWindowDurationMins))
         && isNullableFiniteNumber(snapshot.primaryRemainingPercent)
@@ -9460,6 +9468,7 @@ function normalizeCodexAuthQuotaSnapshot(snapshot) {
     return {
         capturedAtMs: snapshot.capturedAtMs,
         accountId: snapshot.accountId ?? null,
+        quotaIdentityId: snapshot.quotaIdentityId ?? snapshot.accountId ?? null,
         planType: snapshot.planType ?? null,
         primaryWindowDurationMins: snapshot.primaryWindowDurationMins ?? null,
         primaryRemainingPercent: snapshot.primaryRemainingPercent,
@@ -9467,6 +9476,15 @@ function normalizeCodexAuthQuotaSnapshot(snapshot) {
         secondaryRemainingPercent: snapshot.secondaryRemainingPercent,
     };
 }
+function chatGptAuthMetadataCompatible(left, right) {
+    if (left.accountId !== right.accountId) {
+        return false;
+    }
+    if (left.quotaIdentityId === left.accountId || right.quotaIdentityId === right.accountId) {
+        return true;
+    }
+    return left.quotaIdentityId === right.quotaIdentityId;
+}
 function isNullableFiniteNumber(value) {
     return value === null || (typeof value === 'number' && Number.isFinite(value));
 }

package/dist/main.js

@@ -334,6 +334,7 @@ async function runServeCli() {
                         ?? await mirror.readNewestCandidate(candidateName);
                     return await authSync?.requestRecovery(candidateName, {
                         accountId: current?.accountId ?? null,
+                        quotaIdentityId: current?.quotaIdentityId ?? null,
                         lastRefreshMs: current?.lastRefreshMs ?? null,
                     }) ?? false;
                 },
@@ -502,6 +503,7 @@ async function runServeCli() {
                     ?? null;
                 return await singleAuthSync?.requestRecovery(candidateName, {
                     accountId: current?.accountId ?? null,
+                    quotaIdentityId: current?.quotaIdentityId ?? null,
                     lastRefreshMs: current?.lastRefreshMs ?? null,
                 }) ?? false;
             },

package/dist/store/database.d.ts

@@ -28,6 +28,7 @@ export interface CodexAuthQuotaSnapshotRecord {
     runtimeId: string;
     candidateName: string;
     accountId: string;
+    quotaIdentityId: string;
     capturedAtMs: number;
     planType: string | null;
     primaryWindowDurationMins: number | null;
@@ -117,7 +118,7 @@ export declare class BridgeStore {
     setWeixinContextToken(scopeId: string, contextToken: string): void;
     listDisabledCodexAuthCandidateNames(runtimeId?: string): Set<string>;
     setCodexAuthCandidateDisabled(name: string, disabled: boolean, runtimeId?: string): void;
-    setCodexAuthQuotaSnapshot(runtimeId: string, candidateName: string, accountId: string, snapshot: Pick<CodexAuthQuotaSnapshotRecord, 'capturedAtMs' | 'planType' | 'primaryWindowDurationMins' | 'primaryRemainingPercent' | 'secondaryWindowDurationMins' | 'secondaryRemainingPercent'>): void;
-    listCodexAuthQuotaSnapshots(accountIds: string[]): CodexAuthQuotaSnapshotRecord[];
+    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

@@ -182,6 +182,7 @@ export class BridgeStore {
         runtime_id TEXT NOT NULL,
         candidate_name TEXT NOT NULL,
         account_id TEXT NOT NULL,
+        quota_identity_id TEXT NOT NULL DEFAULT '',
         captured_at_ms INTEGER NOT NULL,
         plan_type TEXT,
         primary_window_duration_mins REAL,
@@ -209,6 +210,16 @@ export class BridgeStore {
         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');
+        this.ensureColumn('codex_auth_quota_snapshots', 'quota_identity_id', "TEXT NOT NULL DEFAULT ''");
+        this.db.prepare(`
+      UPDATE codex_auth_quota_snapshots
+      SET quota_identity_id = account_id
+      WHERE quota_identity_id = ''
+    `).run();
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS codex_auth_quota_snapshots_quota_identity_idx
+        ON codex_auth_quota_snapshots(quota_identity_id);
+    `);
         migrateLegacyBridgeScopeIds(this.db);
     }
     getTelegramOffset(botKey) {
@@ -839,12 +850,13 @@ export class BridgeStore {
       ON CONFLICT(name) DO UPDATE SET disabled = excluded.disabled, updated_at = excluded.updated_at
     `).run(name, disabled ? 1 : 0, Date.now());
     }
-    setCodexAuthQuotaSnapshot(runtimeId, candidateName, accountId, snapshot) {
+    setCodexAuthQuotaSnapshot(runtimeId, candidateName, accountId, quotaIdentityId, snapshot) {
         this.db.prepare(`
       INSERT INTO codex_auth_quota_snapshots (
         runtime_id,
         candidate_name,
         account_id,
+        quota_identity_id,
         captured_at_ms,
         plan_type,
         primary_window_duration_mins,
@@ -853,9 +865,10 @@ export class BridgeStore {
         secondary_remaining_percent,
         updated_at
       )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(runtime_id, candidate_name) DO UPDATE SET
         account_id = excluded.account_id,
+        quota_identity_id = excluded.quota_identity_id,
         captured_at_ms = excluded.captured_at_ms,
         plan_type = excluded.plan_type,
         primary_window_duration_mins = excluded.primary_window_duration_mins,
@@ -863,19 +876,20 @@ export class BridgeStore {
         secondary_window_duration_mins = excluded.secondary_window_duration_mins,
         secondary_remaining_percent = excluded.secondary_remaining_percent,
         updated_at = excluded.updated_at
-    `).run(runtimeId, candidateName, accountId, snapshot.capturedAtMs, snapshot.planType, snapshot.primaryWindowDurationMins, snapshot.primaryRemainingPercent, snapshot.secondaryWindowDurationMins, snapshot.secondaryRemainingPercent, Date.now());
+    `).run(runtimeId, candidateName, accountId, quotaIdentityId, snapshot.capturedAtMs, snapshot.planType, snapshot.primaryWindowDurationMins, snapshot.primaryRemainingPercent, snapshot.secondaryWindowDurationMins, snapshot.secondaryRemainingPercent, Date.now());
     }
-    listCodexAuthQuotaSnapshots(accountIds) {
-        const uniqueAccountIds = [...new Set(accountIds.filter(Boolean))];
-        if (uniqueAccountIds.length === 0) {
+    listCodexAuthQuotaSnapshots(quotaIdentityIds) {
+        const uniqueQuotaIdentityIds = [...new Set(quotaIdentityIds.filter(Boolean))];
+        if (uniqueQuotaIdentityIds.length === 0) {
             return [];
         }
-        const placeholders = uniqueAccountIds.map(() => '?').join(', ');
+        const placeholders = uniqueQuotaIdentityIds.map(() => '?').join(', ');
         const rows = this.db.prepare(`
       SELECT
         runtime_id,
         candidate_name,
         account_id,
+        quota_identity_id,
         captured_at_ms,
         plan_type,
         primary_window_duration_mins,
@@ -884,12 +898,13 @@ export class BridgeStore {
         secondary_remaining_percent,
         updated_at
       FROM codex_auth_quota_snapshots
-      WHERE account_id IN (${placeholders})
-    `).all(...uniqueAccountIds);
+      WHERE quota_identity_id IN (${placeholders})
+    `).all(...uniqueQuotaIdentityIds);
         return rows.map(row => ({
             runtimeId: String(row.runtime_id),
             candidateName: String(row.candidate_name),
             accountId: String(row.account_id),
+            quotaIdentityId: String(row.quota_identity_id),
             capturedAtMs: Number(row.captured_at_ms),
             planType: nullableString(row.plan_type),
             primaryWindowDurationMins: nullableNumber(row.primary_window_duration_mins),

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

@@ -33,7 +33,7 @@ Safety boundaries:
 - FoxClaw only accepts sync files from bots listed in `AUTH_SYNC_PEERS`.
 - Wrong `AUTH_SYNC_KEY`, cluster, nonce, or payload validation never writes files.
 - Remote imports wait for global local idleness, then run temporary usage validation before writing a candidate.
-- A same-name candidate known to belong to a different account id is never overwritten.
+- A same-name candidate known to belong to a different account id, or to a different identifiable ChatGPT user/email under the same account, is never overwritten.
 - Sync packets do not create reply chains. FoxClaw filters by packet type, nonce, and peer allowlist to avoid bot-to-bot loops.
 
 Telegram's official Bot Features documentation says private bot-to-bot messaging requires Bot-to-Bot Communication Mode on both sender and recipient, and it calls out loop-prevention requirements. See https://core.telegram.org/bots/features#bot-to-bot-communication
@@ -164,7 +164,7 @@ If it shows `Missing replies: @peer_bot`, Telegram delivery may have succeeded,
 
 Confirm that pending imports were processed, or that the candidate exists or has a newer timestamp.
 
-Note: `/auth sync push all` saying “sent” only means this node successfully handed encrypted packages to Telegram. It does not prove the peer wrote files. The peer imports only when it is globally idle, usage validation succeeds, same-name candidates belong to the same account id, and the remote `last_refresh` is newer than the local copy. If the local file is already equal or newer, it will not change and `Last import` may remain empty.
+Note: `/auth sync push all` saying “sent” only means this node successfully handed encrypted packages to Telegram. It does not prove the peer wrote files. The peer imports only when it is globally idle, usage validation succeeds, same-name candidates belong to the same account id and compatible ChatGPT user/email identity, and the remote `last_refresh` is newer than the local copy. If the local file is already equal or newer, it will not change and `Last import` may remain empty.
 
 When cross-node sync is enabled, the contact bot private chat receives node-level notifications: local auth updates and the peers being contacted, received remote bundles and whether they were queued or immediately validated, import success/skip/failure reasons, recovery peer queries and peer replies, and a manual-intervention notice when every peer lacks an importable copy. Notifications never include auth contents, tokens, or encrypted bundle payloads.
 
@@ -198,7 +198,7 @@ With cross-node sync enabled, this command first requests a cross-node refresh l
 
 - The local node may not be globally idle. Active turns, approvals, inputs, login flows, and mirror writes make imports wait.
 - Usage validation failure rejects the write.
-- Same-name candidates from different account ids are refused.
+- Same-name candidates from different account ids, or from different identifiable ChatGPT users/emails under the same account, are refused.
 - Run `/auth sync events <candidate>` or `/auth sync trace <requestId>` to see the receive, validation, skip, or failure records kept by FoxClaw.
 
 **Should I periodically run `/auth refresh all confirm` as keepalive?**

package/docs/user-manual.md

@@ -359,7 +359,7 @@ FoxClaw recognizes candidate names in these forms:
 - `auth.json.<name>`
 - `auth.json-<name>`
 
-`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON and should not be hand-written. In multi-bot mode, FoxClaw mirrors a candidate only when its account identity matches, its refresh timestamp is newer, and the active app-server verifies it against the ChatGPT usage endpoint, preventing a same-name candidate from overwriting a different account. Before an auth switch or reload, FoxClaw also searches the other Codex homes for a newer credential with the same account ID, restores it into the requesting runtime, then verifies and mirrors it after restart.
+`auth.json` is what Codex currently uses. When switching accounts, FoxClaw points `auth.json` at one candidate. Candidate contents are Codex-generated JSON and should not be hand-written. In multi-bot mode, FoxClaw mirrors a candidate only when its account identity and identifiable ChatGPT user/email identity are compatible, its refresh timestamp is newer, and the active app-server verifies it against the ChatGPT usage endpoint, preventing a same-name candidate from overwriting a different account or Team seat. Before an auth switch or reload, FoxClaw also searches the other Codex homes for a newer compatible credential, restores it into the requesting runtime, then verifies and mirrors it after restart.
 
 If you already have a working `auth.json`, you can save it as a candidate:
 
@@ -395,7 +395,7 @@ If the login is cancelled or fails, FoxClaw tries to restore the previous auth t
 
 `/auth` lists candidate accounts, the current account, and the auth directory. It also provides buttons for switching, disabling, login, and reload. In multi-bot mode the panel names the `@botname` runtime being managed, because private chats, groups, and topics on one bot share that bot's current auth. The panel shows 8 candidates per page and supports paging, `All / Enabled / Attention` filters, and `/auth list <keyword>` filename search for large local inventories. Panel text and buttons omit the repeated `auth.json_` prefix from standard candidate filenames, so `auth.json_personal` on disk renders as `personal`; files are not renamed, and search and commands still operate on the original candidates. `/auth use <n>` always uses the full-list candidate number, independent of panel paging.
 
-Candidate rows are prefixed with observed `window:remaining-percent` values. For example, a Plus account may show `5h:20|7d:25`, while an account with one monthly window may show `30d:97`. Buttons use a compact two-number `primary|secondary` form such as `20|25`; unknown values render as `—`. The current auth quota is refreshed when the panel opens; other candidates are not switched merely to query quota. When multiple bot runtimes have recently used the same ChatGPT account, FoxClaw combines their cached quota snapshots by verified account ID, so one bot's `/auth` panel can show quota information learned by another bot without mixing different accounts.
+Candidate rows are prefixed with observed `window:remaining-percent` values. For example, a Plus account may show `5h:20|7d:25`, while an account with one monthly window may show `30d:97`. Buttons use a compact two-number `primary|secondary` form such as `20|25`; unknown values render as `—`. The current auth quota is refreshed when the panel opens; other candidates are not switched merely to query quota. When multiple bot runtimes have recently used the same ChatGPT quota identity, FoxClaw combines their cached quota snapshots by verified user/email identity under the account, so one bot's `/auth` panel can show quota information learned by another bot without mixing different seats on the same Team account.
 
 Approximation:
 
@@ -453,7 +453,7 @@ Safety boundaries:
 - Telegram only carries ciphertext. Auth contents, candidate names, account ids, and `last_refresh` live inside the AES-256-GCM encrypted payload.
 - 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.
+- A same-name candidate known to belong to a different account id, or to a different identifiable ChatGPT user/email under the same account, is never overwritten.
 - 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:

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

@@ -33,7 +33,7 @@
 - 只接收 `AUTH_SYNC_PEERS` 中列出的 peer bot 发来的同步文件。
 - `AUTH_SYNC_KEY`、cluster、nonce 或 payload 校验失败时不会写盘。
 - 远端导入必须等本机全局空闲，再临时验证 usage；验证成功后才写入候选。
-- 同名候选如果已知属于不同 account id，永远拒绝覆盖。
+- 同名候选如果已知属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱，永远拒绝覆盖。
 - 同步包不会触发自动回复链路；FoxClaw 对包类型、nonce 和 peer allowlist 做过滤，避免 bot-to-bot 循环。
 
 Telegram 官方 Bot Features 文档说明：私聊 bot-to-bot 需要发送方和接收方都启用 Bot-to-Bot Communication Mode，并提醒开发者处理 loop prevention。参考：https://core.telegram.org/bots/features#bot-to-bot-communication
@@ -164,7 +164,7 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 确认待导入清单被处理，或候选已经出现/更新时间变新。
 
-注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
+注意：`/auth sync push all` 的“已发送”只代表本节点把加密包发给 Telegram 成功，不代表对端已经写盘。对端只有在全局空闲、usage 验证通过、同名候选 account id 一致且 ChatGPT 用户/邮箱身份兼容，并且远端 `last_refresh` 比本地更新时才会覆盖文件。如果本地已经是相同或更新版本，文件不会变化，`最近导入` 也可能保持为空。
 
 启用跨节点同步后，联系人 bot 的私聊会收到节点级通知：本机 auth 更新并开始发往哪些 peer、收到远端包后是排队还是立即验证、导入成功/跳过/失败原因、auth 恢复时正在查询哪些 peer、peer 回应了什么，以及所有 peer 都无法提供可用副本时的人工介入提示。通知不会包含 auth 内容、token 或同步密文。
 
@@ -198,7 +198,7 @@ auth sync 测试完成：已发送 1，收到回应 1。
 
 - 本机可能不是全局空闲；有 turn、审批、待输入、登录流程或镜像写入时会排队。
 - usage 验证失败会拒绝写盘。
-- 同名候选属于不同 account id 时会拒绝覆盖。
+- 同名候选属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱时会拒绝覆盖。
 - 执行 `/auth sync events <候选名>` 或 `/auth sync trace <requestId>`，查看 FoxClaw 记录的接收、验证、跳过或失败流水。
 
 **要不要定期 `/auth refresh all confirm` 保活**

package/docs/zh/user-manual.md

@@ -359,7 +359,7 @@ FoxClaw 识别这些候选文件名：
 - `auth.json.<name>`
 - `auth.json-<name>`
 
-`auth.json` 是 Codex 当前使用的文件。切换账号时，FoxClaw 会把 `auth.json` 指向某个候选文件。候选文件内容是 Codex CLI 生成的 JSON，不建议手写这些字段。多 bot 镜像只在账号标识一致、刷新时间更新，并且由当前 app-server 通过 ChatGPT 用量接口在线验证时复制候选，避免同名候选意外覆盖成另一个账号。切换或重载 auth 之前，FoxClaw 还会在其他 Codex home 中查找同账号 ID 的较新凭据，先恢复到发起操作的 runtime，再在重启后验证并镜像。
+`auth.json` 是 Codex 当前使用的文件。切换账号时，FoxClaw 会把 `auth.json` 指向某个候选文件。候选文件内容是 Codex CLI 生成的 JSON，不建议手写这些字段。多 bot 镜像只在账号标识和可识别的 ChatGPT 用户/邮箱身份兼容、刷新时间更新，并且由当前 app-server 通过 ChatGPT 用量接口在线验证时复制候选，避免同名候选意外覆盖成另一个账号或同一 Team 下的另一个 seat。切换或重载 auth 之前，FoxClaw 还会在其他 Codex home 中查找兼容的较新凭据，先恢复到发起操作的 runtime，再在重启后验证并镜像。
 
 如果你已经有一个可用的 `auth.json`，可以先备份成候选：
 
@@ -395,7 +395,7 @@ cp -L ~/.codex/auth.json ~/.codex/auth.json_personal
 
 `/auth` 会列出候选账号、当前账号和 auth 目录，并提供按钮切换、禁用、登录和重载。多 bot 模式中，面板顶部还会显示当前正在管理的 `@botname`，因为该 bot 内的私聊、群聊和话题共享同一个当前 auth。面板每页显示 8 个候选，支持翻页、`全部 / 已启用 / 需关注` 筛选和 `/auth list <关键词>` 文件名搜索，适合管理较大的本地候选清单。面板文本和按钮会省略标准候选文件名中重复的 `auth.json_` 前缀，例如磁盘上的 `auth.json_personal` 显示为 `personal`；文件本身不会重命名，搜索和命令仍按原候选工作。命令 `/auth use <n>` 的编号始终对应完整候选列表，不会因为分页变化。
 
-文本列表中每个候选名前的 `窗口:剩余百分比` 来自最近一次观察到的真实额度窗口，例如 Plus 账号可能显示 `5h:20|7d:25`，只有一个月度窗口的账号可能显示 `30d:97`。按钮为了适配窄屏，只显示两个剩余百分比数字，例如 `20|25`；未知值显示为 `—`。当前 auth 会在打开面板时刷新额度；其他候选不会为了查询额度被自动切换。如果多个 bot runtime 最近使用过同一个 ChatGPT 账号，FoxClaw 会按已验证的账号 ID 合并它们缓存到的额度快照，因此一个 bot 的 `/auth` 面板可以显示另一个 bot 掌握到的额度信息，同时不会把不同账号混在一起。
+文本列表中每个候选名前的 `窗口:剩余百分比` 来自最近一次观察到的真实额度窗口，例如 Plus 账号可能显示 `5h:20|7d:25`，只有一个月度窗口的账号可能显示 `30d:97`。按钮为了适配窄屏，只显示两个剩余百分比数字，例如 `20|25`；未知值显示为 `—`。当前 auth 会在打开面板时刷新额度；其他候选不会为了查询额度被自动切换。如果多个 bot runtime 最近使用过同一个 ChatGPT 额度身份，FoxClaw 会按账号下已验证的用户/邮箱身份合并缓存到的额度快照，因此一个 bot 的 `/auth` 面板可以显示另一个 bot 掌握到的额度信息，同时不会把同一个 Team account 里的不同 seat 混在一起。
 
 示意：
 
@@ -453,7 +453,7 @@ AUTH_SYNC_NODE_ID=workstation-a
 - Telegram 只承载密文；auth 文件内容、候选名、account id、`last_refresh` 都在 AES-256-GCM 加密 payload 内。
 - 只接收 `AUTH_SYNC_PEERS` 中 peer bot 发来的同步文件；密钥、cluster、nonce 或 payload 校验失败时不会写盘。
 - 远端导入必须等本机全局空闲，再临时切换到待验证 auth、重启 app-server、读取 usage 验证成功后才写入候选。
-- 同名候选如果已知属于不同 account id，永远拒绝覆盖。
+- 同名候选如果已知属于不同 account id，或属于同一 account 下不同的可识别 ChatGPT 用户/邮箱，永远拒绝覆盖。
 - 跨节点恢复只拉取 peer 已持有的有效副本，不会在恢复过程中直接轮换 refresh token；找不到有效副本时会停止，提示你人工维护授权。后台 9 天主动刷新会单独申请跨节点刷新锁，拿不到锁就跳过本轮。
 
 双主动流程：

package/package.json

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