fix(config): preserve symlinked destinations in atomic writes

Applies PR #869 (nicosuave) onto current dev plus one audit-folded
amendment. atomicWriteFile/atomicWriteFileAsync wrote the temp beside the
literal destination and renamed over it; rename(2) replaces the directory
entry, so a symlinked destination (dotfiles-managed ~/.codex/config.toml)
was silently converted to a plain file and the tracked repo stopped
receiving writes (POSIX.1-2024 rename; Linux rename(2): the link will be
overwritten).

resolveWriteTarget realpaths the destination so temp and rename land
beside the real file and the link survives; the test-only real-home guard
is re-applied to the resolved target so a symlink escaping a fixture home
into the protected home is still refused; the responses-state load sweeps
stale temps in both the literal and the resolved directory.

Audit amendment (wt4 wp2): a realpath failure no longer falls back to the
literal path blindly. A genuinely absent destination keeps the literal
first-write path, but an EXISTING unresolvable symlink (dangling target,
unmounted volume, ELOOP, EACCES) is now refused and preserved instead of
silently replaced; snapshot loading sweeps the literal dir only in that
case.

Tests: 202/202 config + responses-state + test-home-guard (sync+async
link survival, no-temp-left, plain destination, first-write creation,
dangling-link refusal, resolved-dir sweep, guard escape probe);
typecheck green.

Author: lidge-jun

devlog/_plan/260802_wt4_server_config_security/020_wp2_execution_notes.md

@@ -0,0 +1,38 @@
+# wp2 execution notes (P-phase stale check, 2026-08-02)
+
+## Stale check results
+
+- `atomicWriteFile` at `src/config.ts:107`, `atomicWriteFileAsync` at :187 — both confirmed in the pre-fix form (temp `${path}.ocx.${pid}.${seq}.tmp` beside the LITERAL path; `io.rename(tmp, path)`).
+- PR #869 diff (`/tmp/wt4-pr869.diff`, 336 lines) applies CLEAN to dev@478354ee8 + wp1 commit (`git apply --check` passes).
+- PR #869 state: OPEN, MERGEABLE, quality gates green, no maintainer blocker comments.
+- The diff's `src/responses/state.ts` hunk expects `enforceAppOwnedMemoryBudget` (77243d932) — present on current dev.
+
+## PR #869 implementation shape (what will be applied)
+
+1. `resolveWriteTarget(path)` (exported): `realpathSync(path)`, fallback to literal path when unresolvable (first write of a not-yet-created file).
+2. `assertResolvedTargetAllowed(path, target)`: re-applies the test-only real-home guard (`assertNotRealHomeUnderTest`) to the RESOLVED target — a symlink escaping a temp fixture home into the protected home is refused even though the caller's dir-level check passed. Inert in production.
+3. Both sync + async writers compute `tmp` beside the RESOLVED target and rename onto it.
+4. `src/responses/state.ts` snapshot load sweeps stale temps in BOTH the literal and the resolved directory (a symlinked snapshot strands temps in the real dir).
+5. Tests: `tests/config.test.ts` symlink suite (sync+async: link survives + target updated, no temps left, plain destination unaffected, first-write creation, dangling symlink replaced), `tests/responses-state.test.ts` (sweep in resolved dir), `tests/test-home-guard.test.ts` (escape-refused probe).
+
+## Caller audit (criterion c5) — grep `atomicWriteFile` across `src/` @ dev 478354ee8
+
+| Caller | Writes into | Symlink exposure |
+|---|---|---|
+| `src/config.ts` (owner; config.json :1627, pid :2070, runtime port :2098) | OPENCODEX_HOME | direct — config dir is dotfiles-managed in the reported case |
+| `src/oauth/store.ts` | OPENCODEX_HOME credential store | high-value target; fix protects token files behind symlinked dirs |
+| `src/codex/inject.ts`, `journal.ts`, `history-provider.ts`, `account-store.ts`, `quota.ts`, `refresh.ts`, `runtime.ts`, `features.ts` | `~/.codex/*` | the reported dotfiles case (`config.toml` symlink) |
+| `src/claude/desktop-3p.ts` | Claude Desktop config | user-managed file, symlink plausible |
+| `src/grok/inject.ts` | grok config | same shape |
+| `src/responses/state.ts` | OPENCODEX_HOME snapshot | covered by the sweep-in-both-dirs hunk |
+| `src/update/job.ts`, `notify.ts` | OPENCODEX_HOME update state | covered by shared helper |
+| `src/codex/catalog/*` (aggregation, bundled, effort, metadata, parsing, provider-fetch, sync) | catalog caches | covered by shared helper |
+
+No caller needs an individual change: the fix lives in the shared writer + the one stale-temp sweep that scans directories.
+
+## Known design decisions to audit
+
+- Dangling symlink: realpath fails → literal path → rename REPLACES the dangling link (PR test asserts this). Debate point: silently replacing a dotfiles link whose target dir is temporarily unmounted. PR chose "replace"; the alternative (refuse) breaks first-write-into-new-target-dir.
+- TOCTOU: link swapped between realpath and rename lands the write at the old target. Accepted, documented in `010_implementation.md`; not claimed race-free.
+- Windows: `realpathSync` resolves junctions/symlinks on win32 too; temp stays same-volume because it sits beside the resolved target.
+- wt2 coordination: #840's memo-release touches `atomicWriteFileAsync` timeout-memo area; this diff does not overlap those lines (memo keyed by `path` argument, unchanged).

