Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(auth): 阻止群聊认证失败触发反复续期 (#5672)

bobo0c0a2e57768a
diff --git a/apps/desktop/src/main/__tests__/authCredentialStoreHealth.test.ts b/apps/desktop/src/main/__tests__/authCredentialStoreHealth.test.ts
index 4fbaa0ea84..dc09a7b52c 100644
--- a/apps/desktop/src/main/__tests__/authCredentialStoreHealth.test.ts
+++ b/apps/desktop/src/main/__tests__/authCredentialStoreHealth.test.ts
@@ -206,7 +206,7 @@ describe('authManager credential-store escalation wiring', () => {
expect(noteIdx).toBeGreaterThan(body.indexOf('treating as transient'));
// 注意 refresh body 更早处(realm manifest 分支)也调用了同名重排函数,
// 必须取 noteReadFailure 之后的那一次。
- const retryAfterNote = body.indexOf('scheduleRefreshRetryAfterTransientFailure();', noteIdx);
+ const retryAfterNote = body.indexOf('scheduleRefreshRetryAfterTransientFailure(refreshEpoch);', noteIdx);
expect(retryAfterNote).toBeGreaterThan(noteIdx);
// 升级不改变瞬时语义:transient 分支内不得出现实际的过期 / 清态调用
// (匹配调用形态,避免误中提及函数名的注释)。
diff --git a/apps/desktop/src/main/__tests__/authPassiveSharedInstance.test.ts b/apps/desktop/src/main/__tests__/authPassiveSharedInstance.test.ts
index d8d5aac236..6e294e91c6 100644
--- a/apps/desktop/src/main/__tests__/authPassiveSharedInstance.test.ts
+++ b/apps/desktop/src/main/__tests__/authPassiveSharedInstance.test.ts
@@ -117,7 +117,7 @@ describe('passive shared-userData instance auth isolation', () => {
expect(scheduleBody).toContain('refreshTimer = setTimeout(');
const retryBody = sliceBody(
- 'function scheduleRefreshRetryAfterTransientFailure(): void {',
+ 'function scheduleRefreshRetryAfterTransientFailure(epoch: number, retryAt?: number): void {',
'\n}\n',
);
expect(retryBody).not.toContain('isPassiveSharedUserDataInstance');
diff --git a/apps/desktop/src/main/__tests__/authRefreshBackoff.test.ts b/apps/desktop/src/main/__tests__/authRefreshBackoff.test.ts
new file mode 100644
index 0000000000..13ebdc4e5e
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/authRefreshBackoff.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { AuthRefreshBackoff } from '../authRefreshBackoff';
+
+describe('runtime auth refresh backoff', () => {
+ it('keeps an absolute deadline across two-second explicit calls and resumes at expiry', () => {
+ let now = 1_000_000;
+ const backoff = new AuthRefreshBackoff(() => now);
+ expect(backoff.remaining(1)).toBe(0);
+ expect(backoff.defer(1)).toBe(60_000);
+ for (let elapsed = 2_000; elapsed < 60_000; elapsed += 2_000) {
+ now = 1_000_000 + elapsed;
+ expect(backoff.remaining(1)).toBe(60_000 - elapsed);
+ }
+ now = 1_060_000;
+ expect(backoff.remaining(1)).toBe(0);
+ });
+
+ it('honors a longer server wait without applying the failed login generation to another account', () => {
+ let now = 1_000_000;
+ const backoff = new AuthRefreshBackoff(() => now);
+ expect(backoff.defer(1, now + 120_000)).toBe(120_000);
+ now += 60_000;
+ expect(backoff.remaining(1)).toBe(60_000);
+ expect(backoff.remaining(2)).toBe(0);
+ backoff.defer(2);
+ expect(backoff.remaining(1)).toBe(0);
+ expect(backoff.remaining(2)).toBe(60_000);
+ });
+
+ it.each([undefined, 0, 999_999, Number.NaN, Number.POSITIVE_INFINITY])('retains the minimum wait for invalid or shorter deadline %s', retryAt => {
+ const backoff = new AuthRefreshBackoff(() => 1_000_000);
+ expect(backoff.defer(1, retryAt)).toBe(60_000);
+ });
+
+ it('clears the failed wait when a successful login or refresh schedules normal renewal', () => {
+ const backoff = new AuthRefreshBackoff(() => 1_000_000);
+ backoff.defer(1);
+ backoff.clear();
+ expect(backoff.remaining(1)).toBe(0);
+ });
+});
diff --git a/apps/desktop/src/main/__tests__/authSessionExpiredDetection.test.ts b/apps/desktop/src/main/__tests__/authSessionExpiredDetection.test.ts
index 9a36a071f1..6aa569158f 100644
--- a/apps/desktop/src/main/__tests__/authSessionExpiredDetection.test.ts
+++ b/apps/desktop/src/main/__tests__/authSessionExpiredDetection.test.ts
@@ -40,7 +40,7 @@ describe('desktop auth session-expiry detection', () => {
expect(body).toContain('treating as transient');
// 瞬时分支必须重排 refresh 重试:正常 timer 已触发过,不重排则密钥链/IO 抖动
// 后有效会话在 access token 到期前没有任何后续 refresh(半死)。
- expect(body).toContain('scheduleRefreshRetryAfterTransientFailure();');
+ expect(body).toContain('scheduleRefreshRetryAfterTransientFailure(refreshEpoch);');
expect(body.indexOf('isPersistedSecretAbsent(AUTH_SESSION_KEY)')).toBeLessThan(
body.indexOf("await expireRuntimeAuth(previousUserId, 'credential-lost', {"),
);
diff --git a/apps/desktop/src/main/authManager.ts b/apps/desktop/src/main/authManager.ts
index 4e02f27b6c..c080f496b6 100644
--- a/apps/desktop/src/main/authManager.ts
+++ b/apps/desktop/src/main/authManager.ts
@@ -23,6 +23,7 @@ import { machineIdSync } from 'node-machine-id';
import {
AuthApiError,
CindyAuthClient,
+ retryAfterDeadline,
discoverEmailLogin,
discoverPersonalLoginOrganization,
discoverSsoOrgRealm,
@@ -50,6 +51,7 @@ import { isEnableBetaUserCustomized, readUpdateChannelSettings } from './updateC
import { BRAND_IDENTITY } from '@cindy/maker-shared/brand-identity';
import * as canaryFlagStore from './canaryFlagStore';
import { decodeAccessTokenOrgSlug } from './authTokenClaims';
+import { AuthRefreshBackoff } from './authRefreshBackoff';
import { getProviderSecretStore } from './secrets/providerSecretStore.js';
import {
runRefreshWithReplacementRetry,
@@ -379,6 +381,7 @@ let activeAuthRealm: AuthRegion = AUTH_REGION;
let pendingAuthRealm: AuthRegion | null = null;
let refreshTimer: ReturnType<typeof setTimeout> | null = null;
let refreshPromise: Promise<boolean> | null = null;
+const refreshBackoff = new AuthRefreshBackoff();
let sessionInvalidationPromise: Promise<void> | null = null;
// Real owner change / logout: keep the renderer fail-closed even if a late
// notifyRenderer() races the teardown. Same-owner Ghost repair must not set
@@ -2271,7 +2274,7 @@ async function apiFetch<T>(
timeoutMs?: number;
baseUrl?: string;
},
-): Promise<{ ok: boolean; status: number; data: T }> {
+): Promise<{ ok: boolean; status: number; data: T; retryAt?: number }> {
const url = (options?.baseUrl ?? authServerUrl()) + apiPath;
const method = options?.method ?? 'GET';
const headers: Record<string, string> = { 'Content-Type': 'application/json' };
@@ -2289,14 +2292,18 @@ async function apiFetch<T>(
body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
signal: effectiveTimeout > 0 ? controller.signal : undefined,
});
- const data = (await response.json()) as T;
+ const retryAt = response.status === 429 ? retryAfterDeadline(response) : undefined;
+ let data: T;
+ try { data = (await response.json()) as T; }
+ catch { return { ok: false, status: response.status, data: null as T, retryAt }; }
const errorCode = (data as AuthErrorResponse | null)?.error?.code;
if (response.status === 401 && errorCode === 'ACCOUNT_UNAVAILABLE' && currentUser) {
// Internal auth-server calls (profile/feature flags/refresh) do not pass
// through serverApiClient, but share the same terminal auth contract.
void invalidateSession('account-unavailable');
}
- return { ok: response.ok, status: response.status, data };
+ return { ok: response.ok, status: response.status, data,
+ ...(retryAt !== undefined ? { retryAt } : {}) };
} catch {
return { ok: false, status: 0, data: null as T };
} finally {
@@ -3085,6 +3092,7 @@ async function openLoopbackBrowserAuthorization(
// ── Refresh scheduling ──────────────────────────────────────────────────────
function scheduleRefresh(token: string): void {
+ refreshBackoff.clear();
if (refreshTimer !== null) {
clearTimeout(refreshTimer);
refreshTimer = null;
@@ -3318,12 +3326,22 @@ function scheduleNonXdOrgBetaDefault(input: {
*/
let coldStartAuthInFlight: Promise<AuthState> | null = null;
-function scheduleRefreshRetryAfterTransientFailure(): void {
+function scheduleRefreshRetryAfterTransientFailure(epoch: number, retryAt?: number): void {
+ if (epoch !== authStateEpoch) return;
+ const delay = refreshBackoff.defer(epoch, retryAt);
if (refreshTimer !== null) {
clearTimeout(refreshTimer);
refreshTimer = null;
}
- refreshTimer = setTimeout(() => void refresh(), RUNTIME_REFRESH_RETRY_MS);
+ // A long server deadline must not overflow Node's timer into an immediate
+ // retry; re-arm it in bounded chunks without extending the original wait.
+ const retry = () => {
+ if (authStateEpoch !== epoch) return;
+ const remaining = refreshBackoff.remaining(epoch);
+ if (remaining > 0) refreshTimer = setTimeout(retry, Math.min(remaining, 2_147_483_647));
+ else { refreshTimer = null; void refresh(); }
+ };
+ refreshTimer = setTimeout(retry, Math.min(delay, 2_147_483_647));
}
function clearReplacementIntegrationReloadTimers(): void {
@@ -3651,6 +3669,7 @@ function clearAuth(
): void {
const notify = opts.notify ?? true;
authStateEpoch += 1; // 迟到的冷启动流程从此作废(见 authStateEpoch 注释)
+ refreshBackoff.clear();
loginFlowEpoch += 1;
// Explicit logout clears health. Failed startup keeps its recovery reason
// in the same synchronous commit, so owner cleanup cannot erase the error.
@@ -5698,6 +5717,9 @@ export async function refresh(): Promise<boolean> {
return false;
}
if (refreshPromise !== null) return refreshPromise;
+ // Explicit callers (including chat polling and resume) share the same wait
+ // as the retry timer; skipped calls must not move the deadline forward.
+ if (refreshBackoff.remaining(authStateEpoch) > 0) return false;
refreshPromise = (async () => {
const refreshEpoch = authStateEpoch;
@@ -5721,7 +5743,7 @@ export async function refresh(): Promise<boolean> {
await loadClientEndpointsForRealm(persistedSession.realm);
} catch (error) {
log.warn('runtime auth realm manifest unavailable; retrying later', error);
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch);
return false;
}
}
@@ -5752,7 +5774,7 @@ export async function refresh(): Promise<boolean> {
}
// 正常 refresh timer 已经触发过,这里不重排的话,一次密钥链/IO 抖动
// 会让有效会话在 access token 到期前没有任何后续 refresh(半死)。
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch);
return false;
}
const previousUserId = currentUser.id;
@@ -5793,7 +5815,7 @@ export async function refresh(): Promise<boolean> {
// this request was in flight. Its failure cannot expire or delete the
// newer owner, even when both accounts live in the same realm.
log.warn('runtime auth session changed on disk; discarding stale refresh failure');
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch);
return false;
}
if (!result.ok) {
@@ -5818,14 +5840,14 @@ export async function refresh(): Promise<boolean> {
});
} else if (action.kind === 'replacement-retry') {
log.warn(
- `runtime refresh failed for a stale token after replacement retries status=${result.status} code=${code ?? '<none>'} — retrying in ${RUNTIME_REFRESH_RETRY_MS / 1000}s`,
+ `runtime refresh failed for a stale token after replacement retries status=${result.status} code=${code ?? '<none>'} — retrying no sooner than ${RUNTIME_REFRESH_RETRY_MS / 1000}s`,
);
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch, result.retryAt);
} else {
log.warn(
- `runtime refresh failed transiently status=${result.status} code=${code ?? '<none>'} — retrying in ${RUNTIME_REFRESH_RETRY_MS / 1000}s`,
+ `runtime refresh failed transiently status=${result.status} code=${code ?? '<none>'} — retrying no sooner than ${RUNTIME_REFRESH_RETRY_MS / 1000}s`,
);
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch, result.retryAt);
}
return false;
}
@@ -5841,7 +5863,7 @@ export async function refresh(): Promise<boolean> {
log.warn(
`runtime refresh lost active credential ownership (${credentialCommit}); preserved only the still-saved account token and will reconcile from disk`,
);
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch);
return false;
}
lastAcceptedRefreshToken = data.refreshToken;
@@ -5983,7 +6005,7 @@ export async function refresh(): Promise<boolean> {
// apiFetch 消化了网络错误(status 0 走上面 !ok 分支),这里是本地状态同步异常;
// 与瞬时失败同等对待:记录并重排,避免刷新链就此断掉。
log.error('runtime refresh threw — retrying later', err);
- scheduleRefreshRetryAfterTransientFailure();
+ scheduleRefreshRetryAfterTransientFailure(refreshEpoch);
return false;
}
})();
diff --git a/apps/desktop/src/main/authRefreshBackoff.ts b/apps/desktop/src/main/authRefreshBackoff.ts
new file mode 100644
index 0000000000..c03512f45e
--- /dev/null
+++ b/apps/desktop/src/main/authRefreshBackoff.ts
@@ -0,0 +1,22 @@
+/** Process-local retry deadline, scoped to the current login generation. */
+export class AuthRefreshBackoff {
+ private epoch = -1;
+ private retryAt = 0;
+
+ constructor(private readonly now: () => number = () => Date.now()) {}
+
+ remaining(epoch: number): number {
+ return this.epoch === epoch ? Math.max(0, this.retryAt - this.now()) : 0;
+ }
+
+ defer(epoch: number, serverRetryAt?: number): number {
+ this.epoch = epoch;
+ this.retryAt = Math.max(this.now() + 60_000, Number.isFinite(serverRetryAt) ? serverRetryAt! : 0);
+ return this.remaining(epoch);
+ }
+
+ clear(): void {
+ this.epoch = -1;
+ this.retryAt = 0;
+ }
+}
diff --git a/apps/desktop/src/main/authRefreshFailure.ts b/apps/desktop/src/main/authRefreshFailure.ts
index 4713d360be..7956064ecf 100644
--- a/apps/desktop/src/main/authRefreshFailure.ts
+++ b/apps/desktop/src/main/authRefreshFailure.ts
@@ -161,6 +161,8 @@ export interface RefreshFetchResult<T> {
ok: boolean;
status: number;
data: T;
+ /** Local deadline derived from a rate-limit response's Retry-After header. */
+ retryAt?: number;
}
/** 每次失败时回传给调用方的诊断信息(供日志)。 */
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/chatServer.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/chatServer.test.ts
index 16d840c2da..989a8e69dc 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/chatServer.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/chatServer.test.ts
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-const fixture = vi.hoisted(() => ({ download: vi.fn(), packaged: true, urls: [] as string[], wsUrls: [] as string[], exists: vi.fn(), config: '', handle: vi.fn(), profiles: [] as unknown[], sockets: [] as import('ws').WebSocket[] }));
-vi.mock('../../authManager.js', () => ({ getAccessToken: () => 'isolated-test-token', refresh: vi.fn(async () => true) }));
+const fixture = vi.hoisted(() => ({ download: vi.fn(), packaged: true, urls: [] as string[], wsUrls: [] as string[], exists: vi.fn(), config: '', handle: vi.fn(), profiles: [] as unknown[], sockets: [] as import('ws').WebSocket[], token: 'isolated-test-token', refresh: vi.fn(async () => true), requests: [] as Array<{ url: string; token: string }> }));
+vi.mock('../../authManager.js', () => ({ getAccessToken: () => fixture.token, refresh: fixture.refresh }));
vi.mock('../../clientEndpointsService.js', () => ({ getClientEndpoint: () => 'https://chat.cindy.app' }));
vi.mock('../chatServerMedia.js', () => ({ createChatMedia: () => ({ upload: vi.fn(async () => []), download: fixture.download }) }));
vi.mock('../chatServerWorkspaces.js', () => ({ chatServerWorkspaces: () => ({ read: () => null, save: vi.fn() }) }));
@@ -14,15 +14,16 @@ vi.mock('../../localDb/client/current.js', () => ({ getDbClient: () => ({ drizzl
} }) }));
vi.mock('node:http', async () => {
const { EventEmitter } = await import('node:events');
- return { request: (url: string, options: { method: string }, callback: (response: unknown) => void) => {
+ return { request: (url: string, options: { method: string; headers: { Authorization: string } }, callback: (response: unknown) => void) => {
fixture.urls.push(String(url));
+ fixture.requests.push({ url: String(url), token: options.headers.Authorization });
const req = Object.assign(new EventEmitter(), {
end: (data?: string) => {
void Promise.resolve().then(() => fixture.handle(new URL(url).pathname.slice(3) + new URL(url).search, options.method, data ? JSON.parse(data) : undefined))
.then(result => {
- const response = Object.assign(new EventEmitter(), { statusCode: result?.status ?? 200 });
+ const response = Object.assign(new EventEmitter(), { statusCode: result?.status ?? 200, headers: result?.headers ?? {} });
callback(response);
- response.emit('data', Buffer.from(JSON.stringify(result?.body ?? {})));
+ response.emit('data', Buffer.from(result?.rawBody ?? JSON.stringify(result?.body ?? {})));
response.emit('end');
}, error => req.emit('error', error));
},
@@ -108,6 +109,8 @@ describe('Chat Server result delivery and refresh', () => {
fixture.config = '{"baseUrl":"http://127.0.0.1:3018","auth":"cindy"}';
vi.stubEnv('XDT_ISOLATED', '1');
fixture.handle.mockImplementation(response);
+ fixture.token = 'isolated-test-token';
+ fixture.refresh.mockReset().mockResolvedValue(true);
deps = { ensureLane: vi.fn(async () => ({ ok: true, sessionId: 'lane' })), abortLane: vi.fn(async () => {}),
dispatch: vi.fn(async (input: Parameters<BotGroupChatServiceDeps['dispatch']>[0]) => { await input.onAccepted?.(); return { ok: true }; }),
onChanged: vi.fn(),
@@ -288,6 +291,184 @@ describe('Chat Server result delivery and refresh', () => {
expect(deps.abortLane).not.toHaveBeenCalled();
});
+ it.each(['TOKEN_EXPIRED', 'INVALID_TOKEN', 'AUTH_REQUIRED'])('preserves an immutable completion during %s while Auth refresh fails or waits', async code => {
+ let recovering = false;
+ fixture.refresh.mockResolvedValue(false);
+ fixture.handle.mockImplementation((route, _method, body) => body?.action === 'complete' && !recovering
+ ? { status: 401, body: { error: { code } } } : response(route));
+ await start();
+ expect(await service.settleLaneTurn(terminal)).toBe(true);
+ const payload = deliveries()[0][2];
+ await vi.advanceTimersByTimeAsync(58_000);
+ expect(deliveries()).toHaveLength(1);
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ recovering = true;
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(deliveries()).toHaveLength(2);
+ expect(deliveries()[1][2]).toEqual(payload);
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ await vi.advanceTimersByTimeAsync(30_000);
+ expect(deliveries()).toHaveLength(2);
+ });
+
+ it('retains a completion when Auth rotates successfully but Chat still rejects the new token', async () => {
+ let recovering = false;
+ fixture.refresh.mockImplementation(async () => { fixture.token = 'renewed-test-token'; return true; });
+ fixture.handle.mockImplementation((route, _method, body) => body?.action === 'complete' && !recovering
+ ? { status: 401, body: { error: { code: 'INVALID_TOKEN' } } } : response(route));
+ await start();
+ await service.settleLaneTurn(terminal);
+ expect(deliveries()).toHaveLength(2);
+ await vi.advanceTimersByTimeAsync(58_000);
+ expect(deliveries()).toHaveLength(2);
+ recovering = true;
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(deliveries()).toHaveLength(3);
+ expect(deliveries().every(([, , body]) => JSON.stringify(body) === JSON.stringify(deliveries()[0][2]))).toBe(true);
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
+ it('keeps the lease alive while a prepared completion waits for authentication recovery', async () => {
+ let recovering = false;
+ let leaseUntil = Date.now() + 60_000;
+ let committed = 0;
+ fixture.refresh.mockResolvedValue(false);
+ fixture.handle.mockImplementation((route, _method, body) => {
+ if (body?.action === 'complete' && !recovering) return { status: 401, body: { error: { code: 'INVALID_TOKEN' } } };
+ if (body?.action === 'heartbeat' || body?.action === 'complete') {
+ if (Date.now() >= leaseUntil) return { status: 409, body: { error: { code: 'STALE_EXECUTOR' } } };
+ leaseUntil = Date.now() + 60_000;
+ if (body.action === 'complete') committed += 1;
+ }
+ return response(route);
+ });
+ await start();
+ await service.settleLaneTurn(terminal);
+ await vi.advanceTimersByTimeAsync(58_000);
+ expect(deliveries()).toHaveLength(1);
+ recovering = true;
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(committed).toBe(1);
+ expect(deliveries()[1][2]).toEqual(deliveries()[0][2]);
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
+ it.each([
+ { status: 401, code: 'ACCOUNT_UNAVAILABLE' },
+ { status: 403, code: 'ROLE_REQUIRED' },
+ { status: 404, code: 'EXECUTION_NOT_FOUND' },
+ { status: 409, code: 'STALE_EXECUTOR' },
+ { status: 410, code: 'EXECUTION_EXPIRED' },
+ ])('releases an auth-delayed completion immediately after a definitive heartbeat $code', async ({ status, code }) => {
+ let rejectHeartbeat = false;
+ let replacementQueued = false;
+ const nextExecution = { ...execution, id: '40000000-0000-4000-8000-000000000002', epoch: 2 };
+ fixture.handle.mockImplementation((route, _method, body) => {
+ if (body?.action === 'complete') return { status: 429, headers: { 'retry-after': '3600' }, body: { error: { code: 'RATE_LIMITED' } } };
+ if (body?.action === 'heartbeat' && rejectHeartbeat) {
+ rejectHeartbeat = false;
+ return { status, body: { error: { code } } };
+ }
+ if (route === '/executions/claim' && replacementQueued) {
+ replacementQueued = false;
+ return { body: { execution: nextExecution } };
+ }
+ return response(route);
+ });
+ await start();
+ await service.settleLaneTurn(terminal);
+ rejectHeartbeat = true;
+ replacementQueued = true;
+ await vi.advanceTimersByTimeAsync(18_000);
+ expect(deps.dispatch).toHaveBeenCalledTimes(2);
+ expect(vi.mocked(deps.dispatch).mock.calls[1][0].clientId).toContain(nextExecution.id);
+ expect(deliveries()).toHaveLength(1);
+ await vi.advanceTimersByTimeAsync(3_600_000);
+ expect(deliveries()).toHaveLength(1);
+ });
+
+ it.each([401, 503])('retains the completed reply when the waiting heartbeat has a temporary %s response', async status => {
+ let recovering = false;
+ fixture.refresh.mockResolvedValue(false);
+ fixture.handle.mockImplementation((route, _method, body) => {
+ if (body?.action === 'complete' && !recovering) return { status: 401, body: { error: { code: 'INVALID_TOKEN' } } };
+ if (body?.action === 'heartbeat' && !recovering && Date.now() > new Date('2026-10-03T00:00:02Z').getTime())
+ return { status, body: { error: { code: status === 401 ? 'INVALID_TOKEN' : 'SERVICE_UNAVAILABLE' } } };
+ return response(route);
+ });
+ await start();
+ await service.settleLaneTurn(terminal);
+ await vi.advanceTimersByTimeAsync(58_000);
+ recovering = true;
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(deliveries()).toHaveLength(2);
+ expect(deliveries()[1][2]).toEqual(deliveries()[0][2]);
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
+ it('keeps the original completion receipt lookup after a lost committed response', async () => {
+ let committed: unknown;
+ fixture.handle.mockImplementation((route, _method, body) => {
+ if (body?.action === 'heartbeat' && committed) return { status: 409, body: { error: { code: 'STALE_EXECUTOR' } } };
+ if (body?.action === 'complete') {
+ if (!committed) { committed = body; throw new Error('ECONNRESET'); }
+ expect(body).toEqual(committed);
+ }
+ return response(route);
+ });
+ await start();
+ await service.settleLaneTurn(terminal);
+ await vi.advanceTimersByTimeAsync(16_000);
+ expect(deliveries()).toHaveLength(2);
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
+ it.each([401, 429])('preserves a pending completion after an HTML %s and observes the delivery wait', async status => {
+ let recovering = false;
+ fixture.handle.mockImplementation((route, _method, body) => body?.action === 'complete' && !recovering
+ ? { status, headers: { 'retry-after': '120' }, rawBody: '<html>temporary upstream fixture</html>' } : response(route));
+ await start();
+ await service.settleLaneTurn(terminal);
+ const wait = status === 429 ? 120_000 : 60_000;
+ await vi.advanceTimersByTimeAsync(wait - 2_000);
+ expect(deliveries()).toHaveLength(1);
+ recovering = true;
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(deliveries()).toHaveLength(2);
+ expect(deliveries()[1][2]).toEqual(deliveries()[0][2]);
+ expect(fixture.refresh).not.toHaveBeenCalled();
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
+ it.each([{ status: 401, code: 'ACCOUNT_UNAVAILABLE' }, { status: 403, code: 'ROLE_REQUIRED' }, { status: 409, code: 'STALE_EXECUTOR' }])('stops a completion after a definitive rejection $code', async ({ status, code }) => {
+ fixture.handle.mockImplementation((route, _method, body) => body?.action === 'complete'
+ ? { status, body: { error: { code } } } : response(route));
+ await start();
+ await service.settleLaneTurn(terminal);
+ await vi.advanceTimersByTimeAsync(120_000);
+ expect(deliveries()).toHaveLength(1);
+ expect(fixture.refresh).not.toHaveBeenCalled();
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
+ it('does not retry a previous owner’s auth-delayed completion', async () => {
+ service.dispose();
+ let epoch = 0;
+ deps.captureOwnerScope = () => ({ epoch }) as ReturnType<NonNullable<BotGroupChatServiceDeps['captureOwnerScope']>>;
+ deps.isOwnerScopeCurrent = captured => (captured as unknown as { epoch: number }).epoch === epoch;
+ service = withChatServer({ dispose: vi.fn() } as unknown as BotGroupChatService, deps);
+ fixture.refresh.mockResolvedValue(false);
+ fixture.handle.mockImplementation((route, _method, body) => body?.action === 'complete'
+ ? { status: 401, body: { error: { code: 'INVALID_TOKEN' } } } : response(route));
+ await start();
+ await service.settleLaneTurn(terminal);
+ epoch += 1;
+ await vi.advanceTimersByTimeAsync(120_000);
+ expect(deliveries()).toHaveLength(1);
+ expect(deps.dispatch).toHaveBeenCalledOnce();
+ });
+
it('uses a fresh operation id for each lease renewal', async () => {
await start();
await vi.advanceTimersByTimeAsync(30000);
@@ -347,3 +528,157 @@ describe('Chat Server result delivery and refresh', () => {
expect(fixture.handle.mock.calls.some(([route]) => route.includes('/messages?'))).toBe(false);
});
});
+
+describe('Chat authentication recovery and polling backoff', () => {
+ let service: BotGroupChatService;
+ const denied = (code = 'INVALID_TOKEN') => ({ status: 401, body: { error: { code } } });
+ const healthy = (route: string) => ({ body: route === '/me' ? { actor: { id: 'self' } } : [] });
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date('2026-10-09T00:00:00Z'));
+ fixture.packaged = true;
+ fixture.profiles = [];
+ fixture.requests = [];
+ fixture.token = 'isolated-test-token';
+ fixture.refresh.mockReset().mockResolvedValue(true);
+ fixture.handle.mockReset().mockImplementation(healthy);
+ service = withChatServer({ dispose: vi.fn(), listGroups: async () => ({ ok: true, groups: [] }) } as unknown as BotGroupChatService, {} as BotGroupChatServiceDeps);
+ });
+
+ afterEach(() => {
+ service.dispose();
+ fixture.token = 'isolated-test-token';
+ fixture.refresh.mockReset().mockResolvedValue(true);
+ vi.useRealTimers();
+ });
+
+ it.each(['TOKEN_EXPIRED', 'INVALID_TOKEN', 'AUTH_REQUIRED'])('refreshes %s once and replays with the current token', async code => {
+ fixture.handle.mockImplementation(route => fixture.token === 'isolated-test-token' ? denied(code) : healthy(route));
+ fixture.refresh.mockImplementation(async () => { fixture.token = 'renewed-test-token'; return true; });
+ expect(await service.chatServer!.refreshProfile()).toMatchObject({ ok: true });
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ expect(fixture.requests.map(r => r.token)).toEqual(['Bearer isolated-test-token', 'Bearer renewed-test-token']);
+ });
+
+ it.each([true, false])('bounds repeated foreground 401s when Auth refresh returns %s', async refreshed => {
+ fixture.handle.mockImplementation(() => denied());
+ let rotation = 0;
+ fixture.refresh.mockImplementation(async () => {
+ if (refreshed) fixture.token = `renewed-test-token-${++rotation}`;
+ return refreshed;
+ });
+ for (let i = 0; i < 10; i += 1) {
+ expect(await service.chatServer!.refreshProfile()).toMatchObject({ ok: false });
+ }
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ expect(fixture.requests).toHaveLength(refreshed ? 11 : 10);
+ await vi.advanceTimersByTimeAsync(58_000);
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ await vi.advanceTimersByTimeAsync(2_000);
+ await service.chatServer!.refreshProfile();
+ expect(fixture.refresh).toHaveBeenCalledTimes(2);
+ });
+
+ it('shares one refresh across concurrent 401 responses', async () => {
+ let finish!: (value: boolean) => void;
+ fixture.refresh.mockImplementation(() => new Promise<boolean>(resolve => { finish = resolve; }));
+ fixture.handle.mockImplementation(route => fixture.token === 'isolated-test-token' ? denied('TOKEN_EXPIRED') : healthy(route));
+ const first = service.chatServer!.refreshProfile();
+ const second = service.chatServer!.refreshProfile();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ fixture.token = 'renewed-test-token';
+ finish(true);
+ expect(await Promise.all([first, second])).toEqual([{ ok: true }, { ok: true }]);
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ });
+
+ it('reuses a newer token for a late 401 without rotating again', async () => {
+ let finish!: (value: ReturnType<typeof denied>) => void;
+ fixture.handle.mockImplementationOnce(() => new Promise(resolve => { finish = resolve; }));
+ fixture.handle.mockImplementation(route => fixture.token === 'isolated-test-token' ? denied() : healthy(route));
+ fixture.refresh.mockImplementation(async () => { fixture.token = 'renewed-test-token'; return true; });
+ const first = service.chatServer!.refreshProfile();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(await service.chatServer!.refreshProfile()).toMatchObject({ ok: true });
+ finish(denied());
+ expect(await first).toMatchObject({ ok: true });
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ });
+
+ it.each(['ACCOUNT_UNAVAILABLE', 'SOME_OTHER_CODE', undefined])('does not refresh on a non-recoverable 401 code %s', async code => {
+ fixture.handle.mockImplementation(() => ({ status: 401, body: { error: { code } } }));
+ expect(await service.chatServer!.refreshProfile()).toMatchObject({ ok: false });
+ expect(fixture.refresh).not.toHaveBeenCalled();
+ });
+
+ it('pauses the two-second poll after persistent 401 and resumes after the wait', async () => {
+ fixture.handle.mockImplementation(() => denied());
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(fixture.requests).toHaveLength(2);
+ await vi.advanceTimersByTimeAsync(58_000);
+ expect(fixture.requests).toHaveLength(2);
+ fixture.handle.mockImplementation(healthy);
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(fixture.requests.some(r => new URL(r.url).pathname === '/v1/actors')).toBe(true);
+ expect(fixture.refresh).toHaveBeenCalledOnce();
+ });
+
+ it.each([false, true])('honors a longer Retry-After on 429 (HTML=%s) without calling Auth refresh', async html => {
+ fixture.handle.mockImplementation(() => ({ status: 429, headers: { 'retry-after': '120' }, body: { error: { code: 'RATE_LIMITED' } }, ...(html ? { rawBody: '<html>rate limit fixture</html>' } : {}) }));
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(fixture.requests).toHaveLength(1);
+ await vi.advanceTimersByTimeAsync(118_000);
+ expect(fixture.requests).toHaveLength(1);
+ fixture.handle.mockImplementation(healthy);
+ await vi.advanceTimersByTimeAsync(2_000);
+ expect(fixture.requests.some(r => new URL(r.url).pathname === '/v1/actors')).toBe(true);
+ expect(fixture.refresh).not.toHaveBeenCalled();
+ });
+
+ it('backs off temporary server errors and returns to normal polling on recovery', async () => {
+ fixture.handle.mockImplementation(() => ({ status: 503, body: { error: { code: 'JWKS_UNAVAILABLE' } } }));
+ await vi.advanceTimersByTimeAsync(18_000);
+ expect(fixture.requests).toHaveLength(4); // Requests at 2s, 4s, 8s and 16s.
+ fixture.handle.mockImplementation(healthy);
+ await vi.advanceTimersByTimeAsync(14_000);
+ const meCalls = () => fixture.requests.filter(r => new URL(r.url).pathname === '/v1/me').length;
+ expect(meCalls()).toBe(5);
+ await vi.advanceTimersByTimeAsync(6_000);
+ expect(meCalls()).toBe(6);
+ expect(fixture.refresh).not.toHaveBeenCalled();
+ });
+
+ it('does not refresh on an HTML challenge or leak its body through the error result', async () => {
+ fixture.handle.mockImplementation(() => ({ status: 401, rawBody: '<script>private-challenge-fixture</script>' }));
+ const result = await service.chatServer!.refreshProfile();
+ expect(result).toEqual({ ok: false, errorCode: 'INVALID_CHAT_RESPONSE' });
+ expect(fixture.refresh).not.toHaveBeenCalled();
+ expect(JSON.stringify(result)).not.toContain('private-challenge-fixture');
+ });
+
+ it('discards a late refresh after owner change and gives the new owner an independent recovery window', async () => {
+ service.dispose();
+ let epoch = 0;
+ const deps = {
+ captureOwnerScope: () => ({ epoch }),
+ isOwnerScopeCurrent: (scope: { epoch: number }) => scope.epoch === epoch,
+ } as unknown as BotGroupChatServiceDeps;
+ service = withChatServer({ dispose: vi.fn() } as unknown as BotGroupChatService, deps);
+ fixture.handle.mockImplementation(() => denied());
+ let finish!: (value: boolean) => void;
+ fixture.refresh.mockImplementation(() => new Promise<boolean>(resolve => { finish = resolve; }));
+ const oldRequest = service.chatServer!.refreshProfile();
+ await vi.advanceTimersByTimeAsync(0);
+ epoch += 1;
+ fixture.token = 'new-owner-test-token';
+ finish(true);
+ expect(await oldRequest).toMatchObject({ ok: false });
+ expect(fixture.requests).toHaveLength(1);
+ fixture.refresh.mockResolvedValue(true);
+ await service.chatServer!.refreshProfile();
+ expect(fixture.refresh).toHaveBeenCalledTimes(2);
+ expect(fixture.requests.slice(1).every(r => r.token === 'Bearer new-owner-test-token')).toBe(true);
+ });
+});
diff --git a/apps/desktop/src/main/maker-ipc/chatServer.ts b/apps/desktop/src/main/maker-ipc/chatServer.ts
index dcf9015a3c..5239918a7c 100644
--- a/apps/desktop/src/main/maker-ipc/chatServer.ts
+++ b/apps/desktop/src/main/maker-ipc/chatServer.ts
@@ -5,6 +5,7 @@ import { uploadPublicAsset } from '../ossPublicUpload.js';
import { getClientEndpoint } from '../clientEndpointsService.js';
import { readFile as readMedia } from '../cindy-media/blobStore.js';
import { getAccessToken, refresh } from '../authManager.js';
+import { retryAfterDeadline } from '@cindy/auth-client';
import { existsSync, readFileSync } from 'node:fs';
import { request as httpRequest } from 'node:http';
import { request as httpsRequest } from 'node:https';
@@ -58,7 +59,7 @@ interface ServerPlan {
}
interface Running {
execution: Execution; sessionId: string; clientId: string; accepted: boolean; started: number;
- settlement?: { terminal: BotGroupLaneTerminal; payload?: Record<string, unknown>; retryAt: number };
+ settlement?: { terminal: BotGroupLaneTerminal; payload?: Record<string, unknown>; retryAt: number; keepLease?: boolean };
delivery?: Promise<void>;
plan?: ServerPlan;
workspace?: { workDir: string; branch: string | null; ownerSessionId: string | null };
@@ -67,8 +68,14 @@ interface Running {
releaseToolAuthority?: () => void;
}
class ChatResponseError extends Error {
- constructor(code: string, readonly status: number) { super(code); }
+ constructor(code: string, readonly status: number, readonly retryAt?: number) { super(code); }
}
+const CHAT_AUTH_RETRY_MS = 60_000;
+const CHAT_REFRESHABLE_ERROR_CODES = new Set(['TOKEN_EXPIRED', 'INVALID_TOKEN', 'AUTH_REQUIRED']);
+const recoverableAuth = (error: ChatResponseError) => error.status === 401
+ && (CHAT_REFRESHABLE_ERROR_CODES.has(error.message) || error.message === 'INVALID_CHAT_RESPONSE');
+const retryableResponse = (error: ChatResponseError) => recoverableAuth(error)
+ || error.status >= 500 || [408, 429].includes(error.status);
const id = z.string().uuid();
const groupInput = z.object({ name: z.string().trim().min(1).max(40), botIds: z.array(z.string().min(1)).max(6) });
const failure = (message: string): BotGroupFailure => ({ ok: false, errorCode: 'HOST_NOT_READY', message });
@@ -139,6 +146,8 @@ function createChatServer(local: BotGroupChatService, deps: BotGroupChatServiceD
let reconnect: ReturnType<typeof setTimeout> | undefined;
let reconnectDelay = 500;
let refreshActors: Promise<void> | undefined;
+ let authRefreshPromise: Promise<boolean> | undefined;
+ let authRefreshRetryAt = 0;
let upgradedGroups = new Map<string, string>();
const changed = (roomId: string) => {
if (!current()) return;
@@ -149,6 +158,17 @@ function createChatServer(local: BotGroupChatService, deps: BotGroupChatServiceD
};
// TLS for production; explicit loopback is only enabled by the isolated fixture.
// Redirects are never followed and every retry remains in the captured account.
+ function refreshRejectedToken(token: string): Promise<boolean> {
+ if (!current()) return Promise.resolve(false);
+ // A concurrent request may already have replaced this request's token.
+ if (getAccessToken() !== token) return Promise.resolve(Boolean(getAccessToken()));
+ if (authRefreshPromise) return authRefreshPromise;
+ if (Date.now() < authRefreshRetryAt) return Promise.resolve(false);
+ // Even a successful refresh cannot repair a persistent upstream 401.
+ authRefreshRetryAt = Date.now() + CHAT_AUTH_RETRY_MS;
+ authRefreshPromise = refresh().finally(() => { authRefreshPromise = undefined; });
+ return authRefreshPromise;
+ }
function api<T>(route: string, method = 'GET', data?: unknown, actorId?: string, retried = false): Promise<T> {
if (!current()) return Promise.reject(new Error('OWNER_CHANGED'));
if (!config.baseUrl) return Promise.reject(new Error('CHAT_ENDPOINT_UNAVAILABLE'));
@@ -171,13 +191,19 @@ function createChatServer(local: BotGroupChatService, deps: BotGroupChatServiceD
res.on('end', async () => {
try {
if (!current()) throw new Error('OWNER_CHANGED');
- if (res.statusCode === 401 && !retried) {
- if (await refresh() && current()) { resolve(api<T>(route, method, data, actorId, true)); return; }
- throw new Error('AUTH_REQUIRED');
- }
if ((res.statusCode ?? 500) >= 300 && (res.statusCode ?? 500) < 400) throw new Error('CHAT_REDIRECT_REFUSED');
- const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
- if ((res.statusCode ?? 500) >= 400) throw new ChatResponseError(value.error?.code ?? 'REQUEST_FAILED', res.statusCode ?? 500);
+ const status = res.statusCode ?? 500;
+ const retryAt = status === 429 ? retryAfterDeadline({ headers: {
+ get: name => { const header = res.headers[name.toLowerCase()]; return typeof header === 'string' ? header : null; },
+ } }) : undefined;
+ let value;
+ try { value = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+ catch { throw new ChatResponseError('INVALID_CHAT_RESPONSE', status >= 400 ? status : 502, retryAt); }
+ const code = typeof value?.error?.code === 'string' ? value.error.code : 'REQUEST_FAILED';
+ if (res.statusCode === 401 && !retried && CHAT_REFRESHABLE_ERROR_CODES.has(code)) {
+ if (await refreshRejectedToken(token) && current()) { resolve(api<T>(route, method, data, actorId, true)); return; }
+ }
+ if (status >= 400) throw new ChatResponseError(code, status, retryAt);
resolve(value);
} catch (error) { reject(error); }
});
@@ -564,8 +590,13 @@ function createChatServer(local: BotGroupChatService, deps: BotGroupChatServiceD
// Keep the result during transport/temporary service failures. A definitive
// rejection (including revoked/expired leases) must never rerun the Agent
// or post the private result under a new execution identity.
- if (!(error instanceof ChatResponseError) || error.status >= 500 || [408, 429].includes(error.status)) {
- pending.retryAt = Date.now() + 15000;
+ const recoveringAuth = error instanceof ChatResponseError && recoverableAuth(error);
+ if (!(error instanceof ChatResponseError) || retryableResponse(error)) {
+ const delayed = recoveringAuth || (error instanceof ChatResponseError && error.status === 429);
+ pending.keepLease = delayed;
+ pending.retryAt = delayed
+ ? Math.max(Date.now() + CHAT_AUTH_RETRY_MS, error instanceof ChatResponseError ? error.retryAt ?? 0 : 0)
+ : Date.now() + 15000;
return;
}
} finally { run.delivery = undefined; }
@@ -701,8 +732,10 @@ function createChatServer(local: BotGroupChatService, deps: BotGroupChatServiceD
}
}
let polling = false;
+ let pollRetryAt = 0;
+ let pollFailures = 0;
const timer = setInterval(() => {
- if (!current() || polling) return;
+ if (!current() || polling || Date.now() < pollRetryAt) return;
polling = true;
void (async () => {
for (const run of running.values()) if (run.settlement) void deliverSettlement(run);
@@ -714,14 +747,33 @@ function createChatServer(local: BotGroupChatService, deps: BotGroupChatServiceD
const { execution } = await api<{ execution: Execution | null }>('/executions/claim', 'POST', { operationId: randomUUID(), executorId, accessPolicyVersion: 1, planVersion: 1 }, actor.id);
if (execution) void runExecution(execution);
}
- })().catch(() => undefined).finally(() => { polling = false; });
+ })().then(() => { pollFailures = 0; pollRetryAt = 0; }).catch(error => {
+ if (error instanceof ChatResponseError && (error.status === 401 || error.status === 429)) {
+ pollRetryAt = Math.max(Date.now() + CHAT_AUTH_RETRY_MS, error.retryAt ?? 0);
+ } else if (!(error instanceof ChatResponseError) || error.status >= 500) {
+ pollFailures += 1;
+ pollRetryAt = Date.now() + Math.min(60_000, 2_000 * 2 ** Math.min(pollFailures - 1, 5));
+ }
+ }).finally(() => { polling = false; });
}, 2000);
const checking = new Set<Running>();
async function checkLease(run: Running) {
if (run.settlement) {
- // Large step artifacts may take longer than one lease to upload. Keep the
- // lease alive while preparing the immutable completion, never rerun the Agent.
- if (!run.settlement.payload) await updateExecution(run, 'heartbeat').catch(() => undefined);
+ // Auth/rate-limit waits need lease renewal; ordinary lost-response retries
+ // preserve the existing receipt lookup without an intervening heartbeat.
+ if (!run.settlement.payload || run.settlement.keepLease) {
+ try { await updateExecution(run, 'heartbeat'); }
+ catch (error) {
+ if (error instanceof ChatResponseError && !retryableResponse(error)) {
+ if (running.get(run.execution.bot_id) === run) {
+ run.releaseToolAuthority?.();
+ running.delete(run.execution.bot_id);
+ changed(run.execution.conversation_id);
+ }
+ return;
+ }
+ }
+ }
await deliverSettlement(run); return;
}
if (checking.has(run) || running.get(run.execution.bot_id) !== run) return;
diff --git a/docs/dev-rules/credentials-and-local-storage.md b/docs/dev-rules/credentials-and-local-storage.md
index 188be46109..704dc719fc 100644
--- a/docs/dev-rules/credentials-and-local-storage.md
+++ b/docs/dev-rules/credentials-and-local-storage.md
@@ -170,6 +170,15 @@ Claude.ai 登录,也不得收集、存储或中转订阅凭证。Cindy 因此
提供给支持人员。复用本机日志目录入口,不自动上传。旧响应适配器可省略 headers,
旧 IPC 消费者可忽略 retryAt;Mobile 暂不增加等待时间界面。
+### 运行时会话续期退避
+
+Desktop 的运行时 refresh 遇到瞬时失败后,主动调用与定时重试共用至少 60 秒的等待;
+429 的有效 `Retry-After` 更长时按服务器等待时间执行。等待期间的调用不发请求、不延长
+原期限,也不清除凭证。成功续期/登录清除等待,登录代次改变后旧等待不约束新账号。
+冷启动、确定性失效和同机 token 替换恢复继续沿用原有判定。状态只留在进程内存中。
+实现见 `main/authRefreshBackoff.ts`、`main/authManager.ts`;回归见
+`main/__tests__/authRefreshBackoff.test.ts`。
+
## 路径与生命周期
| 数据性质 | 正确位置 |
diff --git a/docs/product-rules/bot-group-chat.md b/docs/product-rules/bot-group-chat.md
index 60405a6e8b..6fa613591e 100644
--- a/docs/product-rules/bot-group-chat.md
+++ b/docs/product-rules/bot-group-chat.md
@@ -305,6 +305,19 @@ Chris 已明确扩展到多人各带伙伴,并选择「主人按群预先授
当前本地验收与正式切源边界见 [Chat Server 本地联调](../dev-rules/chat-server-local-test.md)。
+Desktop 群聊只对 `TOKEN_EXPIRED`、`INVALID_TOKEN`、`AUTH_REQUIRED` 的 401 尝试一次
+续期后重发,并发失败共用同一次续期;已有更新 token 时直接重发。持续 401 即使续期
+成功也至少等待 60 秒再尝试刷新,不能让两秒任务轮询反复轮换 Auth token。后台轮询
+在 401/429 后等待至少 60 秒,429 遵守更长的 `Retry-After`;服务暂时不可用时逐步
+退避到最多 60 秒,成功后恢复正常轮询。换账号后使用独立的恢复状态,旧请求不重发。
+已完成回复遇到可恢复的 401(含无法解析的上游响应)或 429 时保留待提交结果,遵守
+至少 60 秒及服务器更长的等待,使用同一 `operationId` 和结果内容重试,不重跑伙伴。
+准备结果以及认证/限流等待期间继续按既有心跳续租,由服务器检查当前授权与租约;
+心跳明确拒绝时立即释放旧执行,不能占住伙伴直到等待结束。普通网络丢失响应仍使用
+原提交回执重试,不插入心跳。租约确实过期时接受最终拒绝,不更换执行身份来提交旧结果。
+账号不可用、权限撤回或执行租约失效等明确拒绝仍停止提交,换账号后不重发旧结果。
+回归见 `main/maker-ipc/__tests__/chatServer.test.ts`。
+
### Desktop 群邀请深链续接
群邀请沿用创建接口生成的 `cindy://chat-invite/<token>`,由主进程校验并暂存目标。
diff --git a/packages/auth-client/src/client.ts b/packages/auth-client/src/client.ts
index 6c0fa254d2..179e4c5de1 100644
--- a/packages/auth-client/src/client.ts
+++ b/packages/auth-client/src/client.ts
@@ -73,7 +73,7 @@ export class AuthApiError extends Error {
}
/** Accept Retry-After seconds or HTTP-date; never invent a cooldown. */
-function retryAfterDeadline(response: AuthFetchResponse): number | undefined {
+export function retryAfterDeadline(response: Pick<AuthFetchResponse, "headers">): number | undefined {
const value = response.headers?.get("retry-after")?.trim();
if (!value) return undefined;
const now = Date.now();
diff --git a/packages/auth-client/src/index.ts b/packages/auth-client/src/index.ts
index 46e8c21da5..6292aeeb4d 100644
--- a/packages/auth-client/src/index.ts
+++ b/packages/auth-client/src/index.ts
@@ -1,4 +1,4 @@
-export { AuthApiError, CindyAuthClient } from "./client.js";
+export { AuthApiError, CindyAuthClient, retryAfterDeadline } from "./client.js";
export {
accountVaultKey,
isStoredAccountMetadata,