fix(codex): return remote auth refresh to external home

Author: AI Agent

docs/adapters/codex-local.md

@@ -75,7 +75,10 @@ A managed home is created empty, so the adapter must provision auth into it befo
    instead of copying a stale token into the managed home.
 3. **External `CODEX_HOME`:** if adapter env points `CODEX_HOME` outside the
    Paperclip-managed company tree, that home is self-managed. Paperclip does
-   not seed or overwrite it, so its own `auth.json` wins.
+   not seed it, so its own `auth.json` wins. A remote run stages that credential
+   and copies a strictly newer same-account OAuth refresh back to that external
+   source on teardown, matching the mutation a local Codex process would make.
+   Separate external homes can therefore retain separate subscription identities.
 
 For sandbox or SSH execution, Paperclip uploads the effective managed
 `CODEX_HOME` and launches Codex with `CODEX_HOME` pointing at that uploaded
@@ -84,6 +87,11 @@ managed-home mode. If the host has no usable `auth.json` and no per-agent
 `OPENAI_API_KEY`, the managed run fails fast instead of falling back to an
 in-sandbox login.
 
+For an external `CODEX_HOME`, the uploaded credential remains bound to that
+external home. Teardown never redirects its refreshed OAuth credential into the
+shared host login, so two agents configured with different external homes cannot
+overwrite each other's subscription identity.
+
 Worked example: a worker runs in a sandbox image that already has
 `$HOME/.codex/auth.json`, and the Paperclip host is logged in with a ChatGPT
 subscription. For a managed `codex_local` agent, Paperclip symlinks the host

packages/adapters/codex-local/src/server/codex-auth-copyback.ts

@@ -18,7 +18,7 @@ const execFile = promisify(execFileCallback);
 // predicate answers one question — "should the caller replace `destination`
 // with `source`?" — purely by argument order (first = source, second =
 // destination). For the copy-back the sandbox credential is the `source` and
-// the shared host credential is the `destination`, so exit 10 (use source)
+// the host-side source credential is the `destination`, so exit 10 (use source)
 // means "install the sandbox copy onto the host" and exit 20 (keep destination)
 // means "leave the host copy untouched". The predicate only ever reads the two
 // files and exits with a code; it never prints token bytes.
