fix: guard resolved write targets and sweep their stale temps

Two follow-ups from review of the symlink-preservation change.

Re-check the real-home guard against the resolved target. Callers such as
saveConfig validate only their logical config dir, which passes when
OPENCODEX_HOME points at a temp fixture. Resolving a symlink out of that
fixture could then land on the protected home the caller had just
cleared, so the guard now runs again on wherever the write actually
terminates. Inert in production, where the guard is disarmed.

Sweep stale response-state temps in the resolved directory too. Temps are
created beside the resolved target, so a symlinked responses-state.json
stranded them in the link's real directory while startup recovery only
scanned the literal config dir. A crash between write and rename would
have left a private snapshot temp there permanently. Both directories are
now swept, collapsing to one when nothing is symlinked.

Also assert the dangling-symlink cases replace the link rather than
following it: reading through the link passed either way.

Author: nicosuave

src/config.ts

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { chmodSync, copyFileSync, existsSync, linkSync, 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 {
@@ -118,14 +118,28 @@ function isMissingPathError(error: unknown): boolean {
  * resolved target. An unresolvable path (not yet created) falls back to the literal
  * path, which is the correct target for a first write.
  */
-function resolveWriteTarget(path: string): string {
+export function resolveWriteTarget(path: string): string {
   try {
     return realpathSync(path);
   } catch {
     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 => {
@@ -138,6 +152,7 @@ export function atomicWriteFile(path: string, content: string, io: AtomicWriteIO
 }): void {
   recordOwnedConfigPath(resolveConfigDir(), path);
   const target = resolveWriteTarget(path);
+  assertResolvedTargetAllowed(path, target);
   const tmp = `${target}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   let hardened = false;
   try {
@@ -225,6 +240,7 @@ export async function atomicWriteFileAsync(
     unlink: unlinkSync,
   };
   const target = resolveWriteTarget(path);
+  assertResolvedTargetAllowed(path, target);
   const tmp = `${target}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   let hardened = false;
   try {

src/responses/state.ts

@@ -1,6 +1,6 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, rmSync, 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 {
@@ -454,10 +454,16 @@ function ensureLoaded(): void {
   if (loaded) return;
   loaded = true;
   const path = snapshotPath();
-  try {
-    recoverStaleResponseStateTemps(dirname(path));
-  } catch {
-    /* best-effort cleanup only; snapshot loading must remain independent */
+  // 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.
+  for (const dir of new Set([dirname(path), dirname(resolveWriteTarget(path))])) {
+    try {
+      recoverStaleResponseStateTemps(dir);
+    } catch {
+      /* best-effort cleanup only; snapshot loading must remain independent */
+    }
   }
   try {
     if (existsSync(path)) {

tests/config.test.ts

@@ -1726,6 +1726,9 @@ describe("config.ts – atomic writes preserve symlinked destinations", () => {
 
     atomicWriteFile(link, "recovered");
 
+    // Reading through the link cannot distinguish "link replaced" from "link kept,
+    // target created", so assert the link itself is gone.
+    expect(lstatSync(link).isSymbolicLink()).toBe(false);
     expect(readFileSync(link, "utf8")).toBe("recovered");
   });
 });
@@ -1776,6 +1779,9 @@ describe("config.ts – async atomic writes preserve symlinked destinations", ()
 
     await atomicWriteFileAsync(link, "recovered");
 
+    // Reading through the link cannot distinguish "link replaced" from "link kept,
+    // target created", so assert the link itself is gone.
+    expect(lstatSync(link).isSymbolicLink()).toBe(false);
     expect(readFileSync(link, "utf8")).toBe("recovered");
   });
 });

tests/responses-state.test.ts

@@ -1418,6 +1418,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-"));