PR #17221: fix(utils): chown atomic-replace target to match parent when root (#17144)

• Repository: NousResearch/hermes-agent
• Author: Tranquil-Flow
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/17221

Description (problem / solution / changelog)

What does this PR do?

Containerized hermes deployments (e.g. nousresearch/hermes-agent:latest on Synology / Docker / Podman) typically have a root-init entrypoint (tini) that spawns the gateway as hermes / UID 10000 against a host-mounted persistent volume that is also owned by 10000. When a memory-tool consolidation, hook script, or any other atomic write happens to land on the root side of that boundary, the new file lands as root:root with restrictive perms — and the running gateway cannot read it. Memory updates appear to succeed (the agent gets a write-OK response) but the gateway never re-injects them on the next session, silently breaking the persistent-memory promise (#17144).

The fix adds a _chown_to_match_parent helper in utils.py and calls it from atomic_replace, so every atomic-write call site (memory tool, atomic_json_write, atomic_yaml_write, future writers) inherits the fix without touching every call site.

The helper is best-effort and POSIX-only: no-op on Windows, no-op when not running as root (where chown to a foreign UID would EPERM anyway), no-op when the parent directory is itself root-owned, and swallows OSError so a chown rejection from a FUSE mount or ACL-locked filesystem doesn't fail the user-visible write.

Related Issue

Fixes #17144

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• utils.py — new private helper _chown_to_match_parent(path) with os.geteuid() == 0 gate, parent-stat read, root-parent skip, and an OSError swallow. atomic_replace calls it on the resolved real path after os.replace. Docstring updated to describe the new behavior.
• tests/test_atomic_replace_chown_parent.py (new) — four cases pinning the gating logic by monkey-patching os.geteuid / os.stat / os.chown so we don't need real root in CI:
  1. root + non-root parent → chown propagates the parent's owner/gid
  2. non-root → no chown call
  3. root + root-owned parent → no chown call
  4. root + chown EPERM → atomic_replace still commits content

How to Test

1. Run hermes inside a container where the entrypoint is root and the gateway runs as a service user (hermes/10000). The persistent volume parent should be owned by 10000:10000.
2. From a root-side code path (e.g. a startup hook), invoke a memory write that touches ~/.hermes/memories/MEMORY.md.
3. Before this fix: the resulting file is root:root; docker exec hermes ls -l /opt/data/memories shows root root MEMORY.md; the gateway logs cannot read the file on the next session reset.
4. After this fix: the file is hermes:hermes (matches parent); the gateway re-injects it normally.

Automated:

pytest tests/test_atomic_replace_chown_parent.py tests/test_atomic_replace_symlinks.py tests/hermes_cli/test_atomic_json_write.py tests/hermes_cli/test_atomic_yaml_write.py tests/tools/test_memory_tool.py -q

Result on macOS 15.6 / Python 3.14: 62 passed. The new tests fail on origin/main because no chown call is ever made (the helper does not exist there).

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/test_atomic_replace_chown_parent.py tests/test_atomic_replace_symlinks.py tests/hermes_cli/test_atomic_json_write.py tests/hermes_cli/test_atomic_yaml_write.py tests/tools/test_memory_tool.py -q (62 passed). Full pytest tests/ -q not run; the atomic-write surface above is fully exercised.
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 15.6 (Python 3.14)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A (updated atomic_replace's docstring to describe the new chown step; no user-facing docs reference atomic-write internals)
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A (N/A — no config keys touched)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A (N/A)
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A (explicit os.name != "posix" early-return on Windows; macOS and Linux both go through the same POSIX path; the helper is also a no-op when not root, so Linux/macOS users running as themselves see zero behavior change)
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A (N/A — internal helper, not a tool)

Screenshots / Logs

$ pytest tests/test_atomic_replace_chown_parent.py tests/test_atomic_replace_symlinks.py tests/hermes_cli/test_atomic_json_write.py tests/hermes_cli/test_atomic_yaml_write.py tests/tools/test_memory_tool.py -q
............                                                             [ 19%]
..................................................                       [100%]
62 passed, 62 warnings in 2.44s

Changed files

• tests/test_atomic_replace_chown_parent.py (added, +149/-0)
• utils.py (modified, +53/-0)