fix(utils): EXDEV/EBUSY copy fallback in atomic_replace (port from gemini-cli#21541)

[teknium1]

Summary

atomic_replace() now falls back to copy + fsync + unlink when os.replace() fails with EXDEV (cross-device link) or EBUSY (busy bind mount), instead of crashing every atomic write site.

Port of the rename-fallback pattern from google-gemini/gemini-cli#21541 (their policy-file persistence hit the same failure class on Docker bind mounts / Linux aarch64).

Root cause: atomic_replace resolves symlinked targets to their real path (#16743 symlink preservation) before renaming. When a managed deployment symlinks ~/.hermes/config.yaml / auth.json / jobs.json to a file on a different filesystem (Docker bind mount, NFS/SMB share, dotfiles repo on another partition), the rename crosses devices and raises OSError(EXDEV) — reproduced E2E on current main with a /dev/shm-backed symlink target. Every caller of atomic_replace / atomic_json_write / atomic_yaml_write (~24 sites: config, auth, cron jobs, webhooks, model catalog, skills sync, …) is affected.

Changes

• utils.py: catch EXDEV/EBUSY from os.replace, fall back to shutil.copyfile + copymode + fsync + unlink. All other OSErrors still propagate. Fallback is non-atomic but strictly better than failing the write and leaking the temp file.
• tests/test_atomic_replace_symlinks.py: 5 new tests — EXDEV/EBUSY fallback (parametrized), symlink preserved on the fallback path, non-EXDEV errors propagate untouched, and a real-filesystem E2E using a tmpfs (/dev/shm) symlink target.

Validation

	Before	After
atomic_replace onto cross-device symlink	OSError: [Errno 18] Invalid cross-device link	content lands, symlink + mode preserved, temp cleaned
tests/test_atomic_replace_symlinks.py	8 passed	13 passed
Non-EXDEV OSError (EACCES)	raises	still raises, target untouched

Source PR: google-gemini/gemini-cli#21541

[github-actions]

🔎 Lint report: gemini-cli-port/atomic-replace-ebusy-fallback vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10878 on HEAD, 10878 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 5709 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[liuhao1024]

Verification review — reviewed the full diff (2 files, +157/-1).

Clean port of the EXDEV/EBUSY fallback from gemini-cli#21541:

1. Error scoping — only EXDEV (cross-device) and EBUSY (bind-mount busy) trigger the fallback; other OSError codes propagate unchanged. This is the correct narrow scope.

2. Fallback sequence — shutil.copyfile → shutil.copymode → os.fsync → os.unlink. The fsync ensures data is durable before the temp file is removed. Permission copy failures are caught and ignored (correct — the file is still readable).

3. Symlink preservation — the fallback writes to real_path (the resolved target), so symlinked configs survive cross-device writes. This maintains the [Bug]: atomic writes to HERMES_HOME files replace symlinked targets (config.yaml/SOUL.md) #16743 invariant.

4. Test coverage — parameterized EXDEV/EBUSY, symlink preservation, other-OSError propagation, and a real cross-device E2E test using /dev/shm vs tmpdir.

No issues found. Clean utility fix.

[teknium1]

Refreshed against current origin/main and force-pushed a cleaner salvage commit.

Cleanup:

• fallback only for EXDEV / EBUSY; other OSErrors still propagate
• preserves symlink target semantics through resolved real path handling
• uses copy + copystat + fsync + unlink for the fallback path
• focused test coverage for symlink, metadata, non-fallback errors, and real cross-device behavior when /dev/shm is available

Validation:

• python3 -m py_compile utils.py tests/test_atomic_replace_symlinks.py -> passed
• pytest -q tests/test_atomic_replace_symlinks.py -> 14 passed
• python3 -m ruff check utils.py tests/test_atomic_replace_symlinks.py -> passed