Skip to content

The open-source app everyone uses to manage agents at work

fix(codex-local): replace stale auth.json copy with symlink on prepare (#5028) (#5240)

Harshit Khemanic297ba2a80f2
diff --git a/packages/adapters/codex-local/src/server/codex-home.test.ts b/packages/adapters/codex-local/src/server/codex-home.test.ts
index 864837510b..840db45691 100644
--- a/packages/adapters/codex-local/src/server/codex-home.test.ts
+++ b/packages/adapters/codex-local/src/server/codex-home.test.ts
@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
-import { prepareManagedCodexHome } from "./codex-home.js";
+import { ensureSymlink, prepareManagedCodexHome } from "./codex-home.js";
describe("codex managed home", () => {
afterEach(() => {
@@ -54,4 +54,95 @@ describe("codex managed home", () => {
await fs.rm(root, { recursive: true, force: true });
}
});
+
+ // Regression for #5028: older Paperclip versions copied auth.json into the
+ // managed home instead of symlinking. After upgrading to the symlink-based
+ // logic, the stale regular file at the target stayed in place and every
+ // subsequent codex_local run failed with refresh_token_reused as soon as the
+ // source token rotated. `ensureSymlink` now heals the upgrade path by
+ // unlinking the stale copy and creating a symlink to the live source.
+ it("replaces a stale regular-file auth.json with a symlink to the live source (#5028)", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-home-"));
+ try {
+ const sharedCodexHome = path.join(root, "shared-codex-home");
+ const paperclipHome = path.join(root, "paperclip-home");
+ const managedCodexHome = path.join(
+ paperclipHome,
+ "instances",
+ "default",
+ "companies",
+ "company-1",
+ "codex-home",
+ );
+ const sharedAuth = path.join(sharedCodexHome, "auth.json");
+ const managedAuth = path.join(managedCodexHome, "auth.json");
+
+ await fs.mkdir(sharedCodexHome, { recursive: true });
+ // The live source has rotated since the stale copy was written.
+ await fs.writeFile(sharedAuth, '{"token":"fresh"}', "utf8");
+
+ // Simulate a stale copy left by a previous Paperclip version.
+ await fs.mkdir(managedCodexHome, { recursive: true });
+ await fs.writeFile(managedAuth, '{"token":"stale-from-copy"}', "utf8");
+
+ await prepareManagedCodexHome(
+ {
+ CODEX_HOME: sharedCodexHome,
+ PAPERCLIP_HOME: paperclipHome,
+ PAPERCLIP_INSTANCE_ID: "default",
+ },
+ async () => {},
+ "company-1",
+ );
+
+ expect((await fs.lstat(managedAuth)).isSymbolicLink()).toBe(true);
+ expect(await fs.readFile(managedAuth, "utf8")).toBe('{"token":"fresh"}');
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ // Direct unit coverage for the new ensureSymlink branch (#5028). The
+ // regression test above goes through prepareManagedCodexHome, whose
+ // pre-existing apikey-mode cleanup `fs.rm`s the stale auth.json before
+ // ensureSymlink runs — so the heal branch never executes there. Call
+ // ensureSymlink directly to prove the unlink-and-recreate path itself.
+ it("ensureSymlink: unlinks a stale regular file and recreates the symlink", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ensure-symlink-"));
+ try {
+ const source = path.join(root, "live-source.json");
+ const target = path.join(root, "stale-target.json");
+ await fs.writeFile(source, '{"token":"fresh"}', "utf8");
+ await fs.writeFile(target, '{"token":"stale-from-copy"}', "utf8");
+
+ await ensureSymlink(target, source);
+
+ expect((await fs.lstat(target)).isSymbolicLink()).toBe(true);
+ expect(await fs.readFile(target, "utf8")).toBe('{"token":"fresh"}');
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
+ // The isDirectory() guard added with the heal branch must keep an unexpected
+ // directory in place rather than throwing EISDIR. We treat a directory at
+ // this path as operator-owned, not a stale Paperclip copy.
+ it("ensureSymlink: leaves an unexpected directory in place instead of throwing", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ensure-symlink-dir-"));
+ try {
+ const source = path.join(root, "live-source.json");
+ const target = path.join(root, "unexpected-dir");
+ await fs.writeFile(source, '{"token":"fresh"}', "utf8");
+ await fs.mkdir(target);
+ await fs.writeFile(path.join(target, "sentinel"), "keep-me", "utf8");
+
+ await expect(ensureSymlink(target, source)).resolves.toBeUndefined();
+
+ expect((await fs.lstat(target)).isDirectory()).toBe(true);
+ expect(await fs.readFile(path.join(target, "sentinel"), "utf8")).toBe("keep-me");
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
+
});
diff --git a/packages/adapters/codex-local/src/server/codex-home.ts b/packages/adapters/codex-local/src/server/codex-home.ts
index ee87e6cbf5..bd9d4c02e3 100644
--- a/packages/adapters/codex-local/src/server/codex-home.ts
+++ b/packages/adapters/codex-local/src/server/codex-home.ts
@@ -65,7 +65,7 @@ async function createExpectedSymlink(target: string, source: string): Promise<vo
}
}
-async function ensureSymlink(target: string, source: string): Promise<void> {
+export async function ensureSymlink(target: string, source: string): Promise<void> {
const existing = await fs.lstat(target).catch(() => null);
if (!existing) {
await ensureParentDir(target);
@@ -74,6 +74,19 @@ async function ensureSymlink(target: string, source: string): Promise<void> {
}
if (!existing.isSymbolicLink()) {
+ // A previous Paperclip version copied this file into the managed home
+ // instead of symlinking it. Codex refresh tokens rotate and are
+ // single-use, so a stale copy fails with refresh_token_reused on the next
+ // run (#5028). Replace the regular file with a symlink so the CLI follows
+ // the live source. Safe to delete: target is always under the
+ // Paperclip-managed company home, never the user's real ~/.codex.
+ // Directories are left alone — `fs.unlink` would throw EISDIR on Unix
+ // (and behave inconsistently on Windows). A directory at this path is not
+ // a Paperclip-written stale copy and warrants operator inspection rather
+ // than silent removal.
+ if (existing.isDirectory()) return;
+ await fs.unlink(target);
+ await createExpectedSymlink(target, source);
return;
}
diff --git a/packages/adapters/codex-local/src/server/parse.test.ts b/packages/adapters/codex-local/src/server/parse.test.ts
index 93b76b1865..bfd15e24ae 100644
--- a/packages/adapters/codex-local/src/server/parse.test.ts
+++ b/packages/adapters/codex-local/src/server/parse.test.ts
@@ -80,6 +80,7 @@ describe("isCodexUnknownSessionError", () => {
it("still detects existing stale-session wordings", () => {
expect(isCodexUnknownSessionError("unknown thread id", "")).toBe(true);
expect(isCodexUnknownSessionError("", "state db missing rollout path for thread abc")).toBe(true);
+ expect(isCodexUnknownSessionError("", "state db returned stale rollout path for thread abc")).toBe(true);
});
it("does not classify unrelated Codex failures as stale sessions", () => {
diff --git a/packages/adapters/codex-local/src/server/parse.ts b/packages/adapters/codex-local/src/server/parse.ts
index 679a3f8f4d..6dd3d5fb3f 100644
--- a/packages/adapters/codex-local/src/server/parse.ts
+++ b/packages/adapters/codex-local/src/server/parse.ts
@@ -78,7 +78,7 @@ export function isCodexUnknownSessionError(stdout: string, stderr: string): bool
.map((line) => line.trim())
.filter(Boolean)
.join("\n");
- return /unknown (session|thread)|session .* not found|thread .* not found|conversation .* not found|missing rollout path for thread|state db missing rollout path|no rollout found for thread id/i.test(
+ return /unknown (session|thread)|session .* not found|thread .* not found|conversation .* not found|missing rollout path for thread|state db missing rollout path|state db returned stale rollout path|no rollout found for thread id/i.test(
haystack,
);
}