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

## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - codex_local runs Codex CLI under a per-company "managed home" so multiple companies don't trample on each other's session state > - For `auth.json` specifically, the managed home keeps a SYMLINK to the user's real `~/.codex/auth.json` rather than a copy — Codex refresh tokens rotate and are single-use, so any copy goes stale the moment the source rotates and every subsequent run dies with `401 refresh_token_reused` > - Older Paperclip versions copied `auth.json` instead. After upgrading, `ensureSymlink()` saw a regular file at the target, hit `if (!existing.isSymbolicLink()) return;`, and silently kept the stale copy > - This pull request makes the upgrade path self-healing inside `ensureSymlink()` itself: when the target is a regular file, unlink it and create the symlink, since the target lives under the Paperclip-managed home and is safe to delete. Directories are skipped to avoid `EISDIR` on Unix (and inconsistent behavior on Windows) > - The benefit is operators who upgraded from a copy-based version stop getting refresh-token-reused failures without having to manually purge `companies/<id>/codex-home/auth.json`, and the healing is defense-in-depth even outside the `prepareManagedCodexHome` cleanup path ## What Changed - `packages/adapters/codex-local/src/server/codex-home.ts` — `ensureSymlink()` previously bailed out of the `!existing.isSymbolicLink()` branch, leaving any pre-existing regular file untouched. Now unlinks and recreates the symlink in that branch via the existing `createExpectedSymlink()` helper (preserves the EEXIST race-tolerance behavior added in #5119). A guard skips directories so the call never throws `EISDIR` and aborts `prepareManagedCodexHome`. Inline comment explains the safety: target is always under the company-scoped managed home (`<paperclipHome>/instances/<id>/companies/<companyId>/codex-home/`), never the user's real `~/.codex`. - `packages/adapters/codex-local/src/server/codex-home.test.ts` — adds a regression test for #5028: pre-seed a stale copy at the target, run `prepareManagedCodexHome`, assert the target is now a symlink and reads through to the fresh source. The existing concurrent-symlink test is preserved. ## Verification ``` pnpm --filter @paperclipai/adapter-codex-local exec vitest run # Test Files 8 passed (8) # Tests 26 passed (26) pnpm --filter @paperclipai/adapter-codex-local exec tsc --noEmit # clean ``` Manual repro flow that the regression test mirrors: 1. Create a stale copy: `echo '{"token":"old"}' > <managedHome>/auth.json`. 2. Rotate source: `echo '{"token":"new"}' > ~/.codex/auth.json`. 3. Trigger any codex_local run — `prepareManagedCodexHome` is called from the execute path, the managed file is now a symlink to the source, and the CLI sees the fresh token. ## Risks - **Low risk.** The new branch only fires when the target file is a regular file (the upgrade path) — a pure copy that Codex couldn't have written, since Codex never writes into the managed home. Operators in steady-state on the symlink-based version are unaffected. - The `fs.unlink` only runs against the per-company managed-home path, never the user's real `~/.codex`. Inline comment makes this guarantee explicit. - A directory at the auth.json path is left in place (no silent `EISDIR` crash) — this requires operator inspection rather than autonomous deletion. - The healing uses `createExpectedSymlink()` so it remains tolerant of EEXIST races with concurrent prepare calls (the concurrent-symlink test still passes). - No DB / migration / schema impact. ## Model Used - Anthropic Claude Opus 4.7 (claude-opus-4-7), via Claude Code CLI with extended tool use (Read / Edit / Bash / Grep). No extended-thinking budget consumed beyond default. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots — N/A, adapter-only - [x] I have updated relevant documentation to reflect my changes — inline comment explains the why and the safety of the unlink - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge - [x] I searched the GitHub PR list for similar PRs and confirmed this is not a duplicate Fixes #5028. --------- Co-authored-by: Devin Foley <devin@paperclip.ing> Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-06-10 19:20:20 +05:30
parent dfd3ed44c5
commit c297ba2a80
4 changed files with 108 additions and 3 deletions
@@ -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 });
+    }
+  });
+
 });
@@ -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;
  }

@@ -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", () => {
@@ -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,
  );
 }