src/config.ts

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { chmodSync, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, renameSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Database } from "bun:sqlite";
 import * as z from "zod/v4";
 import {
@@ -104,6 +104,57 @@ function isMissingPathError(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
 }
 
+/**
+ * Resolve a write target through any symlink before the temp+rename dance.
+ *
+ * rename(2) replaces a directory ENTRY. When the entry is itself a symlink
+ * (a dotfiles-managed `~/.codex/config.toml` -> `~/dotfiles/.codex/config.toml`,
+ * say), renaming a sibling temp file over it destroys the link and leaves a plain
+ * file behind — the repo silently stops receiving writes. Resolving first puts both
+ * the temp file and the rename target inside the link's real directory, so the entry
+ * being replaced is the real file and the symlink survives.
+ *
+ * Same-filesystem atomicity is preserved because the temp file stays beside its
+ * resolved target. A genuinely absent destination (not yet created) falls back to
+ * the literal path, which is the correct target for a first write.
+ *
+ * An EXISTING symlink that cannot be resolved — dangling because its target volume
+ * is unmounted, an ELOOP chain, an EACCES parent — is refused instead. Falling back
+ * to the literal path there would let the rename replace the link, recreating the
+ * exact dotfiles-divergence failure this helper exists to prevent (audit: wt4 wp2).
+ */
+export function resolveWriteTarget(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch (cause) {
+    let entry;
+    try {
+      entry = lstatSync(path);
+    } catch (error) {
+      if (isMissingPathError(error)) return path; // no entry at all — first write
+      throw error;
+    }
+    if (entry.isSymbolicLink()) {
+      throw new Error(`refusing to replace unresolvable symlinked write target: ${path}`, { cause });
+    }
+    return path;
+  }
+}
+
+/**
+ * Re-apply the real-home guard to a RESOLVED write target.
+ *
+ * Callers such as saveConfig check only their logical config dir, which passes when
+ * OPENCODEX_HOME points at a temp fixture. Following a symlink out of that fixture
+ * would land on the protected home the caller's own check just cleared, so the guard
+ * has to run again on wherever the write actually terminates. Inert in production,
+ * where the guard is disarmed.
+ */
+function assertResolvedTargetAllowed(path: string, target: string): void {
+  if (target === path) return;
+  assertNotRealHomeUnderTest(dirname(target));
+}
+
 export function atomicWriteFile(path: string, content: string, io: AtomicWriteIO = {
   write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
   harden: target => {
@@ -117,13 +168,15 @@ export function atomicWriteFile(path: string, content: string, io: AtomicWriteIO
   unlink: unlinkSync,
 }): void {
   recordOwnedConfigPath(resolveConfigDir(), path);
-  const tmp = `${path}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
+  const target = resolveWriteTarget(path);
+  assertResolvedTargetAllowed(path, target);
+  const tmp = `${target}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   let hardened = false;
   try {
     io.write(tmp, content);
     io.harden(tmp);
     hardened = true;
-    io.rename(tmp, path);
+    io.rename(tmp, target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
     let scrubbed = false;
@@ -203,13 +256,15 @@ export async function atomicWriteFileAsync(
     truncate: target => truncateSync(target, 0),
     unlink: unlinkSync,
   };
-  const tmp = `${path}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
+  const target = resolveWriteTarget(path);
+  assertResolvedTargetAllowed(path, target);
+  const tmp = `${target}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   let hardened = false;
   try {
     await effective.write(tmp, content);
     await effective.harden(tmp);
     hardened = true;
-    await effective.rename(tmp, path);
+    await effective.rename(tmp, target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
     let scrubbed = false;

src/responses/state.ts

@@ -1,6 +1,6 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { atomicWriteFileAsync, getConfigDir } from "../config";
+import { atomicWriteFileAsync, getConfigDir, resolveWriteTarget } from "../config";
 import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
 import type { OcxProviderContinuationState } from "../types";
 import {
@@ -567,10 +567,23 @@ function ensureLoaded(): void {
   if (loaded) return;
   loaded = true;
   const path = snapshotPath();
+  // Atomic writes place their temp beside the RESOLVED target, so a symlinked
+  // snapshot (dotfiles-managed config dir) strands temps in the link's real
+  // directory where a scan of the literal config dir would never see them.
+  // Both locations are swept; they collapse to one when nothing is symlinked.
+  // resolveWriteTarget refuses a dangling link; snapshot loading stays independent.
+  let resolvedDir = dirname(path);
   try {
-    recoverStaleResponseStateTemps(dirname(path));
+    resolvedDir = dirname(resolveWriteTarget(path));
   } catch {
-    /* best-effort cleanup only; snapshot loading must remain independent */
+    /* unresolvable link: sweep the literal dir only */
+  }
+  for (const dir of new Set([dirname(path), resolvedDir])) {
+    try {
+      recoverStaleResponseStateTemps(dir);
+    } catch {
+      /* best-effort cleanup only; snapshot loading must remain independent */
+    }
   }
   try {
     if (existsSync(path)) {

tests/config.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, truncateSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import {
@@ -27,7 +27,7 @@ import {
 } from "../src/config";
 
 import * as windowsAcl from "../src/lib/windows-secret-acl";
-import { AtomicWriteResidualTempError, atomicWriteFile, hardenConfigDir, hardenExistingSecret, renameAtomicFile, saveConfig } from "../src/config";
+import { AtomicWriteResidualTempError, atomicWriteFile, atomicWriteFileAsync, hardenConfigDir, hardenExistingSecret, renameAtomicFile, saveConfig } from "../src/config";
 let testDir = "";
 
 beforeEach(() => {
@@ -1738,5 +1738,115 @@ describe("config.ts – sync writer timeout keying (#840 refinement)", () => {
       if (previousUsername === undefined) delete process.env.USERNAME;
       else process.env.USERNAME = previousUsername;
     }
+||||||| parent of d8261a286 (fix(config): preserve symlinked destinations in atomic writes)
+describe("config.ts – atomic writes preserve symlinked destinations", () => {
+  test("a symlinked destination survives the write and the real file receives it", () => {
+    // Dotfiles shape: ~/.codex/config.toml -> ~/dotfiles/.codex/config.toml
+    const repoDir = join(testDir, "dotfiles");
+    mkdirSync(repoDir, { recursive: true });
+    const realFile = join(repoDir, "config.toml");
+    writeFileSync(realFile, "original", "utf-8");
+    const link = join(testDir, "config.toml");
+    symlinkSync(realFile, link);
+
+    atomicWriteFile(link, "rewritten");
+
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(link)).toBe(realFile);
+    expect(readFileSync(realFile, "utf8")).toBe("rewritten");
+    expect(readFileSync(link, "utf8")).toBe("rewritten");
+  });
+
+  test("no temp file is left beside the link or its target", () => {
+    const repoDir = join(testDir, "dotfiles-clean");
+    mkdirSync(repoDir, { recursive: true });
+    const realFile = join(repoDir, "config.toml");
+    writeFileSync(realFile, "original", "utf-8");
+    const link = join(testDir, "config-clean.toml");
+    symlinkSync(realFile, link);
+
+    atomicWriteFile(link, "rewritten");
+
+    expect(readdirSync(repoDir).filter(name => name.includes(".ocx."))).toEqual([]);
+    expect(readdirSync(testDir).filter(name => name.includes(".ocx."))).toEqual([]);
+  });
+
+  test("a plain destination is unaffected", () => {
+    const destination = join(testDir, "plain.toml");
+    atomicWriteFile(destination, "first");
+    atomicWriteFile(destination, "second");
+
+    expect(lstatSync(destination).isSymbolicLink()).toBe(false);
+    expect(readFileSync(destination, "utf8")).toBe("second");
+  });
+
+  test("a destination that does not exist yet is created at the literal path", () => {
+    const destination = join(testDir, "created.toml");
+    expect(existsSync(destination)).toBe(false);
+
+    atomicWriteFile(destination, "fresh");
+
+    expect(readFileSync(destination, "utf8")).toBe("fresh");
+  });
+
+  test("a dangling symlink is preserved and the write is refused", () => {
+    const link = join(testDir, "dangling.toml");
+    symlinkSync(join(testDir, "gone", "config.toml"), link);
+
+    // The target volume may only be temporarily unavailable; replacing the link
+    // would recreate the dotfiles divergence this fix exists to prevent.
+    expect(() => atomicWriteFile(link, "recovered")).toThrow(/unresolvable symlinked write target/);
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(existsSync(join(testDir, "gone"))).toBe(false);
+  });
+});
+
+describe("config.ts – async atomic writes preserve symlinked destinations", () => {
+  test("a symlinked destination survives the write and the real file receives it", async () => {
+    const repoDir = join(testDir, "dotfiles-async");
+    mkdirSync(repoDir, { recursive: true });
+    const realFile = join(repoDir, "config.toml");
+    writeFileSync(realFile, "original", "utf-8");
+    const link = join(testDir, "config-async.toml");
+    symlinkSync(realFile, link);
+
+    await atomicWriteFileAsync(link, "rewritten");
+
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(link)).toBe(realFile);
+    expect(readFileSync(realFile, "utf8")).toBe("rewritten");
+    expect(readFileSync(link, "utf8")).toBe("rewritten");
+  });
+
+  test("no temp file is left beside the link or its target", async () => {
+    const repoDir = join(testDir, "dotfiles-async-clean");
+    mkdirSync(repoDir, { recursive: true });
+    const realFile = join(repoDir, "config.toml");
+    writeFileSync(realFile, "original", "utf-8");
+    const link = join(testDir, "config-async-clean.toml");
+    symlinkSync(realFile, link);
+
+    await atomicWriteFileAsync(link, "rewritten");
+
+    expect(readdirSync(repoDir).filter(name => name.includes(".ocx."))).toEqual([]);
+    expect(readdirSync(testDir).filter(name => name.includes(".ocx."))).toEqual([]);
+  });
+
+  test("a plain destination is unaffected", async () => {
+    const destination = join(testDir, "plain-async.toml");
+    await atomicWriteFileAsync(destination, "first");
+    await atomicWriteFileAsync(destination, "second");
+
+    expect(lstatSync(destination).isSymbolicLink()).toBe(false);
+    expect(readFileSync(destination, "utf8")).toBe("second");
+  });
+
+  test("a dangling symlink is preserved and the write is refused", async () => {
+    const link = join(testDir, "dangling-async.toml");
+    symlinkSync(join(testDir, "gone-async", "config.toml"), link);
+
+    await expect(atomicWriteFileAsync(link, "recovered")).rejects.toThrow(/unresolvable symlinked write target/);
+    expect(lstatSync(link).isSymbolicLink()).toBe(true);
+    expect(existsSync(join(testDir, "gone-async"))).toBe(false);
   });
 });

tests/responses-state.test.ts

@@ -1449,6 +1449,27 @@ describe("Responses previous_response_id state", () => {
     for (const path of [live, current, young, unrelated, directory]) expect(existsSync(path)).toBe(true);
   });
 
+  test("load sweeps stale temps in a symlinked snapshot's real directory", () => {
+    // Atomic writes place their temp beside the RESOLVED target, so a dotfiles-managed
+    // config dir strands temps where a scan of the literal home would never find them.
+    const realDir = mkdtempSync(join(tmpdir(), "ocx-state-real-"));
+    const realSnapshot = join(realDir, "responses-state.json");
+    writeFileSync(realSnapshot, JSON.stringify({ version: 2, states: [] }));
+    symlinkSync(realSnapshot, join(home, "responses-state.json"));
+
+    const deadPid = process.pid === 4242 ? 4243 : 4242;
+    const stranded = join(realDir, `responses-state.json.ocx.${deadPid}.1.tmp`);
+    writeFileSync(stranded, "private state");
+    const old = new Date(Date.now() - 60 * 60 * 1_000);
+    utimesSync(stranded, old, old);
+
+    clearResponseStateMemoryForTests();
+    previousResponseProviderState("trigger-load");
+
+    expect(existsSync(stranded)).toBe(false);
+    rmSync(realDir, { recursive: true, force: true });
+  });
+
   test("stale temp recovery is best-effort when unlink fails", () => {
     const deadPid = process.pid === 4242 ? 4243 : 4242;
     const path = join(home, `responses-state.json.ocx.${deadPid}.1.tmp`);

tests/test-home-guard.test.ts

@@ -93,6 +93,32 @@ describe("real-home write guard", () => {
     expect(() => readFileSync(join(opencodexHome, "codex-accounts.json"))).toThrow();
   });
 
+  test("armed + a symlink escaping a temp home into the protected home: refused", () => {
+    // Atomic writes resolve their destination through symlinks, so a temp home whose
+    // config.json points into the protected home would otherwise pass the caller's
+    // dir-level check and then write the real file anyway.
+    const { realHome, opencodexHome } = sentinelHome();
+    const protectedFile = join(opencodexHome, "config.json");
+    writeFileSync(protectedFile, '{"sentinel":true}', "utf8");
+    const dir = mkdtempSync(join(tmpdir(), "ocx-escape-home-"));
+    symlinkSync(protectedFile, join(dir, "config.json"));
+
+    const probe = runProbe(`
+      import { saveConfig } from "${REPO_ROOT_URL}src/config";
+      const REFUSAL = "refusing to write the real OpenCodex home";
+      try {
+        saveConfig({ providers: {}, defaultProvider: "openai", port: 10100 } as never);
+        console.log("wrote");
+      } catch (err) {
+        console.log(String(err).includes(REFUSAL) ? "refused" : "other");
+      }
+    `, { OCX_TEST_HOME_GUARD: "1", OCX_REAL_HOME: realHome, OPENCODEX_HOME: dir });
+
+    expect(probe.stdout).toContain("refused");
+    // The protected file must be byte-for-byte untouched.
+    expect(readFileSync(protectedFile, "utf8")).toBe('{"sentinel":true}');
+  });
+
   test("armed + an unregistered temp home: writers succeed", () => {
     // The 54 suites that mkdtemp their own home must keep working with no opt-in.
     const dir = mkdtempSync(join(tmpdir(), "ocx-plain-home-"));