From c297ba2a80f235ce045e7179affead708a7dc05e Mon Sep 17 00:00:00 2001 From: Harshit Khemani Date: Wed, 10 Jun 2026 19:20:20 +0530 Subject: [PATCH] fix(codex-local): replace stale auth.json copy with symlink on prepare (#5028) (#5240) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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//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 (`/instances//companies//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"}' > /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 Co-authored-by: Paperclip --- .../codex-local/src/server/codex-home.test.ts | 93 ++++++++++++++++++- .../codex-local/src/server/codex-home.ts | 15 ++- .../codex-local/src/server/parse.test.ts | 1 + .../adapters/codex-local/src/server/parse.ts | 2 +- 4 files changed, 108 insertions(+), 3 deletions(-) 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 86483751..840db456 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 ee87e6cb..bd9d4c02 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 { +export async function ensureSymlink(target: string, source: string): Promise { 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 { } 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 93b76b18..bfd15e24 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 679a3f8f..6dd3d5fb 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, ); }