@@ -39,9 +39,9 @@ export interface CopyBackCodexAuthInput {
    */
   readSandboxAuth: () => Promise<Buffer>;
   /**
-   * Absolute path of the shared host credential to (maybe) overwrite — the
-   * symlink *source* the managed Codex homes point their `auth.json` at, never
-   * an in-sandbox or per-agent symlink.
+   * Absolute path of the host-side source credential to (maybe) overwrite —
+   * either the shared source for managed homes or an external CODEX_HOME auth
+   * source, never an in-sandbox or per-agent managed symlink.
    */
   hostAuthPath: string;
   /** Non-leaking progress sink: receives decision/outcome lines only. */
@@ -92,7 +92,7 @@ async function decideExitCode(sourcePath: string, destinationPath: string): Prom
 
 /**
  * Guards, locks, and atomically installs a strictly-newer sandbox Codex
- * `auth.json` onto the shared host credential at teardown.
+ * `auth.json` onto its host-side source credential at teardown.
  *
  * Sequence, all under `withDirectoryMergeLock` on the host target's directory
  * so a concurrent inbound restore or another copy-back can't interleave:

packages/adapters/codex-local/src/server/execute.test.ts

@@ -1,4 +1,4 @@
-import { lstat, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -120,7 +120,14 @@ describe("codex execute — outbound auth copy-back restore contribution", () =>
   async function runTeardown(input: {
     sandboxAuth: string;
     hostAuth: string;
-  }): Promise<{ finalHostAuth: string; finalHostMode: number }> {
+    externalHostAuth?: string;
+    externalAuthViaSymlink?: boolean;
+  }): Promise<{
+    finalHostAuth: string;
+    finalHostMode: number;
+    finalSharedHostAuth: string;
+    configuredAuthIsSymlink: boolean;
+  }> {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-copyback-e2e-"));
     cleanupDirs.push(rootDir);
     const workspaceDir = path.join(rootDir, "workspace");
@@ -132,6 +139,20 @@ describe("codex execute — outbound auth copy-back restore contribution", () =>
     await mkdir(sharedHostHome, { recursive: true });
     const hostAuthPath = path.join(sharedHostHome, "auth.json");
     await writeFile(hostAuthPath, input.hostAuth, { mode: 0o600 });
+    const configuredHome = input.externalHostAuth == null
+      ? sharedHostHome
+      : path.join(rootDir, "external-codex-home");
+    if (input.externalHostAuth != null) {
+      await mkdir(configuredHome, { recursive: true });
+      const configuredAuthPath = path.join(configuredHome, "auth.json");
+      if (input.externalAuthViaSymlink) {
+        const externalAuthSource = path.join(rootDir, "external-auth-source.json");
+        await writeFile(externalAuthSource, input.externalHostAuth, { mode: 0o600 });
+        await symlink(externalAuthSource, configuredAuthPath);
+      } else {
+        await writeFile(configuredAuthPath, input.externalHostAuth, { mode: 0o600 });
+      }
+    }
 
     savedCodexHomeEnv = process.env.CODEX_HOME;
     process.env.CODEX_HOME = sharedHostHome;
@@ -151,8 +172,9 @@ describe("codex execute — outbound auth copy-back restore contribution", () =>
         command: "codex",
         engine: "cli",
         // External CODEX_HOME (outside the managed company tree) so no managed
-        // seeding rewrites auth.json before teardown; equals the shared host home.
-        env: { CODEX_HOME: sharedHostHome },
+        // seeding rewrites auth.json before teardown. Most cases use the shared
+        // home; multi-subscription coverage supplies a distinct external home.
+        env: { CODEX_HOME: configuredHome },
       },
       context: {
         paperclipWorkspace: {
@@ -176,8 +198,10 @@ describe("codex execute — outbound auth copy-back restore contribution", () =>
     });
 
     return {
-      finalHostAuth: await readFile(hostAuthPath, "utf8"),
-      finalHostMode: (await lstat(hostAuthPath)).mode & 0o777,
+      finalHostAuth: await readFile(path.join(configuredHome, "auth.json"), "utf8"),
+      finalHostMode: (await stat(path.join(configuredHome, "auth.json"))).mode & 0o777,
+      finalSharedHostAuth: await readFile(hostAuthPath, "utf8"),
+      configuredAuthIsSymlink: (await lstat(path.join(configuredHome, "auth.json"))).isSymbolicLink(),
     };
   }
 
@@ -211,6 +235,42 @@ describe("codex execute — outbound auth copy-back restore contribution", () =>
     expect(result.finalHostMode).toBe(0o600);
   });
 
+  it.each([
+    { authStorage: "regular file", externalAuthViaSymlink: false },
+    { authStorage: "symlink source", externalAuthViaSymlink: true },
+  ])(
+    "round-trips an external CODEX_HOME identity from a $authStorage without overwriting the shared subscription",
+    async ({ externalAuthViaSymlink }) => {
+      const sharedHostAuth = subscriptionAuth({
+        accountId: "acct-primary",
+        lastRefresh: "2026-07-09T03:00:00Z",
+        marker: "shared-primary",
+      });
+      const externalHostAuth = subscriptionAuth({
+        accountId: "acct-secondary",
+        lastRefresh: "2026-07-09T01:00:00Z",
+        marker: "external-older",
+      });
+      const sandboxAuth = subscriptionAuth({
+        accountId: "acct-secondary",
+        lastRefresh: "2026-07-09T02:00:00Z",
+        marker: "external-refreshed",
+      });
+
+      const result = await runTeardown({
+        sandboxAuth,
+        hostAuth: sharedHostAuth,
+        externalHostAuth,
+        externalAuthViaSymlink,
+      });
+
+      expect(result.finalHostAuth).toBe(sandboxAuth);
+      expect(result.finalHostMode).toBe(0o600);
+      expect(result.finalSharedHostAuth).toBe(sharedHostAuth);
+      expect(result.configuredAuthIsSymlink).toBe(externalAuthViaSymlink);
+    },
+  );
+
   it("keeps the host auth.json when the sandbox copy is a tie or older on teardown", async () => {
     const cases = [
       {

packages/adapters/codex-local/src/server/execute.ts

@@ -110,6 +110,26 @@ const executeCodexAcp = createCodexAcpExecutor();
 const CODEX_ROLLOUT_NOISE_RE =
   /^\d{4}-\d{2}-\d{2}T[^\s]+\s+ERROR\s+codex_core::rollout::list:\s+state db missing rollout path for thread\s+[a-z0-9-]+$/i;
 
+async function resolveCodexAuthCopyBackPath(input: {
+  configuredCodexHome: string | null;
+  configuredHomeIsManaged: boolean;
+  effectiveCodexHome: string;
+}): Promise<string> {
+  if (input.configuredCodexHome == null || input.configuredHomeIsManaged) {
+    return path.join(resolveSharedCodexHomeDir(process.env), "auth.json");
+  }
+
+  const externalAuthPath = path.join(input.effectiveCodexHome, "auth.json");
+  const entry = await fs.lstat(externalAuthPath).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (!entry?.isSymbolicLink()) return externalAuthPath;
+
+  const target = await fs.readlink(externalAuthPath);
+  return path.resolve(path.dirname(externalAuthPath), target);
+}
+
 function stripCodexRolloutNoise(text: string): string {
   const parts = text.split(/\r?\n/);
   const kept: string[] = [];
@@ -759,6 +779,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
           // the single-use `auth.json`) are dereferenced to bytes. This drops the
           // large runtime state (`sessions/`, `*.sqlite`, `plugins/`, …) that the
           // 4-name denylist missed and that a sandbox run never needs.
+          const authCopyBackPath = await resolveCodexAuthCopyBackPath({
+            configuredCodexHome,
+            configuredHomeIsManaged,
+            effectiveCodexHome,
+          });
           stagedCodexHomeDir = await stageCodexHomeForSync(effectiveCodexHome, { runId });
           return await prepareAdapterExecutionTargetRuntime({
             runId,
@@ -789,16 +814,18 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
                 // Outbound (sandbox→host) auth copy-back contribution: at
                 // teardown, read the sandbox's `auth.json` and — guarded by the
                 // same direction-agnostic decision predicate under a directory
-                // lock — atomically install it onto the shared host credential
-                // when it is a strictly-newer same-identity subscription copy.
+                // lock — atomically install it onto its host-side source
+                // credential when it is a strictly-newer same-identity copy.
                 // The sandbox core stays adapter-agnostic; it just awaits this
                 // generic `restore` seam per asset before destroying the sandbox.
-                // Target is the shared symlink SOURCE (what managed homes point
-                // `auth.json` at), not the in-sandbox symlink.
+                // Target is the actual host-side credential source for this
+                // binding: the shared source for managed homes, or the external
+                // CODEX_HOME auth source for a self-managed override. Never
+                // point copy-back at an in-sandbox or per-agent managed symlink.
                 restore: async ({ assetDir, readFile }) =>
                   void (await copyBackCodexAuth({
                     readSandboxAuth: () => readFile(path.posix.join(assetDir, "auth.json")),
-                    hostAuthPath: path.join(resolveSharedCodexHomeDir(process.env), "auth.json"),
+                    hostAuthPath: authCopyBackPath,
                     log: (line) => onLog("stdout", `${line}\n`),
                     // Additive cache write (sandbox to host): also cache the
                     // sandbox subscription credential in its per-identity slot,