fix(auth): coordinate OAuth refresh across concurrent codebase processes

Users running multiple codebase instances simultaneously (5-10 at once
isn't unusual when juggling several agents) hit a real failure mode:
when two processes detect token expiry at the same moment, each fires
its own refresh request with the shared refresh_token. Most OAuth
backends rotate refresh tokens on each use, so the second call returns
"refresh token already used" and that process gets logged out — even
though everything looked fine on its end.

Wrap the refresh path in a proper-lockfile-coordinated critical section
on the credentials directory: at most one process holds the lock at a
time, and after acquiring it we re-read the credentials file before
deciding to refresh. The first process refreshes + saves; the others
acquire the lock, see fresh tokens on disk, and skip the refresh
entirely. In-memory single-flight remains for within-process collapse.

Also bumps the refresh-skew buffer from 60s to 5 min so the request
never travels under a near-expired token under clock skew + slow
refresh latency.

Author: halfaipg

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.40",
+	"version": "2.0.0-pre.41",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",
@@ -62,10 +62,12 @@
 		"@earendil-works/pi-agent-core": "0.74.0",
 		"@earendil-works/pi-ai": "0.74.0",
 		"@types/diff": "^7.0.2",
+		"@types/proper-lockfile": "^4.1.4",
 		"diff": "^9.0.0",
 		"glob": "^13.0.1",
 		"ignore": "^7.0.0",
 		"ink": "^5.2.1",
+		"proper-lockfile": "^4.1.2",
 		"react": "^18.3.1",
 		"typebox": "^1.1.24"
 	},

package.json

@@ -138,3 +138,62 @@ describe("TokenManager", () => {
 		expect(fetchSpy).not.toHaveBeenCalled();
 	});
 });
