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>

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 });
+    }
+  });
+
 });

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;
   }
 

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

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,
   );
 }