fix(install): disable Claude Code auto-memory on every claude-code install

Disable Claude Code auto-memory during claude-code installs and harden atomic settings writes, including symlink and dangling-symlink destinations.

src/npx-cli/commands/install.ts

@@ -135,6 +135,31 @@ function enablePluginInClaudeSettings(): void {
   writeJsonFileAtomic(claudeSettingsPath(), settings);
 }
 
+/**
+ * Disable Claude Code's built-in auto-memory by setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
+ * in ~/.claude/settings.json `env` block. claude-mem provides its own persistent memory
+ * via plugin hooks; the built-in MEMORY.md system creates shadow state outside the user's
+ * control and competes with claude-mem for context window tokens.
+ *
+ * Per anthropics/claude-code#23544, the env var is the only supported toggle.
+ *
+ * Idempotent: only writes when not already set, preserves existing env vars and other
+ * settings keys, and merges atomically. Returns true when a write happened (for the
+ * caller to surface in the install summary).
+ */
+export function disableClaudeAutoMemory(): boolean {
+  const settings = readJsonSafe<Record<string, any>>(claudeSettingsPath(), {});
+  const env = (settings.env && typeof settings.env === 'object') ? settings.env : {};
+
+  if (env.CLAUDE_CODE_DISABLE_AUTO_MEMORY === '1') {
+    return false;
+  }
+
+  settings.env = { ...env, CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1' };
+  writeJsonFileAtomic(claudeSettingsPath(), settings);
+  return true;
+}
+
 function makeIDETask(ideId: string, failedIDEs: string[], pendingErrors: string[]): TaskDescriptor | null {
   const recordFailure = (label: string, output: string) => {
     failedIDEs.push(ideId);
@@ -1116,6 +1141,30 @@ export async function runInstallCommand(options: InstallOptions = {}): Promise<v
 
   const failedIDEs = await setupIDEs(selectedIDEs);
 
+  // Disable Claude Code's built-in auto-memory (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1)
+  // for any install that targets claude-code. claude-mem's hook-based memory is the
+  // intended source of cross-session context; the built-in MEMORY.md system creates
+  // shadow state and competes for context-window tokens.
+  // Tri-state so the summary can distinguish "wrote", "already set", and "failed".
+  // A boolean would conflate the error path with "already set", which is misleading
+  // when a write fails mid-install (the warn would say one thing, the summary another).
+  let autoMemoryStatus: 'disabled' | 'already-disabled' | 'failed' | null = null;
+  if (selectedIDEs.includes('claude-code')) {
+    try {
+      const wrote = disableClaudeAutoMemory();
+      autoMemoryStatus = wrote ? 'disabled' : 'already-disabled';
+      if (wrote) {
+        log.success('Claude Code: auto-memory disabled (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1).');
+      } else {
+        log.info('Claude Code: auto-memory already disabled, leaving settings.json untouched.');
+      }
+    } catch (error: unknown) {
+      // Don't fail the install over this — surface the warning and continue.
+      autoMemoryStatus = 'failed';
+      log.warn(`Could not disable Claude Code auto-memory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
   const autoStartSkipped = !isInteractive || options.noAutoStart;
 
   await runTasks([
@@ -1151,6 +1200,13 @@ export async function runInstallCommand(options: InstallOptions = {}): Promise<v
     `Plugin dir:  ${pc.cyan(marketplaceDir)}`,
     `IDEs:        ${pc.cyan(selectedIDEs.join(', '))}`,
   ];
+  if (autoMemoryStatus === 'disabled') {
+    summaryLines.push(`Auto-memory: ${pc.cyan('disabled')} (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1)`);
+  } else if (autoMemoryStatus === 'already-disabled') {
+    summaryLines.push(`Auto-memory: ${pc.cyan('already disabled')} (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1)`);
+  } else if (autoMemoryStatus === 'failed') {
+    summaryLines.push(`Auto-memory: ${pc.red('write failed')} (see warning above)`);
+  }
   if (failedIDEs.length > 0) {
     summaryLines.push(`Failed:      ${pc.red(failedIDEs.join(', '))}`);
   }

src/npx-cli/utils/paths.ts

@@ -1,7 +1,22 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from 'fs';
 import { homedir } from 'os';
-import { dirname, join } from 'path';
+import { basename, dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { randomBytes } from 'crypto';
 
 export const IS_WINDOWS = process.platform === 'win32';
 
@@ -86,7 +101,105 @@ export function ensureDirectoryExists(directoryPath: string): void {
 
 export { readJsonSafe } from '../../utils/json-utils.js';
 
+/**
+ * Write JSON to disk with crash-safe atomic-rename semantics.
+ *
+ * Sequence: resolve symlinks at the destination, write payload to a uniquely
+ * named temp file in the same directory as the resolved target, loop writeSync
+ * until the full payload is on disk, fsync the fd, close, rename over the
+ * resolved target, then fsync the parent directory for crash durability. The
+ * rename is atomic on POSIX and on Windows Vista+ (Node uses
+ * MoveFileExW/MOVEFILE_REPLACE_EXISTING under the hood). A crash mid-write
+ * leaves either the old contents or the new contents — never a truncated file.
+ *
+ * Symlink-safe: POSIX rename(2) replaces the symlink itself rather than the
+ * target file, so a naive rename over a symlinked destination would break the
+ * link. We lstat/realpath up front so the temp file lives next to the real
+ * target and the rename writes through the link.
+ *
+ * Preserves the destination file's mode bits when the file already exists so
+ * we don't accidentally widen permissions on user-owned configs like
+ * ~/.claude/settings.json.
+ */
 export function writeJsonFileAtomic(filepath: string, data: any): void {
-  ensureDirectoryExists(dirname(filepath));
+  // POSIX rename(2) operates on the symlink itself, so an atomic rename over
-  writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  // a symlinked destination would replace the link rather than writing through
+  // it. Resolve up front so temp + rename both live on the real target's fs.
+  let resolved = filepath;
+  try {
+    if (lstatSync(filepath).isSymbolicLink()) {
+      try {
+        resolved = realpathSync(filepath);
+      } catch {
+        const linkTarget = readlinkSync(filepath);
+        resolved = resolve(dirname(filepath), linkTarget);
+      }
+    }
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+      throw err;
+    }
+    // Destination doesn't exist yet - write directly to the literal path.
+  }
+
+  ensureDirectoryExists(dirname(resolved));
+
+  const dir = dirname(resolved);
+  const base = basename(resolved);
+  const tmpPath = join(dir, `.${base}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  const payload = Buffer.from(JSON.stringify(data, null, 2) + '\n', 'utf-8');
+
+  // Preserve existing mode if the destination already exists; otherwise let
+  // the OS apply the standard new-file default (0o666 minus umask via openSync).
+  let mode: number | undefined;
+  try {
+    mode = statSync(resolved).mode & 0o777;
+  } catch {
+    // File doesn't exist yet — fall through to default mode.
+  }
+
+  let fd: number | undefined;
+  try {
+    fd = mode !== undefined ? openSync(tmpPath, 'w', mode) : openSync(tmpPath, 'w');
+
+    // writeSync wraps POSIX write(2), which may short-write — loop until the
+    // full payload is committed before fsync.
+    let written = 0;
+    while (written < payload.length) {
+      const n = writeSync(fd, payload, written, payload.length - written);
+      if (n === 0) {
+        throw new Error(`writeSync stalled at ${written}/${payload.length} bytes`);
+      }
+      written += n;
+    }
+
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmpPath, resolved);
+
+    // fsync the parent directory so the rename's directory-entry change
+    // survives a crash. Best-effort: Windows can't fsync a directory and
+    // some filesystems disallow it — skip silently in those cases.
+    if (!IS_WINDOWS) {
+      let dirFd: number | undefined;
+      try {
+        dirFd = openSync(dir, 'r');
+        fsyncSync(dirFd);
+      } catch {
+        // Best-effort durability.
+      } finally {
+        if (dirFd !== undefined) {
+          try { closeSync(dirFd); } catch { /* ignore */ }
+        }
+      }
+    }
+  } catch (err) {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* ignore close-after-error */ }
+    }
+    try { unlinkSync(tmpPath); } catch { /* tempfile may not exist */ }
+    throw err;
+  }
 }

tests/install-disable-auto-memory.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { disableClaudeAutoMemory } from '../src/npx-cli/commands/install.js';
+
+/**
+ * Tests for auto-memory disable behavior in the install command.
+ *
+ * Closes anthropics/claude-code#23544 from claude-mem's side: any install that
+ * targets claude-code must set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in
+ * ~/.claude/settings.json `env` block. The built-in MEMORY.md system creates
+ * shadow state outside the user's control and competes with claude-mem's
+ * hook-based memory for context-window tokens.
+ *
+ * Source-inspection style mirrors install-non-tty.test.ts — disableClaudeAutoMemory
+ * is a private module-level helper that can't be imported directly.
+ */
+
+const installSourcePath = join(
+  __dirname,
+  '..',
+  'src',
+  'npx-cli',
+  'commands',
+  'install.ts',
+);
+const installSource = readFileSync(installSourcePath, 'utf-8');
+
+describe('Install: disable Claude Code auto-memory', () => {
+  describe('disableClaudeAutoMemory helper', () => {
+    it('defines the helper function', () => {
+      expect(installSource).toContain('function disableClaudeAutoMemory()');
+    });
+
+    it('writes CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to settings.json env block', () => {
+      // The string '1' (not boolean true) is required — env vars are always strings.
+      expect(installSource).toMatch(/CLAUDE_CODE_DISABLE_AUTO_MEMORY:\s*['"]1['"]/);
+    });
+
+    it('reads existing settings via readJsonSafe (preserves other keys)', () => {
+      // Must round-trip through readJsonSafe + writeJsonFileAtomic, never overwrite blindly.
+      const helperBody = installSource.match(
+        /function disableClaudeAutoMemory\(\)[\s\S]*?\n\}/,
+      )?.[0];
+      expect(helperBody).toBeDefined();
+      expect(helperBody).toContain('readJsonSafe');
+      expect(helperBody).toContain('writeJsonFileAtomic(claudeSettingsPath()');
+    });
+
+    it('merges with existing env vars instead of replacing the env block', () => {
+      // Spread of existing env into new env is what preserves user-set vars
+      // like ANTHROPIC_AUTH_TOKEN, AWS_REGION, etc.
+      const helperBody = installSource.match(
+        /function disableClaudeAutoMemory\(\)[\s\S]*?\n\}/,
+      )?.[0];
+      expect(helperBody).toMatch(/\.\.\.env/);
+    });
+
+    it('is idempotent — returns false (no write) when already set to "1"', () => {
+      const helperBody = installSource.match(
+        /function disableClaudeAutoMemory\(\)[\s\S]*?\n\}/,
+      )?.[0];
+      expect(helperBody).toMatch(/CLAUDE_CODE_DISABLE_AUTO_MEMORY === ['"]1['"]/);
+      expect(helperBody).toMatch(/return false/);
+    });
+
+    it('returns true after a successful write', () => {
+      const helperBody = installSource.match(
+        /function disableClaudeAutoMemory\(\)[\s\S]*?\n\}/,
+      )?.[0];
+      expect(helperBody).toMatch(/return true/);
+    });
+  });
+
+  describe('runInstallCommand integration', () => {
+    it('calls disableClaudeAutoMemory after setupIDEs', () => {
+      // setupIDEs returns first; we need its result before deciding what to do,
+      // and the disable step shouldn't run if claude-code wasn't installed.
+      // Use lastIndexOf for the call so we match the call site, not the helper definition.
+      const setupCallIdx = installSource.indexOf('await setupIDEs(selectedIDEs)');
+      const disableCallIdx = installSource.lastIndexOf('disableClaudeAutoMemory()');
+      expect(setupCallIdx).toBeGreaterThan(-1);
+      expect(disableCallIdx).toBeGreaterThan(-1);
+      expect(disableCallIdx).toBeGreaterThan(setupCallIdx);
+    });
+
+    it("only runs the disable step when claude-code is in selectedIDEs", () => {
+      // Cursor/Codex/Windsurf installs shouldn't touch ~/.claude/settings.json
+      // for an env var that doesn't apply to them.
+      expect(installSource).toMatch(
+        /selectedIDEs\.includes\(['"]claude-code['"]\)[\s\S]{0,200}disableClaudeAutoMemory\(\)/,
+      );
+    });
+
+    it('catches errors from disableClaudeAutoMemory and continues', () => {
+      // Settings.json is the user's file — a write failure (permissions, disk
+      // full, etc.) must surface as a warning, not abort the install.
+      const integrationBlock = installSource.match(
+        /selectedIDEs\.includes\(['"]claude-code['"]\)[\s\S]{0,800}/,
+      )?.[0];
+      expect(integrationBlock).toBeDefined();
+      expect(integrationBlock).toContain('try {');
+      expect(integrationBlock).toMatch(/const wrote = disableClaudeAutoMemory\(\)/);
+      expect(integrationBlock).toContain('catch');
+      expect(integrationBlock).toMatch(/log\.warn/);
+    });
+
+    it('tracks a tri-state autoMemoryStatus (disabled / already-disabled / failed)', () => {
+      // A boolean would conflate the error path with "already set", so a write
+      // failure mid-install would silently render "already disabled" in the
+      // summary while the warning above said the opposite. Tri-state keeps the
+      // log line and the summary line truthful and consistent.
+      expect(installSource).toMatch(
+        /let autoMemoryStatus:\s*['"]disabled['"]\s*\|\s*['"]already-disabled['"]\s*\|\s*['"]failed['"]\s*\|\s*null/,
+      );
+      const integrationBlock = installSource.match(
+        /selectedIDEs\.includes\(['"]claude-code['"]\)[\s\S]{0,800}/,
+      )?.[0];
+      expect(integrationBlock).toMatch(/autoMemoryStatus = wrote \? ['"]disabled['"] : ['"]already-disabled['"]/);
+      expect(integrationBlock).toMatch(/autoMemoryStatus = ['"]failed['"]/);
+    });
+
+    it('surfaces all three states in the install summary distinctly', () => {
+      // The error case must NOT render as "already disabled" — that would
+      // contradict the warn line above it and falsely imply the env var is set.
+      expect(installSource).toMatch(
+        /autoMemoryStatus === ['"]disabled['"][\s\S]{0,200}CLAUDE_CODE_DISABLE_AUTO_MEMORY=1/,
+      );
+      expect(installSource).toMatch(
+        /autoMemoryStatus === ['"]already-disabled['"][\s\S]{0,200}already disabled/,
+      );
+      expect(installSource).toMatch(
+        /autoMemoryStatus === ['"]failed['"][\s\S]{0,200}write failed/,
+      );
+    });
+  });
+
+  // Behavioral test that exercises real file I/O against a temp Claude config dir.
+  // Complements the source-inspection tests above: catches runtime bugs (overwriting
+  // env block, dropping existing keys, non-string values, etc.) that string matching
+  // can't see. Uses CLAUDE_CONFIG_DIR override so we don't touch the user's settings.
+  describe('disableClaudeAutoMemory runtime behavior', () => {
+    let tempDir: string;
+    let originalConfigDir: string | undefined;
+
+    beforeEach(() => {
+      tempDir = mkdtempSync(join(tmpdir(), 'claude-mem-disable-auto-memory-'));
+      originalConfigDir = process.env.CLAUDE_CONFIG_DIR;
+      process.env.CLAUDE_CONFIG_DIR = tempDir;
+    });
+
+    afterEach(() => {
+      if (originalConfigDir === undefined) {
+        delete process.env.CLAUDE_CONFIG_DIR;
+      } else {
+        process.env.CLAUDE_CONFIG_DIR = originalConfigDir;
+      }
+      rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it('writes the env var when settings.json is missing', () => {
+      const wrote = disableClaudeAutoMemory();
+      expect(wrote).toBe(true);
+
+      const settings = JSON.parse(readFileSync(join(tempDir, 'settings.json'), 'utf-8'));
+      expect(settings.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY).toBe('1');
+    });
+
+    it('preserves existing env vars and other top-level keys', () => {
+      writeFileSync(
+        join(tempDir, 'settings.json'),
+        JSON.stringify({
+          theme: 'dark',
+          env: {
+            ANTHROPIC_AUTH_TOKEN: 'sk-test',
+            AWS_REGION: 'us-east-1',
+          },
+          permissions: { defaultMode: 'auto' },
+        }, null, 2),
+      );
+
+      const wrote = disableClaudeAutoMemory();
+      expect(wrote).toBe(true);
+
+      const settings = JSON.parse(readFileSync(join(tempDir, 'settings.json'), 'utf-8'));
+      expect(settings.theme).toBe('dark');
+      expect(settings.permissions).toEqual({ defaultMode: 'auto' });
+      expect(settings.env.ANTHROPIC_AUTH_TOKEN).toBe('sk-test');
+      expect(settings.env.AWS_REGION).toBe('us-east-1');
+      expect(settings.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY).toBe('1');
+    });
+
+    it('is idempotent — second call returns false and leaves the file untouched', () => {
+      const firstWrite = disableClaudeAutoMemory();
+      expect(firstWrite).toBe(true);
+
+      const settingsPath = join(tempDir, 'settings.json');
+      const contentBefore = readFileSync(settingsPath, 'utf-8');
+
+      const secondWrite = disableClaudeAutoMemory();
+      expect(secondWrite).toBe(false);
+
+      const contentAfter = readFileSync(settingsPath, 'utf-8');
+      expect(contentAfter).toBe(contentBefore);
+    });
+
+    it('writes the literal string "1", not boolean true', () => {
+      // Env vars are always strings — boolean true would be coerced unpredictably
+      // by Claude Code's env loader.
+      disableClaudeAutoMemory();
+      const raw = readFileSync(join(tempDir, 'settings.json'), 'utf-8');
+      expect(raw).toMatch(/"CLAUDE_CODE_DISABLE_AUTO_MEMORY":\s*"1"/);
+      expect(raw).not.toMatch(/"CLAUDE_CODE_DISABLE_AUTO_MEMORY":\s*true/);
+    });
+
+    it('replaces a non-object env value with a fresh env block', () => {
+      // Defensive: if settings.env is malformed (string, null, array), the helper
+      // still has to land on a valid object containing the env var.
+      writeFileSync(
+        join(tempDir, 'settings.json'),
+        JSON.stringify({ env: 'not-an-object', theme: 'dark' }),
+      );
+
+      const wrote = disableClaudeAutoMemory();
+      expect(wrote).toBe(true);
+
+      const settings = JSON.parse(readFileSync(join(tempDir, 'settings.json'), 'utf-8'));
+      expect(settings.theme).toBe('dark');
+      expect(typeof settings.env).toBe('object');
+      expect(settings.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY).toBe('1');
+    });
+  });
+});

tests/write-json-file-atomic.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { IS_WINDOWS, writeJsonFileAtomic } from '../src/npx-cli/utils/paths.js';
+
+/**
+ * Tests for writeJsonFileAtomic's crash-safe semantics.
+ *
+ * Per CodeRabbit on PR #2281: the prior implementation was a single
+ * writeFileSync call that could leave a truncated/corrupt file on a mid-write
+ * crash — relevant because callers include disableClaudeAutoMemory's write to
+ * ~/.claude/settings.json (a user-owned global config).
+ *
+ * The new implementation uses temp file + fsync + rename. These tests verify
+ * that contract.
+ */
+
+describe('writeJsonFileAtomic', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'claude-mem-atomic-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('writes JSON to the destination path with a trailing newline', () => {
+    const target = join(tempDir, 'config.json');
+    writeJsonFileAtomic(target, { foo: 'bar', n: 1 });
+    const raw = readFileSync(target, 'utf-8');
+    expect(raw).toBe('{\n  "foo": "bar",\n  "n": 1\n}\n');
+  });
+
+  it('replaces existing content without leaving a temp file behind', () => {
+    const target = join(tempDir, 'config.json');
+    writeJsonFileAtomic(target, { v: 1 });
+    writeJsonFileAtomic(target, { v: 2 });
+    expect(JSON.parse(readFileSync(target, 'utf-8'))).toEqual({ v: 2 });
+
+    // No leftover .tmp files should remain in the directory.
+    const leftovers = readdirSync(tempDir).filter(name => name.endsWith('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('creates parent directories when they do not exist', () => {
+    const target = join(tempDir, 'nested', 'deeper', 'config.json');
+    writeJsonFileAtomic(target, { ok: true });
+    expect(JSON.parse(readFileSync(target, 'utf-8'))).toEqual({ ok: true });
+  });
+
+  it('preserves the destination file mode when the file already exists', () => {
+    const target = join(tempDir, 'restricted.json');
+    writeFileSync(target, '{}', { mode: 0o600 });
+    chmodSync(target, 0o600); // Force-apply in case umask interfered.
+
+    writeJsonFileAtomic(target, { secret: true });
+
+    const mode = statSync(target).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  it('writes the temp file in the same directory as the destination', () => {
+    // Same-directory rename is what gives the atomic guarantee on POSIX
+    // (cross-filesystem rename can fall back to copy+delete, which isn't atomic).
+    // We verify by spotting the temp file name pattern during a write — but since
+    // the write completes synchronously, we infer this from the absence of any
+    // leftover temp file in OTHER directories after a normal write.
+    const otherDir = mkdtempSync(join(tmpdir(), 'claude-mem-atomic-other-'));
+    try {
+      const target = join(tempDir, 'config.json');
+      writeJsonFileAtomic(target, { ok: true });
+
+      // No temp file should have been created in tmpdir, otherDir, or anywhere
+      // outside the destination directory.
+      const otherLeftovers = readdirSync(otherDir).filter(name => name.includes('config.json'));
+      expect(otherLeftovers).toEqual([]);
+      const tempDirLeftovers = readdirSync(tempDir).filter(name => name.endsWith('.tmp'));
+      expect(tempDirLeftovers).toEqual([]);
+    } finally {
+      rmSync(otherDir, { recursive: true, force: true });
+    }
+  });
+
+  it('throws on serialization failure without creating a temp file', () => {
+    // A circular structure makes JSON.stringify throw before openSync runs,
+    // so no temp file should ever appear in the destination directory.
+    const target = join(tempDir, 'config.json');
+    const circular: any = { a: 1 };
+    circular.self = circular;
+
+    expect(() => writeJsonFileAtomic(target, circular)).toThrow();
+
+    const leftovers = readdirSync(tempDir).filter(name => name.endsWith('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('writes through a symlinked destination instead of replacing the link', () => {
+    if (IS_WINDOWS) {
+      // Symlink creation requires elevated privileges on Windows; skip there.
+      return;
+    }
+    // Users who keep ~/.claude/settings.json under a dotfiles repo often
+    // symlink it. POSIX rename(2) replaces the symlink with the temp file,
+    // which would silently break the link — verify we resolve it instead.
+    const realDir = mkdtempSync(join(tmpdir(), 'claude-mem-real-'));
+    try {
+      const realTarget = join(realDir, 'real-config.json');
+      writeFileSync(realTarget, '{"v":0}');
+      const linkPath = join(tempDir, 'config.json');
+      symlinkSync(realTarget, linkPath);
+
+      writeJsonFileAtomic(linkPath, { v: 42 });
+
+      // Underlying file is updated.
+      expect(JSON.parse(readFileSync(realTarget, 'utf-8'))).toEqual({ v: 42 });
+      // Symlink is preserved (not clobbered into a regular file).
+      expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+      // And it still resolves to the same realpath.
+      expect(realpathSync(linkPath)).toBe(realpathSync(realTarget));
+      // Temp file landed next to the real target, not at the symlink site.
+      const realDirLeftovers = readdirSync(realDir).filter(name => name.endsWith('.tmp'));
+      expect(realDirLeftovers).toEqual([]);
+      const tempDirLeftovers = readdirSync(tempDir).filter(name => name.endsWith('.tmp'));
+      expect(tempDirLeftovers).toEqual([]);
+    } finally {
+      rmSync(realDir, { recursive: true, force: true });
+    }
+  });
+
+  it('writes through a dangling symlink destination instead of replacing the link', () => {
+    if (IS_WINDOWS) {
+      // Symlink creation requires elevated privileges on Windows; skip there.
+      return;
+    }
+
+    const linkTarget = join('dotfiles', 'settings.json');
+    const realTarget = join(tempDir, linkTarget);
+    const linkPath = join(tempDir, 'settings.json');
+    symlinkSync(linkTarget, linkPath);
+
+    writeJsonFileAtomic(linkPath, { env: { CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1' } });
+
+    expect(JSON.parse(readFileSync(realTarget, 'utf-8'))).toEqual({
+      env: { CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1' },
+    });
+    expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+    expect(realpathSync(linkPath)).toBe(realpathSync(realTarget));
+    const tempDirLeftovers = readdirSync(tempDir).filter(name => name.endsWith('.tmp'));
+    expect(tempDirLeftovers).toEqual([]);
+    const realDirLeftovers = readdirSync(join(tempDir, 'dotfiles')).filter(name => name.endsWith('.tmp'));
+    expect(realDirLeftovers).toEqual([]);
+  });
+
+  it('cleans up the temp file when the rename step fails', () => {
+    // Force the catch-block cleanup path: pre-create a directory at the
+    // destination so renameSync(tmpPath, filepath) fails (EISDIR/ENOTDIR).
+    // By that point the temp file has already been opened, written, fsync'd,
+    // and closed — so the catch must unlinkSync the leftover .tmp file.
+    const target = join(tempDir, 'config.json');
+    mkdirSync(target);
+
+    expect(() => writeJsonFileAtomic(target, { v: 1 })).toThrow();
+
+    const leftovers = readdirSync(tempDir).filter(name => name.endsWith('.tmp'));
+    expect(leftovers).toEqual([]);
+    // The pre-existing directory should still be there — we didn't clobber it.
+    expect(statSync(target).isDirectory()).toBe(true);
+  });
+});