+
+describe("TokenManager — multi-process coordination", () => {
+	let dataRoot: string;
+
+	beforeEach(() => {
+		dataRoot = mkdtempSync(join(tmpdir(), "tm-mp-"));
+	});
+
+	afterEach(() => {
+		rmSync(dataRoot, { recursive: true, force: true });
+		vi.restoreAllMocks();
+	});
+
+	it("two TokenManagers refreshing concurrently produce only one refresh round-trip", async () => {
+		const storeA = new CredentialsStore({ dataRoot });
+		const storeB = new CredentialsStore({ dataRoot });
+		storeA.save(freshCreds({ expiresAt: Date.now() + 5_000 }));
+		const fetchSpy = vi.spyOn(globalThis, "fetch").mockImplementation(
+			() =>
+				new Promise((resolve) => {
+					setTimeout(
+						() =>
+							resolve(
+								new Response(JSON.stringify({ access_token: "access-NEW", expires_in: 3600 }), {
+									status: 200,
+									headers: { "Content-Type": "application/json" },
+								}),
+							),
+						50,
+					);
+				}),
+		);
+		const tmA = new TokenManager({ store: storeA, oauthConfig: OAUTH });
+		const tmB = new TokenManager({ store: storeB, oauthConfig: OAUTH });
+		const [a, b] = await Promise.all([tmA.getAccessToken(), tmB.getAccessToken()]);
+		expect(a).toBe("access-NEW");
+		expect(b).toBe("access-NEW");
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("a TokenManager started after another process refreshed reads the rotated token without refreshing", async () => {
+		const storeA = new CredentialsStore({ dataRoot });
+		storeA.save(freshCreds({ expiresAt: Date.now() + 5_000 }));
+		vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+			new Response(JSON.stringify({ access_token: "access-NEW", expires_in: 3600 }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			}),
+		);
+		const tmA = new TokenManager({ store: storeA, oauthConfig: OAUTH });
+		await tmA.getAccessToken();
+		// Now another process starts up with its own TokenManager.
+		const fetchSpyLate = vi.spyOn(globalThis, "fetch");
+		const storeB = new CredentialsStore({ dataRoot });
+		const tmB = new TokenManager({ store: storeB, oauthConfig: OAUTH });
+		await expect(tmB.getAccessToken()).resolves.toBe("access-NEW");
+		expect(fetchSpyLate).not.toHaveBeenCalled();
+	});
+});

src/auth/token-manager.test.ts

@@ -1,3 +1,6 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import * as lockfile from "proper-lockfile";
 import type { Credentials, CredentialsStore } from "./credentials.js";
 import { type OAuthConfig, refreshAccessToken } from "./flow.js";
 
@@ -6,32 +9,48 @@ export interface TokenManagerOptions {
 	oauthConfig: OAuthConfig;
 	/**
 	 * Refresh when the access token's remaining lifetime falls below this
-	 * many milliseconds. Default 60s — generous enough to ride out clock
-	 * skew + a slow refresh round-trip without ever sending an expired
-	 * token over the wire.
+	 * many milliseconds. Default 5 minutes — wide enough to absorb clock
+	 * skew, slow refresh round-trips, and a request that starts just under
+	 * the wire so it never travels with an already-expired token.
 	 */
 	refreshSkewMs?: number;
+	/**
+	 * Max time to wait acquiring the cross-process refresh lock before
+	 * giving up. If another `codebase` process is mid-refresh we wait;
+	 * if the lock is wedged (stale, crashed peer) we bail rather than
+	 * hang the user's request.
+	 */
+	lockTimeoutMs?: number;
 }
 
 /**
  * Read-through, refresh-aware accessor for the OAuth access token.
  *
- * Pi-mono's `getApiKey` runs on every API call, so we have to be fast in
- * the common case (token still valid). Slow path: refresh + persist before
- * returning the new token. A single in-flight promise (`pending`) prevents
- * a burst of concurrent calls from firing parallel refreshes at the same
- * moment — they all await the one refresh that's already running.
+ * Two coordination layers:
+ *   1. In-memory single-flight (`pending`) — multiple awaits within ONE
+ *      process collapse into one refresh round-trip.
+ *   2. Filesystem lockfile on the credentials directory — multiple
+ *      `codebase` processes on the same machine coordinate so only one
+ *      refreshes at a time. The others wait, re-read the rotated token,
+ *      and skip their own refresh. Necessary because refresh tokens are
+ *      often one-time-use: two parallel refreshes burn the shared refresh
+ *      token and one process gets logged out.
+ *
+ * Pi-mono's `getApiKey` runs on every API call, so the cached-token fast
+ * path stays branch-free; the slow path only fires near expiry.
  */
 export class TokenManager {
 	private readonly store: CredentialsStore;
 	private readonly oauthConfig: OAuthConfig;
 	private readonly refreshSkewMs: number;
+	private readonly lockTimeoutMs: number;
 	private pending: Promise<string> | null = null;
 
 	constructor(options: TokenManagerOptions) {
 		this.store = options.store;
 		this.oauthConfig = options.oauthConfig;
-		this.refreshSkewMs = options.refreshSkewMs ?? 60_000;
+		this.refreshSkewMs = options.refreshSkewMs ?? 5 * 60_000;
+		this.lockTimeoutMs = options.lockTimeoutMs ?? 30_000;
 	}
 
 	/**
@@ -47,39 +66,75 @@ export class TokenManager {
 		if (!creds.refreshToken) {
 			throw new Error("access token expired and no refresh token saved — run `codebase auth login`");
 		}
-		return this.refresh(creds.refreshToken);
+		return this.refresh();
 	}
 
 	private needsRefresh(creds: Credentials): boolean {
 		if (!creds.expiresAt) return false;
 		return creds.expiresAt - this.refreshSkewMs <= Date.now();
 	}
 
-	private refresh(refreshToken: string): Promise<string> {
+	private refresh(): Promise<string> {
 		if (this.pending) return this.pending;
 		this.pending = (async () => {
 			try {
-				const next = await refreshAccessToken(this.oauthConfig, refreshToken);
-				// Preserve fields the refresh response doesn't echo back (source,
-				// email, userId) so they survive every rotation. The refresh
-				// response is authoritative for tokens + expiry; we layer the
-				// stable metadata back on top.
-				const existing = this.store.load();
-				this.store.save({
-					accessToken: next.accessToken,
-					refreshToken: next.refreshToken ?? existing?.refreshToken ?? refreshToken,
-					expiresAt: next.expiresAt,
-					scopes: next.scopes,
-					source: existing?.source ?? next.source,
-					userId: existing?.userId ?? next.userId,
-					email: existing?.email ?? next.email,
-					provider: existing?.provider ?? next.provider,
-				});
-				return next.accessToken;
+				return await this.refreshWithLock();
 			} finally {
 				this.pending = null;
 			}
 		})();
 		return this.pending;
 	}
+
+	/**
+	 * Acquire a cross-process lock, then re-check (another process may have
+	 * already refreshed by the time we get the lock), then refresh + save.
+	 * The double-check is the whole point of taking the lock — it converts
+	 * N parallel refreshes into 1 refresh + N-1 reads of the fresh token.
+	 */
+	private async refreshWithLock(): Promise<string> {
+		const lockDir = dirname(this.store.filePath);
+		mkdirSync(lockDir, { recursive: true });
+		const release = await lockfile.lock(lockDir, {
+			retries: {
+				retries: Math.max(1, Math.ceil(this.lockTimeoutMs / 500)),
+				minTimeout: 250,
+				maxTimeout: 1000,
+				factor: 1.5,
+				randomize: true,
+			},
+			// 30s — stale-lock window. Survives a normal refresh; releases
+			// quickly enough that a crashed peer doesn't wedge us for long.
+			stale: 30_000,
+		});
+		try {
+			const reread = this.store.load();
+			if (reread && !this.needsRefresh(reread)) return reread.accessToken;
+			if (!reread?.refreshToken) {
+				throw new Error("access token expired and no refresh token saved — run `codebase auth login`");
+			}
+			const next = await refreshAccessToken(this.oauthConfig, reread.refreshToken);
+			// Preserve fields the refresh response doesn't echo back (source,
+			// email, userId) so they survive every rotation. The refresh
+			// response is authoritative for tokens + expiry; we layer the
+			// stable metadata back on top.
+			this.store.save({
+				accessToken: next.accessToken,
+				refreshToken: next.refreshToken ?? reread.refreshToken,
+				expiresAt: next.expiresAt,
+				scopes: next.scopes,
+				source: reread.source ?? next.source,
+				userId: reread.userId ?? next.userId,
+				email: reread.email ?? next.email,
+				provider: reread.provider ?? next.provider,
+			});
+			return next.accessToken;
+		} finally {
+			await release().catch(() => {
+				// Release can fail if the lock was stale-released by another
+				// process while we held it. The credentials are already saved
+				// at that point — there's nothing useful to do here.
+			});
+		}
+	}
 }