@acosmi/sdk-ts 1.0.1 → 1.0.2

package/dist/node/index.d.cts

@@ -122,11 +122,17 @@ declare function skillScopes(): string[];
  *   - Save: 写入持久化, 失败抛 Error
  *   - Load: 读取, 不存在返回 null (与 Go IsNotExist 行为一致)
  *   - Clear: 删除, 不存在不抛错 (Logout 后 Clear 不应报错, [RC-11])
+ *   - withLock (v1.0.2 新增, 可选): 跨进程临界区. Client 在 refresh token rotation
+ *     场景下用此包裹 "load → check → refresh → save" 整段, 防多进程共享同一 store
+ *     (典型: FileTokenStore 默认 ~/.acosmi/tokens.json) 撞 HTTP 400 refresh token
+ *     not found. 不实现时 Client 自动回退到仅进程内串行 (LocalStorage / InMemory
+ *     单进程语义无需此方法).
  */
 interface TokenStore {
     save(tokens: TokenSet): Promise<void>;
     load(): Promise<TokenSet | null>;
     clear(): Promise<void>;
+    withLock?<T>(fn: () => Promise<T>): Promise<T>;
 }
 /**
  * 基于文件的 token 存储 (开发/测试用)
@@ -136,13 +142,46 @@ interface TokenStore {
  *
  * 浏览器环境调用 new FileTokenStore() 会抛错 — 浏览器请用 LocalStorageTokenStore 或 InMemoryTokenStore.
  */
