@tickernelz/paperclip-pro-adapter-codex-local 2026.925.0

package/dist/server/codex-auth-copyback.js

@@ -0,0 +1,123 @@
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { withDirectoryMergeLock } from "@tickernelz/paperclip-pro-adapter-utils/workspace-restore-merge";
+import { isCodexAuthCacheEnabled, readSubscriptionAccountId, writeCodexAuthCacheEntry, } from "./codex-auth-cache.js";
+import { IMPLAUSIBLE_LAST_REFRESH_EXIT, USE_SOURCE_EXIT, decideCodexAuthMerge, } from "./codex-auth-merge-decision.js";
+/**
+ * Guards, locks, and atomically installs a strictly-newer sandbox Codex
+ * `auth.json` onto the shared host 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:
+ *   1. Read the sandbox credential bytes. A genuinely absent sandbox
+ *      `auth.json` (ENOENT) means there is simply nothing to copy back, so it
+ *      resolves to `kept-host` (benign no-op, host untouched); every other read
+ *      error stays fail-loud.
+ *   2. Stage them to a `0600` temp file on the **same filesystem** as the host
+ *      target (its directory), which doubles as the predicate `source`.
+ *   3. Run the Phase-3 decision predicate (`source` = sandbox temp, `destination`
+ *      = host). Exit 10 → adopt the sandbox copy; exit 20 → keep the host copy.
+ *   4. On exit 10, `rename` the staged temp over the host target — an atomic
+ *      same-directory swap that preserves mode `0600`. On exit 20, discard it.
+ * The staged temp is always removed (rename consumes it on the copy path; the
+ * finally cleans it up otherwise), so a failure never leaves a partial file.
+ * Never logs token bytes — only the decision outcome.
+ */
+export async function copyBackCodexAuth(input) {
+    const { readSandboxAuth, hostAuthPath, log, resolveCacheEntryPath, env } = input;
+    // Read first (outside the lock) — a read never mutates the host, so there is
+    // nothing to serialize yet. A genuinely absent sandbox `auth.json` (ENOENT —
+    // e.g. Codex removed it mid-run, or a non-provisioned edge) is a "nothing to
+    // copy back" no-op, not a teardown failure: return `kept-host` and log the
+    // benign outcome. Every other read error stays fail-loud so a real read fault
+    // is never silently mistaken for "nothing to copy back".
+    let sandboxAuthBytes;
+    try {
+        sandboxAuthBytes = await readSandboxAuth();
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            await log("[paperclip] Codex auth copy-back: no sandbox credential to copy back (absent auth.json); host credential kept.");
+            return "kept-host";
+        }
+        throw error;
+    }
+    const hostDir = path.dirname(hostAuthPath);
+    await mkdir(hostDir, { recursive: true });
+    const hostOutcome = await withDirectoryMergeLock(hostDir, async () => {
+        // Stage on the same filesystem as the host target so both the predicate read
+        // and the final rename stay device-local (rename across devices is not
+        // atomic and would fail with EXDEV).
+        const stagedTempPath = path.join(hostDir, `.auth.json.copyback-${process.pid}-${randomUUID()}.tmp`);
+        // `wx` + explicit mode create the temp private (0600) and fail if it somehow
+        // already exists, so we never write through a pre-existing symlink.
+        const handle = await open(stagedTempPath, "wx", 0o600);
+        try {
+            await handle.writeFile(sandboxAuthBytes);
+            await handle.close();
+            const decision = await decideCodexAuthMerge(stagedTempPath, hostAuthPath, {
+                errorLabel: "codex auth copy-back",
+            });
+            if (decision === USE_SOURCE_EXIT) {
+                // Atomic same-directory swap; rename preserves the temp's 0600 mode.
+                await rename(stagedTempPath, hostAuthPath);
+                await log("[paperclip] Codex auth copy-back: sandbox credential is strictly newer for the same subscription identity; installed to the host at mode 0600.");
+                return "copied";
+            }
+            // Make a clock-bound rejection visible. A host with a wrong clock would
+            // otherwise discard an honest refresh with no signal. Log only the exit
+            // code and this caller's own label — never a timestamp read from either
+            // file, and never credential bytes.
+            if (decision === IMPLAUSIBLE_LAST_REFRESH_EXIT) {
+                await log(`[paperclip] Codex auth copy-back: WARNING host credential kept (decision exit ${IMPLAUSIBLE_LAST_REFRESH_EXIT}, codex auth copy-back) — the sandbox copy's last_refresh sat further ahead of the host clock than the plausible skew allowance. Check the host clock if this is unexpected.`);
+                return "kept-host";
+            }
+            await log("[paperclip] Codex auth copy-back: host credential kept (sandbox copy is not a strictly-newer same-identity subscription credential).");
+            return "kept-host";
+        }
+        finally {
+            // Close is idempotent-safe to skip after an explicit close; the temp is the
+            // thing that must never linger. On the copy path rename already consumed it
+            // (force makes the removal a no-op); on every other path this deletes the
+            // staged credential bytes.
+            await handle.close().catch(() => undefined);
+            await rm(stagedTempPath, { force: true }).catch(() => undefined);
+        }
+    }, env);
+    // Additive cache write. Independent of the host default overwrite above: it
+    // runs on its own directory lock, keys the slot by the real sandbox
+    // `account_id`, and can write a slot for a different identity than the host
+    // holds. It never touches the host default store. The off-switch (default on)
+    // makes this a no-op when disabled. Only a usable subscription credential has
+    // an identity to key; an api-key or unusable sandbox credential is skipped.
+    //
+    // The cache write is best-effort. The host copy-back above already finished
+    // and set `hostOutcome`, so a failure of this additive write must not replace
+    // that successful result. Catch the error, log it, and return `hostOutcome`.
+    // The cache stays a hint: the next teardown re-attempts the write.
+    if (resolveCacheEntryPath && isCodexAuthCacheEnabled(env)) {
+        try {
+            const sandboxAccountId = readSubscriptionAccountId(sandboxAuthBytes);
+            if (sandboxAccountId) {
+                const cacheEntryPath = await resolveCacheEntryPath(sandboxAccountId);
+                await writeCodexAuthCacheEntry({ sandboxAuthBytes, cacheEntryPath, log, env });
+            }
+        }
+        catch (error) {
+            // Log only the errno code, never the error message. The message embeds the
+            // cache slot path, and the slot path embeds the raw `account_id`; the code
+            // (for example EACCES or ENOSPC) makes the failure diagnosable without a
+            // leak. Token bytes never reach the log.
+            const code = error?.code ?? "unknown";
+            // The host copy-back above already finished and set `hostOutcome`. This
+            // diagnostic log is the last step, so a rejecting logger must not throw
+            // and turn that successful result into a failed copy-back. Guard the log:
+            // a rejection here is swallowed, and the function still returns
+            // `hostOutcome` below.
+            await Promise.resolve(log(`[paperclip] Codex auth cache: additive cache write failed (${code}); host copy-back result kept.`)).catch(() => undefined);
+        }
+    }
+    return hostOutcome;
+}
+//# sourceMappingURL=codex-auth-copyback.js.map

