fix(auth): _auth_lock_path follows symlinks so shared auth.json serializes across processes

[vkrmch]

Summary

• _auth_lock_path() returned the caller's LOCAL ~/.hermes/auth.lock — silently broke shared-auth via symlink (the pattern the community is already DIY-ing per feat(profiles): native auth-sharing pattern across forked profiles #19436 / Profiled workers need a shared auth home separate from isolated HERMES_HOME #29530 / Share Codex CLI auth across Hermes gateway profiles #38176).
• In a shared-auth setup, each process held a different flock while writing to the SAME real file. Load-modify-save races across processes could persist a partial store that PURGED providers a peer just added.
• Fix resolves the symlink target so all sharers lock the same file. Non-symlink setups are unchanged (realpath returns the original path).

Motivation

I hit this on a 3-agent host sharing one Codex OAuth via ~/.hermes/auth.json → /var/lib/hermes-oauth/auth.json symlinks. After the first refresh cycle, the shared auth.json went from 5 providers (gemini, openai-codex, openrouter, xai, copilot) to 2 (gemini, openrouter). openai-codex, xai, copilot all wiped from credential_pool. active_provider cleared. providers map emptied. Required a full OAuth re-auth to recover.

Traced to _auth_lock_path() — the fcntl.flock was on ~/agent-x/.hermes/auth.lock, not on the target of the symlink, so cross-process serialization silently didn't work.

Related

• Bug: credential pool TOCTOU — process-local lock doesn't protect cross-process file access #8040 — same class of bug, but for agent/credential_pool.py's process-local threading.Lock. That issue suggests using the fcntl.flock pattern from hermes_cli/auth.py as a fix template — which is exactly the code path this PR corrects. So if Bug: credential pool TOCTOU — process-local lock doesn't protect cross-process file access #8040 gets that fix without this PR, the shared-auth case is still broken. Left a comment there flagging it: Bug: credential pool TOCTOU — process-local lock doesn't protect cross-process file access #8040 (comment)
• feat(profiles): native auth-sharing pattern across forked profiles #19436 / Profiled workers need a shared auth home separate from isolated HERMES_HOME #29530 / Share Codex CLI auth across Hermes gateway profiles #38176 — feature requests for native shared-auth. This PR makes the DIY-symlink workaround people are already using actually safe.

Fix

hermes_cli/auth.py::_auth_lock_path now resolves the auth.json symlink and places the lock next to the REAL file:

def _auth_lock_path() -> Path:
    auth = _auth_file_path()
    try:
        target = Path(os.path.realpath(str(auth)))
    except OSError:
        target = auth
    return target.with_suffix(".lock")

• Symlink setup: all processes lock the SAME <target-dir>/auth.lock — cross-process load-modify-save is properly serialized.
• Non-symlink setup: realpath returns the original path; lock stays at ~/.hermes/auth.lock — identical to today.
• Broken symlink (dangling): realpath returns the (non-existent) target path; the flock is created next to it, and a future creator of the shared file picks up the same lock.

Tests

Added tests/hermes_cli/test_auth_lock_path_symlink.py with 4 cases:

• Two profiles sharing an auth.json via symlink resolve to the SAME lock (the regression this fixes).
• Non-symlinked auth.json: lock sits next to it (behavior unchanged).
• No auth.json yet: lock path derives from _auth_file_path() unchanged.
• Dangling symlink: lock is placed next to the (non-existent) target.

All 4 pass locally.

Test plan

• New regression tests pass
• Verified on my 3-agent host: after applying, _auth_lock_path() returns the shared target /var/lib/hermes-oauth/auth.lock for all agents; the shared lock file gets created group-writable on first acquisition; no observed provider-purge in subsequent refresh cycles.
• CI green

🤖 Generated with Claude Code

https://claude.ai/code/session_01CmDNdF6D8TVXRohg17tqNU

[teknium1]

Thanks for the focused regression fix. The premise remains present on current main: hermes_cli/auth.py:983-984 derives the lock from the caller-local auth path, and _auth_store_lock() passes it to the cross-process lock at hermes_cli/auth.py:1072-1078. With separate symlinks to one auth store, those are different locks.

The change resolves the relevant target without altering normal-path behavior. It also fits the existing write behavior: hermes_cli/auth.py:1153 uses atomic_replace, whose symlink-preserving implementation resolves the real target before replacing it (utils.py:91-136). That means the proposed lock coordinates the same file the existing persistence code updates.

gh pr diff 62945 | git apply --check --verbose succeeds against current main.

Automated hermes-sweeper review.