+/** 跨进程文件锁配置 (v1.0.2). 公开常量是为了让 caller / 测试可观察, 不建议生产代码改. */
+declare const fileLockDefaults: {
+    /** 获取锁的超时上限 (毫秒). refresh 流程含网络 < 30s, 30s 已远超正常完成时间. */
+    readonly acquireTimeoutMs: 30000;
+    /** 旧锁判定阈值 (毫秒). 锁文件 mtime 早于此值视为 stale 进程崩溃残留, 自动 break. */
+    readonly staleMs: 60000;
+    /** 重试间隔基数 (毫秒). 真实间隔 = base + random(0, jitter). */
+    readonly retryBaseMs: 30;
+    readonly retryJitterMs: 70;
+};
 declare class FileTokenStore implements TokenStore {
     private path;
-    /** 简单串行化锁 (替代 Go sync.Mutex) */
+    /** 进程内串行化 (Promise chain) — 与跨进程 flock 配合, 避免单进程内并发持锁产生死锁式互等. */
     private chain;
     constructor(path?: string);
     private resolvePath;
-    private withLock;
+    /** 进程内串行 (维持 v1.0.1 单进程语义). flock 之外另一层防御: 如果用户自己就是单进程
+     *  并发场景, 不必每次都进 flock 旁路文件 IO. */
+    private withChain;
+    /**
+     * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
+     *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
+     *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
+     *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
+     *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
+     *
+     * 注意: O_EXCL 在 NFS 上不保证原子; FileTokenStore 适用于本地文件系统 (典型用户家目录).
+     * 真要跨机共享 token, 应实现自定义 Keychain / 数据库 store, 不要用 FileTokenStore.
+     */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 写入 token. 流程:
+     *   1. mkdir -p (默认路径目录)
+     *   2. 写入 `<path>.tmp.<pid>`
+     *   3. fsync 后 rename 到正式路径 (POSIX 上 rename(2) 同分区原子, Windows 上 ReplaceFile)
+     *
+     * 选择 atomic rename 而非直接 writeFile: 多进程并发或本进程崩溃时, 读端永远看到的是
+     * 完整的旧/新 JSON, 不会读到截断半文件 (Client.create.store.load 可能在另一进程
+     * 写入中间触发, atomic rename 避免它解析失败).
+     */
     save(tokens: TokenSet): Promise<void>;
     load(): Promise<TokenSet | null>;
     clear(): Promise<void>;
@@ -391,6 +430,12 @@ declare class Client {
     forceRefresh(signal?: AbortSignal): Promise<void>;
     /** 互斥锁 helper (替代 Go sync.Mutex) */
     private withMu;
+    /** v1.0.2: 跨进程临界区 helper. store.withLock 可选, 缺省则直接调用 fn (LocalStorage /
+     *  InMemory 单进程无需). */
+    private storeWithLock;
+    /** v1.0.2: 从磁盘同步 token (refresh 前). 别的进程 rotation 后磁盘 refresh_token 已变,
+     *  本进程内存仍是旧 R0; 不同步直接 refresh 必撞网关 400. load 失败保留内存继续 (容错). */
+    private syncFromDisk;
     /**
      * 获取可用的托管模型列表.
      *
@@ -788,4 +833,4 @@ declare module '@acosmi/sdk-ts' {
     }
 }
 
-export { AnthropicResponse, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type Config, ConsumeRecordPage, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, QuotaSummary, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerMetadata, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, isSSLError, modelScopes, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };
+export { AnthropicResponse, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type Config, ConsumeRecordPage, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, QuotaSummary, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerMetadata, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, isSSLError, modelScopes, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };

package/dist/node/index.d.ts

@@ -122,11 +122,17 @@ declare function skillScopes(): string[];
  *   - Save: 写入持久化, 失败抛 Error
  *   - Load: 读取, 不存在返回 null (与 Go IsNotExist 行为一致)
  *   - Clear: 删除, 不存在不抛错 (Logout 后 Clear 不应报错, [RC-11])
+ *   - withLock (v1.0.2 新增, 可选): 跨进程临界区. Client 在 refresh token rotation
+ *     场景下用此包裹 "load → check → refresh → save" 整段, 防多进程共享同一 store
+ *     (典型: FileTokenStore 默认 ~/.acosmi/tokens.json) 撞 HTTP 400 refresh token
+ *     not found. 不实现时 Client 自动回退到仅进程内串行 (LocalStorage / InMemory
+ *     单进程语义无需此方法).
  */
 interface TokenStore {
     save(tokens: TokenSet): Promise<void>;
     load(): Promise<TokenSet | null>;
     clear(): Promise<void>;
+    withLock?<T>(fn: () => Promise<T>): Promise<T>;
 }
 /**
  * 基于文件的 token 存储 (开发/测试用)
@@ -136,13 +142,46 @@ interface TokenStore {
  *
  * 浏览器环境调用 new FileTokenStore() 会抛错 — 浏览器请用 LocalStorageTokenStore 或 InMemoryTokenStore.
  */
+/** 跨进程文件锁配置 (v1.0.2). 公开常量是为了让 caller / 测试可观察, 不建议生产代码改. */
+declare const fileLockDefaults: {
+    /** 获取锁的超时上限 (毫秒). refresh 流程含网络 < 30s, 30s 已远超正常完成时间. */
+    readonly acquireTimeoutMs: 30000;
+    /** 旧锁判定阈值 (毫秒). 锁文件 mtime 早于此值视为 stale 进程崩溃残留, 自动 break. */
+    readonly staleMs: 60000;
+    /** 重试间隔基数 (毫秒). 真实间隔 = base + random(0, jitter). */
+    readonly retryBaseMs: 30;
+    readonly retryJitterMs: 70;
+};
 declare class FileTokenStore implements TokenStore {
     private path;
-    /** 简单串行化锁 (替代 Go sync.Mutex) */
+    /** 进程内串行化 (Promise chain) — 与跨进程 flock 配合, 避免单进程内并发持锁产生死锁式互等. */
     private chain;
     constructor(path?: string);
     private resolvePath;
-    private withLock;
+    /** 进程内串行 (维持 v1.0.1 单进程语义). flock 之外另一层防御: 如果用户自己就是单进程
+     *  并发场景, 不必每次都进 flock 旁路文件 IO. */
+    private withChain;
+    /**
+     * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
+     *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
+     *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
+     *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
+     *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
+     *
+     * 注意: O_EXCL 在 NFS 上不保证原子; FileTokenStore 适用于本地文件系统 (典型用户家目录).
+     * 真要跨机共享 token, 应实现自定义 Keychain / 数据库 store, 不要用 FileTokenStore.
+     */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 写入 token. 流程:
+     *   1. mkdir -p (默认路径目录)
+     *   2. 写入 `<path>.tmp.<pid>`
+     *   3. fsync 后 rename 到正式路径 (POSIX 上 rename(2) 同分区原子, Windows 上 ReplaceFile)
+     *
+     * 选择 atomic rename 而非直接 writeFile: 多进程并发或本进程崩溃时, 读端永远看到的是
+     * 完整的旧/新 JSON, 不会读到截断半文件 (Client.create.store.load 可能在另一进程
+     * 写入中间触发, atomic rename 避免它解析失败).
+     */
     save(tokens: TokenSet): Promise<void>;
     load(): Promise<TokenSet | null>;
     clear(): Promise<void>;
@@ -391,6 +430,12 @@ declare class Client {
     forceRefresh(signal?: AbortSignal): Promise<void>;
     /** 互斥锁 helper (替代 Go sync.Mutex) */
     private withMu;
+    /** v1.0.2: 跨进程临界区 helper. store.withLock 可选, 缺省则直接调用 fn (LocalStorage /
+     *  InMemory 单进程无需). */
+    private storeWithLock;
+    /** v1.0.2: 从磁盘同步 token (refresh 前). 别的进程 rotation 后磁盘 refresh_token 已变,
+     *  本进程内存仍是旧 R0; 不同步直接 refresh 必撞网关 400. load 失败保留内存继续 (容错). */
+    private syncFromDisk;
     /**
      * 获取可用的托管模型列表.
      *
@@ -788,4 +833,4 @@ declare module '@acosmi/sdk-ts' {
     }
 }
 
-export { AnthropicResponse, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type Config, ConsumeRecordPage, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, QuotaSummary, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerMetadata, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, isSSLError, modelScopes, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };
+export { AnthropicResponse, type AuthorizeResult, BalanceDetail, type BlockMeta, type BugReportResult, type BugView, CertificationStatus, ChatRequest, ChatResponse, Client, ClientRegistration, type Config, ConsumeRecordPage, DefaultRetryPolicy, DeviceRegistration, EntitlementBalance, EntitlementItem, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, type FilterStatus, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, GenerateSkillRequest, GenerateSkillResult, InMemoryTokenStore, LocalStorageTokenStore, type LoginErrCode, type LoginEvent, type LoginEventType, type LoginOptions, ManagedModel, ModelBucket, ModelByQuotaResponse, ModelCapabilities, ModelCoefficient, NotificationList, NotificationPreference, OptimizeSkillRequest, OptimizeSkillResult, Order, OrderStatus, PayPayload, ProviderAdapter, QuotaSummary, type RetryPolicy, type RetryRequestInfo, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerMetadata, SkillBrowseListResponse, SkillBrowseResponse, SkillStoreItem, SkillStoreQuery, SkillSummary, SourcesEvent, StreamEvent, StreamSettlement, TokenPackage, TokenResponse, TokenSet, type TokenStore, ToolView, Transaction, type WSConfig, WSEvent, WalletStats, allScopes, authorize, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, isSSLError, modelScopes, newFileTokenStore, newTokenSet, refreshToken, register, revokeToken, skillScopes, uniqueMerge };

package/dist/node/index.mjs

@@ -1403,9 +1403,18 @@ function skillScopes() {
 }
 
 // src/store.ts
+var fileLockDefaults = {
+  /** 获取锁的超时上限 (毫秒). refresh 流程含网络 < 30s, 30s 已远超正常完成时间. */
+  acquireTimeoutMs: 3e4,
+  /** 旧锁判定阈值 (毫秒). 锁文件 mtime 早于此值视为 stale 进程崩溃残留, 自动 break. */
+  staleMs: 6e4,
+  /** 重试间隔基数 (毫秒). 真实间隔 = base + random(0, jitter). */
+  retryBaseMs: 30,
+  retryJitterMs: 70
+};
 var FileTokenStore = class {
   path;
-  /** 简单串行化锁 (替代 Go sync.Mutex) */
+  /** 进程内串行化 (Promise chain) — 与跨进程 flock 配合, 避免单进程内并发持锁产生死锁式互等. */
   chain = Promise.resolve();
   constructor(path) {
     if (typeof process === "undefined" || !process.versions || !process.versions.node) {
@@ -1424,7 +1433,9 @@ var FileTokenStore = class {
     this.path = path.join(os.homedir(), ".acosmi", "tokens.json");
     return this.path;
   }
-  withLock(fn) {
+  /** 进程内串行 (维持 v1.0.1 单进程语义). flock 之外另一层防御: 如果用户自己就是单进程
+   *  并发场景, 不必每次都进 flock 旁路文件 IO. */
+  withChain(fn) {
     const next = this.chain.then(fn, fn);
     this.chain = next.then(
       () => void 0,
@@ -1432,19 +1443,106 @@ var FileTokenStore = class {
     );
     return next;
   }
+  /**
+   * 跨进程临界区. 用 sidecar `<path>.lock` 文件 + O_EXCL 创建语义实现互斥:
+   *   - 创建成功 = 持有锁; 写入 pid+timestamp 便于诊断
+   *   - 创建失败 (EEXIST) = 别的进程持锁, backoff 重试
+   *   - 锁文件 mtime > staleMs = 进程崩溃残留, unlink 后重试
+   *   - acquireTimeoutMs 超时 = 抛错 (caller 应作为 transient error 处理, 上层 retry)
+   *
+   * 注意: O_EXCL 在 NFS 上不保证原子; FileTokenStore 适用于本地文件系统 (典型用户家目录).
+   * 真要跨机共享 token, 应实现自定义 Keychain / 数据库 store, 不要用 FileTokenStore.
+   */
+  async withLock(fn) {
+    const fs = await import('fs/promises');
+    const pathMod = await import('path');
+    const p = await this.resolvePath();
+    const lockPath = `${p}.lock`;
+    const dir = pathMod.dirname(p);
+    await fs.mkdir(dir, { recursive: true, mode: 448 });
+    const startMs = Date.now();
+    let release = null;
+    while (true) {
+      try {
+        const fh = await fs.open(lockPath, "wx", 384);
+        try {
+          await fh.writeFile(`${process.pid}
+${Date.now()}
+`, "utf8");
+        } finally {
+          await fh.close();
+        }
+        release = async () => {
+          try {
+            await fs.unlink(lockPath);
+          } catch {
+          }
+        };
+        break;
+      } catch (e) {
+        if (!isAlreadyExistsError(e)) throw e;
+        let stale = false;
+        try {
+          const st = await fs.stat(lockPath);
+          if (Date.now() - st.mtimeMs > fileLockDefaults.staleMs) stale = true;
+        } catch {
+          continue;
+        }
+        if (stale) {
+          try {
+            await fs.unlink(lockPath);
+          } catch {
+          }
+          continue;
+        }
+        if (Date.now() - startMs > fileLockDefaults.acquireTimeoutMs) {
+          throw new Error(
+            `acquire token file lock timeout (${fileLockDefaults.acquireTimeoutMs}ms): ${lockPath}`
+          );
+        }
+        const waitMs = fileLockDefaults.retryBaseMs + Math.random() * fileLockDefaults.retryJitterMs;
+        await new Promise((r) => setTimeout(r, waitMs));
+      }
+    }
+    try {
+      return await fn();
+    } finally {
+      if (release) await release();
+    }
+  }
+  /**
+   * 写入 token. 流程:
+   *   1. mkdir -p (默认路径目录)
+   *   2. 写入 `<path>.tmp.<pid>`
+   *   3. fsync 后 rename 到正式路径 (POSIX 上 rename(2) 同分区原子, Windows 上 ReplaceFile)
+   *
+   * 选择 atomic rename 而非直接 writeFile: 多进程并发或本进程崩溃时, 读端永远看到的是
+   * 完整的旧/新 JSON, 不会读到截断半文件 (Client.create.store.load 可能在另一进程
+   * 写入中间触发, atomic rename 避免它解析失败).
+   */
   save(tokens) {
-    return this.withLock(async () => {
+    return this.withChain(async () => {
       const fs = await import('fs/promises');
-      const path = await import('path');
+      const pathMod = await import('path');
       const p = await this.resolvePath();
-      const dir = path.dirname(p);
+      const dir = pathMod.dirname(p);
       await fs.mkdir(dir, { recursive: true, mode: 448 });
+      const tmp = `${p}.tmp.${process.pid}.${Date.now()}.${Math.floor(Math.random() * 1e6)}`;
       const data = JSON.stringify(tokens, null, 2);
-      await fs.writeFile(p, data, { encoding: "utf8", mode: 384 });
+      await fs.writeFile(tmp, data, { encoding: "utf8", mode: 384 });
+      try {
+        await fs.rename(tmp, p);
+      } catch (e) {
+        try {
+          await fs.unlink(tmp);
+        } catch {
+        }
+        throw e;
+      }
     });
   }
   load() {
-    return this.withLock(async () => {
+    return this.withChain(async () => {
       const fs = await import('fs/promises');
       const p = await this.resolvePath();
       try {
@@ -1459,7 +1557,7 @@ var FileTokenStore = class {
     });
   }
   clear() {
-    return this.withLock(async () => {
+    return this.withChain(async () => {
       const fs = await import('fs/promises');
       const p = await this.resolvePath();
       try {
@@ -1477,6 +1575,12 @@ function isNotExistError(e) {
   }
   return false;
 }
+function isAlreadyExistsError(e) {
+  if (typeof e === "object" && e !== null && "code" in e) {
+    return e.code === "EEXIST";
+  }
+  return false;
+}
 function newFileTokenStore(path) {
   return new FileTokenStore(path);
 }
@@ -2343,61 +2447,67 @@ var Client = class _Client {
     if (!tokenSetIsExpired(tokens)) {
       return tokens.access_token;
     }
-    return this.withMu(async () => {
-      if (this.tokens == null) {
-        throw new Error("not authorized, call login() first");
-      }
-      if (!tokenSetIsExpired(this.tokens)) {
-        return this.tokens.access_token;
-      }
-      if (this.meta == null) {
+    return this.withMu(
+      () => this.storeWithLock(async () => {
+        await this.syncFromDisk();
+        if (this.tokens == null) {
+          throw new Error("not authorized, call login() first");
+        }
+        if (!tokenSetIsExpired(this.tokens)) {
+          return this.tokens.access_token;
+        }
+        if (this.meta == null) {
+          try {
+            this.meta = await discover(this.serverURL, signal);
+          } catch (e) {
+            throw new Error(
+              `discover for refresh: ${e instanceof Error ? e.message : String(e)}`
+            );
+          }
+        }
+        let tokenResp;
         try {
-          this.meta = await discover(this.serverURL, signal);
+          tokenResp = await refreshToken(this.meta, this.tokens.client_id, this.tokens.refresh_token, signal);
         } catch (e) {
-          throw new Error(
-            `discover for refresh: ${e instanceof Error ? e.message : String(e)}`
-          );
+          throw new Error(`refresh token: ${e instanceof Error ? e.message : String(e)}`);
         }
-      }
-      let tokenResp;
-      try {
-        tokenResp = await refreshToken(this.meta, this.tokens.client_id, this.tokens.refresh_token, signal);
-      } catch (e) {
-        throw new Error(`refresh token: ${e instanceof Error ? e.message : String(e)}`);
-      }
-      this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
-      try {
-        await this.store.save(this.tokens);
-      } catch (e) {
-        console.warn(`[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`);
-      }
-      return this.tokens.access_token;
-    });
+        this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
+        try {
+          await this.store.save(this.tokens);
+        } catch (e) {
+          console.warn(`[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return this.tokens.access_token;
+      })
+    );
   }
   /** 强制刷新 token (用于 401 重试) */
   async forceRefresh(signal) {
-    return this.withMu(async () => {
-      if (this.tokens == null) {
-        throw new Error("no tokens to refresh");
-      }
-      if (this.meta == null) {
-        this.meta = await discover(this.serverURL, signal);
-      }
-      const tokenResp = await refreshToken(
-        this.meta,
-        this.tokens.client_id,
-        this.tokens.refresh_token,
-        signal
-      );
-      this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
-      try {
-        await this.store.save(this.tokens);
-      } catch (e) {
-        console.warn(
-          `[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`
+    return this.withMu(
+      () => this.storeWithLock(async () => {
+        await this.syncFromDisk();
+        if (this.tokens == null) {
+          throw new Error("no tokens to refresh");
+        }
+        if (this.meta == null) {
+          this.meta = await discover(this.serverURL, signal);
+        }
+        const tokenResp = await refreshToken(
+          this.meta,
+          this.tokens.client_id,
+          this.tokens.refresh_token,
+          signal
         );
-      }
-    });
+        this.tokens = newTokenSet(tokenResp, this.tokens.client_id, this.serverURL);
+        try {
+          await this.store.save(this.tokens);
+        } catch (e) {
+          console.warn(
+            `[acosmi-sdk] warning: save refreshed token failed: ${e instanceof Error ? e.message : String(e)}`
+          );
+        }
+      })
+    );
   }
   /** 互斥锁 helper (替代 Go sync.Mutex) */
   withMu(fn) {
@@ -2408,6 +2518,29 @@ var Client = class _Client {
     );
     return next;
   }
+  /** v1.0.2: 跨进程临界区 helper. store.withLock 可选, 缺省则直接调用 fn (LocalStorage /
+   *  InMemory 单进程无需). */
+  async storeWithLock(fn) {
+    const lock = this.store.withLock;
+    if (typeof lock === "function") {
+      return lock.call(this.store, fn);
+    }
+    return fn();
+  }
+  /** v1.0.2: 从磁盘同步 token (refresh 前). 别的进程 rotation 后磁盘 refresh_token 已变,
+   *  本进程内存仍是旧 R0; 不同步直接 refresh 必撞网关 400. load 失败保留内存继续 (容错). */
+  async syncFromDisk() {
+    let onDisk = null;
+    try {
+      onDisk = await this.store.load();
+    } catch {
+      return;
+    }
+    if (!onDisk) return;
+    if (this.tokens == null || onDisk.refresh_token !== this.tokens.refresh_token) {
+      this.tokens = onDisk;
+    }
+  }
   // ===========================================================================
   // Managed Models
   // ===========================================================================
@@ -3945,6 +4078,6 @@ Client.prototype.getBugReport = async function(bugID, signal) {
   return resp.data;
 };
 
-export { AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, DefaultRetryPolicy, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, getAdapter, getAdapterForModel, isSSLError, modelScopes, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
+export { AnthropicAdapter, BucketClassCommercial, BucketClassGeneric, BusinessError, Client, DefaultRetryPolicy, ErrAuthDenied, ErrBrowserOpen, ErrDiscovery, ErrRegistration, ErrSSLProxy, ErrTimeout, ErrTokenExchange, EventAuthURL, EventComplete, EventError, FileTokenStore, FilterStatusAdminBypass, FilterStatusDisabledByFlag, FilterStatusFallbackMissingUser, FilterStatusFallbackNoBuckets, FilterStatusFallbackTkdistError, FilterStatusFallbackTkdistSkew, FilterStatusInternalBypass, FilterStatusOK, FilterStatusUnknown, HTTPError, InMemoryTokenStore, LocalStorageTokenStore, ModelNotFoundError, NetworkError, OpenAIAdapter, OrderTerminalError, ProviderFormat, RateLimitError, ScopeAI, ScopeAccount, ScopeEntitlements, ScopeModels, ScopeModelsChat, ScopeProfile, ScopeSkillStore, ScopeSkills, ScopeTokenPackages, ScopeTools, ScopeToolsExecute, ScopeWallet, ScopeWalletReadonly, ServerToolTypeWebSearch, StreamError, ThinkingHigh, ThinkingHighMinMaxTokens, ThinkingMax, ThinkingMaxFallbackMaxTokens, ThinkingOff, allScopes, anthropicResponseTextContent, anthropicResponseThinkingContent, anthropicResponseToolUseBlocks, apiResponseBusinessError, apiResponseGetMessage, authorize, bucketInfoIsCommercial, bucketRowIsCommercial, buildBetas, commerceScopes, computeBackoff, defaultRetryable, defaultSafeToRetry, discover, effectivePolicy, exchangeCode, extractAnthropicBlockMeta, fileLockDefaults, getAdapter, getAdapterForModel, isSSLError, modelScopes, newFileTokenStore, newThinkingConfig, newTokenSet, newWebSearchTool, parseNotificationEvent, parseSettlement, parseSourcesEvent, refreshToken, register, revokeToken, sanitize_exports as sanitize, skillScopes, tokenSetIsExpired, uniqueMerge };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map