title: "fix: atomic_replace() fails with EXDEV when HERMES_HOME is a cross-filesystem symlink" labels: ["bug", "gateway"]

Description

atomic_replace() in utils.py uses os.replace() to atomically move a temp file onto the target path. However, when ~/.hermes/ is a symlink pointing to a different filesystem (e.g., /mnt/data/hermes-data/), os.replace() raises OSError: [Errno 18] Invalid cross-device link because the temp file (created on rootfs) and the target (on a different mount) are on different filesystems.

Impact

• hermes model and hermes config commands crash with OSError: [Errno 18]
• Gateway fails to persist dedup state (feishu_seen_message_ids.json) silently
• Channel directory state is lost on gateway restart
• Users with ~/.hermes -> /mnt/data/... symlinks cannot use the agent at all

Reproduction

# Setup: HERMES_HOME symlink to a different filesystem
ln -sf /mnt/data/hermes-data ~/.hermes
hermes config set model.default test  # Fails with EXDEV

Or in ~/.hermes/hermes-agent:

python3 -c "
import tempfile, os
tmp = tempfile.NamedTemporaryFile(delete=False, suffix='.tmp')
tmp.write(b'test')
tmp.close()
os.replace(tmp.name, os.path.expanduser('~/.hermes/.env'))
# OSError: [Errno 18] Invalid cross-device link
"

Root Cause

https://github.com/NousResearch/hermes-agent/blob/main/utils.py#L77-L86

def atomic_replace(tmp_path, target):
    real_path = os.path.realpath(target_str) if os.path.islink(target_str) else target_str
    os.replace(str(tmp_path), real_path)  # ← fails with EXDEV on cross-fs
    return real_path

os.replace() (backed by rename() syscall) cannot move files across mount points. The fix should fall back to shutil.move() when errno == 18 (EXDEV).

Proposed Fix

def atomic_replace(tmp_path, target):
    real_path = os.path.realpath(target_str) if os.path.islink(target_str) else target_str
    try:
        os.replace(str(tmp_path), real_path)
    except OSError as e:
        if e.errno == 18:  # EXDEV: cross-device link
            import shutil
            shutil.move(str(tmp_path), real_path)
        else:
            raise
    return real_path

Related

The same cross-filesystem issue affects save_env_value() / remove_env_value() in hermes_cli/config.py, where tempfile.NamedTemporaryFile creates temp files in the default tmpdir (rootfs) while .resolve() isn't called on get_env_path(). Adding .resolve() to env_path = get_env_path() calls covers this case.

Environment

• Hermes Agent v0.14.0+ (also present in v2026.5.28)
• Linux with ~/.hermes symlinked to a separate mount point