package/dist/server/codex-auth-copyback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-auth-copyback.js","sourceRoot":"","sources":["../../src/server/codex-auth-copyback.ts"],"names":[],"mappings":"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"}

package/dist/server/codex-auth-copyback.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codex-auth-copyback.test.d.ts.map

package/dist/server/codex-auth-copyback.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-auth-copyback.test.d.ts","sourceRoot":"","sources":["../../src/server/codex-auth-copyback.test.ts"],"names":[],"mappings":""}

package/dist/server/codex-auth-copyback.test.js

@@ -0,0 +1,507 @@
+import { chmod, lstat, mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { copyBackCodexAuth } from "./codex-auth-copyback.js";
+import { ensureCodexAuthCacheEntryDir, resolveCodexAuthCacheDir, resolveCodexAuthCacheEntryPath, } from "./codex-auth-cache.js";
+import { resolveSharedCodexHomeDir } from "./codex-home.js";
+// The copy-back module reuses the exact same direction-agnostic decision
+// predicate (`codex-auth-merge-decision.cjs`) that the inbound extract path
+// runs, only with the arguments flipped: for an outbound copy-back the sandbox
+// copy is the `source` and the host copy is the `destination`, so exit 10
+// (use source) means "install the sandbox credential onto the host" and exit 20
+// (keep destination) means "leave the host credential untouched". This suite
+// drives the REAL `.cjs` through the module (no stub predicate) against a real
+// host tmp filesystem, injecting only the sandbox read.
+describe("copyBackCodexAuth", () => {
+    const cleanupDirs = [];
+    afterEach(async () => {
+        while (cleanupDirs.length > 0) {
+            const dir = cleanupDirs.pop();
+            if (!dir)
+                continue;
+            // Re-open perms in case a test tightened them, so cleanup always succeeds.
+            await chmod(dir, 0o700).catch(() => undefined);
+            await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    });
+    function subscriptionAuth(input) {
+        return JSON.stringify({
+            tokens: {
+                id_token: `id-token-${input.marker}`,
+                access_token: `access-token-${input.marker}`,
+                refresh_token: `refresh-token-${input.marker}`,
+                account_id: input.accountId,
+            },
+            ...(input.lastRefresh ? { last_refresh: input.lastRefresh } : {}),
+        }, null, 2);
+    }
+    function apiKeyAuth(marker) {
+        return JSON.stringify({ OPENAI_API_KEY: `sk-${marker}` }, null, 2);
+    }
+    async function makeHostDir() {
+        const dir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-copyback-"));
+        cleanupDirs.push(dir);
+        return dir;
+    }
+    const NEWER = "2026-07-09T02:00:00Z";
+    const OLDER = "2026-07-09T01:00:00Z";
+    async function runCopyBack(input) {
+        const hostDir = input.hostDir ?? (await makeHostDir());
+        const hostAuthPath = path.join(hostDir, "auth.json");
+        await writeFile(hostAuthPath, input.hostAuth, { mode: 0o600 });
+        const readSandboxAuth = typeof input.sandboxAuth === "function"
+            ? input.sandboxAuth
+            : async () => Buffer.from(input.sandboxAuth, "utf8");
+        const logs = [];
+        const outcome = await copyBackCodexAuth({
+            readSandboxAuth,
+            hostAuthPath,
+            log: (line) => {
+                logs.push(line);
+            },
+        });
+        const finalHostAuth = await readFile(hostAuthPath, "utf8");
+        const finalHostMode = (await lstat(hostAuthPath)).mode & 0o777;
+        const leftoverEntries = (await readdir(hostDir)).filter((name) => name !== "auth.json");
+        return { outcome, finalHostAuth, finalHostMode, logs, leftoverEntries };
+    }
+    it("installs a strictly-newer same-account sandbox auth onto the host at 0600", async () => {
+        const sandboxAuth = subscriptionAuth({
+            accountId: "acct-same",
+            lastRefresh: NEWER,
+            marker: "sandbox-newer-SENTINEL",
+        });
+        const hostAuth = subscriptionAuth({
+            accountId: "acct-same",
+            lastRefresh: OLDER,
+            marker: "host-older-SENTINEL",
+        });
+        const result = await runCopyBack({ sandboxAuth, hostAuth });
+        expect(result.outcome).toBe("copied");
+        expect(result.finalHostAuth).toBe(sandboxAuth);
+        expect(result.finalHostMode).toBe(0o600);
+        // Temp staging file must be gone once the swap completes.
+        expect(result.leftoverEntries).toEqual([]);
+        // Never leak token bytes in log output.
+        expect(result.logs.join("\n")).not.toContain("SENTINEL");
+    });
+    it("keeps the host auth when the sandbox copy is not strictly newer", async () => {
+        const cases = [
+            {
+                name: "tie",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: NEWER, marker: "sandbox-tie" }),
+                hostAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: NEWER, marker: "host-tie" }),
+            },
+            {
+                name: "sandbox older",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: OLDER, marker: "sandbox-older" }),
+                hostAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: NEWER, marker: "host-newer" }),
+            },
+            {
+                name: "missing sandbox last_refresh",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-same", marker: "sandbox-no-refresh" }),
+                hostAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: NEWER, marker: "host-refresh" }),
+            },
+            {
+                name: "unparseable sandbox last_refresh",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: "not-a-date", marker: "sandbox-bad" }),
+                hostAuth: subscriptionAuth({ accountId: "acct-same", lastRefresh: NEWER, marker: "host-refresh" }),
+            },
+        ];
+        for (const entry of cases) {
+            const result = await runCopyBack({ sandboxAuth: entry.sandboxAuth, hostAuth: entry.hostAuth });
+            expect(result.outcome, entry.name).toBe("kept-host");
+            expect(result.finalHostAuth, entry.name).toBe(entry.hostAuth);
+            expect(result.finalHostMode, entry.name).toBe(0o600);
+            expect(result.leftoverEntries, entry.name).toEqual([]);
+        }
+    });
+    it("keeps the host auth on identity mismatch, kind mismatch, apikey, and unusable sandbox auth", async () => {
+        const hostAuth = subscriptionAuth({ accountId: "acct-host", lastRefresh: OLDER, marker: "host-keep" });
+        const cases = [
+            {
+                name: "identity mismatch (sandbox newer, different account)",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-other", lastRefresh: NEWER, marker: "sandbox-other" }),
+                hostAuth,
+            },
+            {
+                name: "kind mismatch (sandbox subscription, host apikey)",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-host", lastRefresh: NEWER, marker: "sandbox-sub" }),
+                hostAuth: apiKeyAuth("host-api-key"),
+            },
+            {
+                name: "sandbox apikey",
+                sandboxAuth: apiKeyAuth("sandbox-api-key"),
+                hostAuth,
+            },
+            {
+                name: "sandbox unusable JSON",
+                sandboxAuth: "{not valid json",
+                hostAuth,
+            },
+            {
+                name: "sandbox account id missing",
+                sandboxAuth: JSON.stringify({
+                    tokens: { id_token: "id", access_token: "acc", refresh_token: "ref" },
+                    last_refresh: NEWER,
+                }),
+                hostAuth,
+            },
+            {
+                name: "host unusable JSON (never create host auth from sandbox)",
+                sandboxAuth: subscriptionAuth({ accountId: "acct-host", lastRefresh: NEWER, marker: "sandbox-valid" }),
+                hostAuth: "{not valid json",
+            },
+        ];
+        for (const entry of cases) {
+            const result = await runCopyBack({ sandboxAuth: entry.sandboxAuth, hostAuth: entry.hostAuth });
+            expect(result.outcome, entry.name).toBe("kept-host");
+            expect(result.finalHostAuth, entry.name).toBe(entry.hostAuth);
+            expect(result.finalHostMode, entry.name).toBe(0o600);
+            expect(result.leftoverEntries, entry.name).toEqual([]);
+        }
+    });
+    it("creates a missing shared Codex home before staging copy-back", async () => {
+        const rootDir = await makeHostDir();
+        const hostDir = path.join(rootDir, "missing-codex-home");
+        const hostAuthPath = path.join(hostDir, "auth.json");
+        const logs = [];
+        const outcome = await copyBackCodexAuth({
+            readSandboxAuth: async () => Buffer.from(apiKeyAuth("sandbox-only"), "utf8"),
+            hostAuthPath,
+            log: (line) => {
+                logs.push(line);
+            },
+        });
+        expect(outcome).toBe("kept-host");
+        expect(await readdir(hostDir)).toEqual([]);
+        expect(logs.join("\n")).not.toContain("sandbox-only");
+    });
+    it("preserves the host file atomically when the install cannot be staged (no partial write, no leaked temp)", async () => {
+        // Make the host directory read-only so staging the same-filesystem temp fails
+        // with EACCES. The host credential must be left byte-for-byte intact and no
+        // partial/temp file may remain — the outbound write is all-or-nothing.
+        const hostDir = await makeHostDir();
+        const hostAuth = subscriptionAuth({ accountId: "acct-same", lastRefresh: OLDER, marker: "host-intact" });
+        const hostAuthPath = path.join(hostDir, "auth.json");
+        await writeFile(hostAuthPath, hostAuth, { mode: 0o600 });
+        const before = await stat(hostAuthPath);
+        await chmod(hostDir, 0o500); // r-x: readable/traversable, not writable
+        try {
+            const sandboxAuth = subscriptionAuth({ accountId: "acct-same", lastRefresh: NEWER, marker: "sandbox-newer" });
+            await expect(copyBackCodexAuth({
+                readSandboxAuth: async () => Buffer.from(sandboxAuth, "utf8"),
+                hostAuthPath,
+                log: () => { },
+            })).rejects.toThrow();
+        }
+        finally {
+            await chmod(hostDir, 0o700);
+        }
+        const after = await stat(hostAuthPath);
+        expect(await readFile(hostAuthPath, "utf8")).toBe(hostAuth);
+        expect(after.mode & 0o777).toBe(0o600);
+        expect(after.mtimeMs).toBe(before.mtimeMs);
+        expect((await readdir(hostDir)).filter((name) => name !== "auth.json")).toEqual([]);
+    });
+    it("treats an absent sandbox auth.json (ENOENT) as a keep-host no-op, host untouched, no throw", async () => {
+        const hostAuth = subscriptionAuth({ accountId: "acct-same", lastRefresh: OLDER, marker: "host-intact" });
+        // The real production `readSandboxAuth` is `readFile("${assetDir}/auth.json")`;
+        // a genuinely absent file surfaces a node ENOENT error. That must be a benign
+        // "nothing to copy back" outcome, not a fail-loud teardown error.
+        const enoent = Object.assign(new Error("ENOENT: no such file or directory, open 'auth.json'"), {
+            code: "ENOENT",
+        });
+        const result = await runCopyBack({
+            sandboxAuth: async () => {
+                throw enoent;
+            },
+            hostAuth,
+        });
+        expect(result.outcome).toBe("kept-host");
+        expect(result.finalHostAuth).toBe(hostAuth);
+        expect(result.finalHostMode).toBe(0o600);
+        // No staging temp is ever created on the ENOENT path.
+        expect(result.leftoverEntries).toEqual([]);
+        expect(result.logs.join("\n")).toContain("no sandbox credential to copy back");
+    });
+    it("fails loud when the sandbox read errors and leaves the host untouched", async () => {
+        const hostDir = await makeHostDir();
+        const hostAuth = subscriptionAuth({ accountId: "acct-same", lastRefresh: OLDER, marker: "host-intact" });
+        const hostAuthPath = path.join(hostDir, "auth.json");
+        await writeFile(hostAuthPath, hostAuth, { mode: 0o600 });
+        await expect(copyBackCodexAuth({
+            readSandboxAuth: async () => {
+                throw new Error("sandbox read boom");
+            },
+            hostAuthPath,
+            log: () => { },
+        })).rejects.toThrow(/sandbox read boom/);
+        expect(await readFile(hostAuthPath, "utf8")).toBe(hostAuth);
+        expect((await readdir(hostDir)).filter((name) => name !== "auth.json")).toEqual([]);
+    });
+    it("does not emit token substrings on any code path", async () => {
+        const sandboxAuth = subscriptionAuth({
+            accountId: "acct-same",
+            lastRefresh: NEWER,
+            marker: "TOKEN-SENTINEL",
+        });
+        const hostAuth = subscriptionAuth({
+            accountId: "acct-same",
+            lastRefresh: OLDER,
+            marker: "HOST-SENTINEL",
+        });
+        const result = await runCopyBack({ sandboxAuth, hostAuth });
+        expect(result.outcome).toBe("copied");
+        const combined = result.logs.join("\n");
+        expect(combined).not.toContain("SENTINEL");
+        expect(combined).not.toContain("id-token");
+        expect(combined).not.toContain("access-token");
+        expect(combined).not.toContain("refresh-token");
+    });
+});
+// The teardown copy-back also writes the fresher, usable subscription credential
+// into its per-identity cache slot, keyed by the real `account_id`. The cache is
+// a SEPARATE store; the host default overwrite and the cache slot are asserted
+// independently. This suite drives the real `.cjs` predicate (default mode for
+// the host store, seed mode for the cache slot) against a real host tmp
+// filesystem.
+describe("copyBackCodexAuth identity-keyed cache write", () => {
+    const cleanupDirs = [];
+    const COMPANY_ID = "company-a";
+    afterEach(async () => {
+        while (cleanupDirs.length > 0) {
+            const dir = cleanupDirs.pop();
+            if (!dir)
+                continue;
+            await chmod(dir, 0o700).catch(() => undefined);
+            await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    });
+    function subscriptionAuth(input) {
+        return JSON.stringify({
+            tokens: {
+                id_token: `id-token-${input.marker}`,
+                access_token: `access-token-${input.marker}`,
+                refresh_token: `refresh-token-${input.marker}`,
+                account_id: input.accountId,
+            },
+            ...(input.lastRefresh ? { last_refresh: input.lastRefresh } : {}),
+        });
+    }
+    function apiKeyAuth(marker) {
+        return JSON.stringify({ OPENAI_API_KEY: `sk-${marker}` });
+    }
+    const NEWER = "2026-07-09T02:00:00Z";
+    const OLDER = "2026-07-09T01:00:00Z";
+    async function makeEnv(extra = {}) {
+        const home = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-copyback-cache-"));
+        cleanupDirs.push(home);
+        const env = {
+            PAPERCLIP_HOME: home,
+            PAPERCLIP_INSTANCE_ID: "default",
+            CODEX_HOME: path.join(home, "shared-codex"),
+            ...extra,
+        };
+        const sharedHome = resolveSharedCodexHomeDir(env);
+        await mkdir(sharedHome, { recursive: true });
+        return { env, sharedHomeAuthPath: path.join(sharedHome, "auth.json"), sharedHome };
+    }
+    async function runWithCache(input) {
+        if (input.hostAuth !== undefined) {
+            await writeFile(input.sharedHomeAuthPath, input.hostAuth, { mode: 0o600 });
+        }
+        const logs = [];
+        const outcome = await copyBackCodexAuth({
+            readSandboxAuth: async () => Buffer.from(input.sandboxAuth, "utf8"),
+            hostAuthPath: input.sharedHomeAuthPath,
+            log: (line) => {
+                logs.push(line);
+            },
+            resolveCacheEntryPath: (accountId) => ensureCodexAuthCacheEntryDir(input.env, accountId, COMPANY_ID),
+            env: input.cacheEnabledEnv ?? input.env,
+        });
+        const finalHostAuth = await readFile(input.sharedHomeAuthPath, "utf8").catch((error) => (error.code === "ENOENT" ? null : Promise.reject(error)));
+        return { outcome, finalHostAuth, logs };
+    }
+    async function readCacheSlot(env, accountId) {
+        const entryPath = resolveCodexAuthCacheEntryPath(env, accountId, COMPANY_ID);
+        return readFile(entryPath, "utf8").catch((error) => error.code === "ENOENT" ? null : Promise.reject(error));
+    }
+    it("host absent (matrix row 3): host default store stays empty, cache slot holds the credential keyed by account_id", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({ accountId: "acct-y", lastRefresh: NEWER, marker: "row3" });
+        const result = await runWithCache({ sandboxAuth, env, sharedHomeAuthPath });
+        expect(result.outcome).toBe("kept-host");
+        expect(result.finalHostAuth).toBeNull(); // host never seeded
+        expect(await readCacheSlot(env, "acct-y")).toBe(sandboxAuth);
+    });
+    it("host present, same identity, sandbox newer (matrix row 1a): host default overwritten AND cache slot updated", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: NEWER, marker: "sandbox" });
+        const hostAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" });
+        const result = await runWithCache({ sandboxAuth, hostAuth, env, sharedHomeAuthPath });
+        expect(result.outcome).toBe("copied");
+        expect(result.finalHostAuth).toBe(sandboxAuth);
+        expect(await readCacheSlot(env, "acct-x")).toBe(sandboxAuth);
+    });
+    it("host present, different identity (matrix row 1b): host default untouched, cache slot holds the new identity only", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({ accountId: "acct-y", lastRefresh: NEWER, marker: "sandbox" });
+        const hostAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" });
+        const result = await runWithCache({ sandboxAuth, hostAuth, env, sharedHomeAuthPath });
+        expect(result.outcome).toBe("kept-host");
+        expect(result.finalHostAuth).toBe(hostAuth); // host keeps its own identity X
+        expect(await readCacheSlot(env, "acct-y")).toBe(sandboxAuth); // slot Y written
+        expect(await readCacheSlot(env, "acct-x")).toBeNull(); // no slot for host identity
+    });
+    it("sandbox apikey or unusable: neither the host default nor the cache changes", async () => {
+        for (const sandboxAuth of [apiKeyAuth("sbx"), "{not valid json"]) {
+            const { env, sharedHomeAuthPath } = await makeEnv();
+            const hostAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" });
+            const result = await runWithCache({ sandboxAuth, hostAuth, env, sharedHomeAuthPath });
+            expect(result.outcome).toBe("kept-host");
+            expect(result.finalHostAuth).toBe(hostAuth);
+            const cacheDir = resolveCodexAuthCacheDir(env, COMPANY_ID);
+            // No cache slot directory is created at all for a credential with no identity.
+            await expect(readdir(cacheDir)).rejects.toThrow();
+        }
+    });
+    it("off-switch off (matrix row 1a inputs): teardown cache write is a no-op and the host default overwrite still runs", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: NEWER, marker: "sandbox" });
+        const hostAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" });
+        const result = await runWithCache({
+            sandboxAuth,
+            hostAuth,
+            env,
+            sharedHomeAuthPath,
+            cacheEnabledEnv: { ...env, PAPERCLIP_CODEX_AUTH_CACHE: "0" },
+        });
+        // Host overwrite still runs with the off-switch off.
+        expect(result.outcome).toBe("copied");
+        expect(result.finalHostAuth).toBe(sandboxAuth);
+        // No cache slot is written.
+        const cacheDir = resolveCodexAuthCacheDir(env, COMPANY_ID);
+        await expect(readdir(cacheDir)).rejects.toThrow();
+    });
+    it("two concurrent teardown writes for the same identity leave one valid cache slot (no partial file)", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        await writeFile(sharedHomeAuthPath, subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" }), { mode: 0o600 });
+        const run = (marker) => copyBackCodexAuth({
+            readSandboxAuth: async () => Buffer.from(subscriptionAuth({ accountId: "acct-x", lastRefresh: NEWER, marker }), "utf8"),
+            hostAuthPath: sharedHomeAuthPath,
+            log: () => { },
+            resolveCacheEntryPath: (accountId) => ensureCodexAuthCacheEntryDir(env, accountId, COMPANY_ID),
+            env,
+        });
+        await Promise.all([run("a"), run("b")]);
+        const entryPath = resolveCodexAuthCacheEntryPath(env, "acct-x", COMPANY_ID);
+        const slotDir = path.dirname(entryPath);
+        // Exactly one valid slot file, no leftover staging temp.
+        expect(await readdir(slotDir)).toEqual(["auth.json"]);
+        const finalSlot = await readFile(entryPath, "utf8");
+        expect(JSON.parse(finalSlot).tokens.account_id).toBe("acct-x");
+    });
+    it("the cache write never emits source token bytes or a raw account_id to the log", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({
+            accountId: "SECRET-ACCT",
+            lastRefresh: NEWER,
+            marker: "TOKEN-SENTINEL",
+        });
+        const result = await runWithCache({ sandboxAuth, env, sharedHomeAuthPath });
+        expect(await readCacheSlot(env, "SECRET-ACCT")).toBe(sandboxAuth);
+        const combined = result.logs.join("\n");
+        expect(combined).not.toContain("SENTINEL");
+        expect(combined).not.toContain("SECRET-ACCT");
+        expect(combined).not.toContain("id-token");
+    });
+    it("a read-only cache directory does not fail the copy-back: the successful host result is kept and no partial slot remains", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: NEWER, marker: "sandbox" });
+        const hostAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" });
+        await writeFile(sharedHomeAuthPath, hostAuth, { mode: 0o600 });
+        // Pre-create the entry directory, then make it read-only so the cache-slot
+        // temp create fails. The host overwrite runs first and must stay intact. The
+        // additive cache write is best-effort, so its failure must not throw.
+        const entryPath = await ensureCodexAuthCacheEntryDir(env, "acct-x", COMPANY_ID);
+        const slotDir = path.dirname(entryPath);
+        const logs = [];
+        await chmod(slotDir, 0o500);
+        let outcome;
+        try {
+            outcome = await copyBackCodexAuth({
+                readSandboxAuth: async () => Buffer.from(sandboxAuth, "utf8"),
+                hostAuthPath: sharedHomeAuthPath,
+                log: (line) => {
+                    logs.push(line);
+                },
+                resolveCacheEntryPath: (accountId) => ensureCodexAuthCacheEntryDir(env, accountId, COMPANY_ID),
+                env,
+            });
+        }
+        finally {
+            await chmod(slotDir, 0o700);
+        }
+        // The host copy-back succeeded and its result is returned unchanged.
+        expect(outcome).toBe("copied");
+        // Host default overwrite ran before the cache write and stays applied.
+        expect(await readFile(sharedHomeAuthPath, "utf8")).toBe(sandboxAuth);
+        // No partial slot file; only the (empty) slot directory remains.
+        expect(await readdir(slotDir)).toEqual([]);
+        // The failure is visible in the log with only the errno code. The raw
+        // account_id (which the failing slot path embeds) never reaches the log.
+        const combined = logs.join("\n");
+        expect(combined).toContain("additive cache write failed (EACCES)");
+        expect(combined).not.toContain("acct-x");
+    });
+    it("a rejecting cache-failure log does not override the successful host copy-back result", async () => {
+        const { env, sharedHomeAuthPath } = await makeEnv();
+        const sandboxAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: NEWER, marker: "sandbox" });
+        const hostAuth = subscriptionAuth({ accountId: "acct-x", lastRefresh: OLDER, marker: "host" });
+        await writeFile(sharedHomeAuthPath, hostAuth, { mode: 0o600 });
+        // Force the additive cache write to fail: pre-create the slot directory,
+        // then make it read-only so the slot temp create fails with EACCES.
+        const entryPath = await ensureCodexAuthCacheEntryDir(env, "acct-x", COMPANY_ID);
+        const slotDir = path.dirname(entryPath);
+        await chmod(slotDir, 0o500);
+        // The logger rejects for the cache-failure diagnostic line only. The host
+        // copy-back already installed the sandbox credential on disk, so this
+        // rejection must not propagate and must not override the "copied" result.
+        const logs = [];
+        let outcome;
+        let thrown;
+        try {
+            outcome = await copyBackCodexAuth({
+                readSandboxAuth: async () => Buffer.from(sandboxAuth, "utf8"),
+                hostAuthPath: sharedHomeAuthPath,
+                log: (line) => {
+                    logs.push(line);
+                    if (line.includes("additive cache write failed")) {
+                        return Promise.reject(new Error("log sink boom"));
+                    }
+                },
+                resolveCacheEntryPath: (accountId) => ensureCodexAuthCacheEntryDir(env, accountId, COMPANY_ID),
+                env,
+            }).catch((error) => {
+                thrown = error;
+                return undefined;
+            });
+        }
+        finally {
+            await chmod(slotDir, 0o700);
+        }
+        // The rejecting cache-failure log never surfaces as a thrown error.
+        expect(thrown).toBeUndefined();
+        // The host copy-back result is kept intact.
+        expect(outcome).toBe("copied");
+        expect(await readFile(sharedHomeAuthPath, "utf8")).toBe(sandboxAuth);
+        // No partial slot file remains after the failed cache write.
+        expect(await readdir(slotDir)).toEqual([]);
+        // The cache-failure diagnostic was attempted even though the sink rejected.
+        expect(logs.some((line) => line.includes("additive cache write failed (EACCES)"))).toBe(true);
+    });
+});
+//# sourceMappingURL=codex-auth-copyback.test.js.map