Strengthen the auth-store queue regression and clarify comments

Replace the dual-save case that stayed green without the queue with a
50-way same-process burst that needs fresh lock deadlines, and document
the queue plus defensive temp-counter in the store header.

Author: TheGreatAxios

src/auth/store.test.ts

@@ -114,49 +114,48 @@ describe("createAuthStore", () => {
     }
   });
 
-  test("queues same-process profile writes so neither save is lost", async () => {
-    const home = await mkdtemp(join(tmpdir(), "oauth-store-same-process-"));
+  test("keeps a same-process burst of profile saves without shared-deadline loss", async () => {
+    const home = await mkdtemp(join(tmpdir(), "oauth-store-burst-"));
     try {
       const store = createAuthStore<TestTokens>({
         filename: "test-auth.json",
         settingsDirName: TEST_SETTINGS_DIR,
         isTokens: isTestTokens,
       });
 
-      await Promise.all([
-        store.saveProfile(
-          {
-            name: "personal",
-            tokens: { access: "p", refresh: "pr", expiresAt: 1 },
-            createdAt: 1,
-          },
-          home,
-        ),
-        store.saveProfile(
-          {
-            name: "work",
-            tokens: { access: "w", refresh: "wr", expiresAt: 2 },
-            createdAt: 2,
-          },
-          home,
+      // Without the per-path queue, a large same-process burst shares one lock
+      // deadline from invoke time and some waiters time out. With the queue,
+      // each save gets its own window and all land.
+      const names = Array.from(
+        { length: 50 },
+        (_, index) => `profile-${String(index)}`,
+      );
+      const results = await Promise.allSettled(
+        names.map((name) =>
+          store.saveProfile(
+            {
+              name,
+              tokens: {
+                access: `access-${name}`,
+                refresh: `refresh-${name}`,
+                expiresAt: 1,
+              },
+              createdAt: 1,
+            },
+            home,
+          ),
         ),
-      ]);
+      );
 
-      const profiles = await store.listProfiles(home);
-      expect(profiles.map((profile) => profile.name)).toEqual([
-        "personal",
-        "work",
-      ]);
-      expect(profiles.find((profile) => profile.name === "personal")).toEqual({
-        name: "personal",
-        tokens: { access: "p", refresh: "pr", expiresAt: 1 },
-        createdAt: 1,
-      });
-      expect(profiles.find((profile) => profile.name === "work")).toEqual({
-        name: "work",
-        tokens: { access: "w", refresh: "wr", expiresAt: 2 },
-        createdAt: 2,
-      });
+      const failures = results.flatMap((result, index) =>
+        result.status === "rejected"
+          ? [`${names[index]}: ${String(result.reason)}`]
+          : [],
+      );
+      expect(failures).toEqual([]);
+      expect((await store.listProfiles(home)).map((profile) => profile.name)).toEqual(
+        [...names].sort(),
+      );
     } finally {
       await rm(home, { recursive: true, force: true });
     }
@@ -181,6 +180,8 @@ describe("createAuthStore", () => {
 
       // Hold the lock until the head of the same-process queue times out; the
       // queued write must still get its own lock window after we release.
+      // `second` may already be polling when `first` rejects — release must land
+      // inside LOCK_TIMEOUT_MS of that handoff.
       const lockPath = `${store.authPath(home)}.lock`;
       await writeFile(lockPath, "foreign", { mode: 0o600 });
 

src/auth/store.ts

@@ -18,7 +18,8 @@ export type { AuthProfile, BaseTokens };
 // for the same provider, so credentials are keyed by a user-chosen profile name
 // within a single file. Tokens are credentials, so the file is owner-only (0o600)
 // and the directory 0o700. Writes go through a temp file + rename so a concurrent
-// reader never observes a torn file.
+// reader never observes a torn file. Same-process writers also queue per auth path
+// so each lock wait starts its own deadline.
 
 export interface AuthStore<TTokens extends BaseTokens> {
   authPath: (home?: string) => string;
@@ -48,8 +49,8 @@ interface AuthFile<TTokens extends BaseTokens> {
 const LOCK_RETRY_MS = 25;
 const LOCK_TIMEOUT_MS = 1_000;
 
-// pid alone is not unique per call — concurrent saves in one process must not
-// share a temp path or the second rename hits ENOENT after the first moves it.
+// Per-call unique temp (pid + counter). Matches mcp/auth-store — pid alone is not
+// unique per call if writeAuthFile ever overlaps in-process.
 let tmpWriteCounter = 0;
 
 // Same-process ops on one auth file queue here so a caller's lock deadline