feat(config): interprocess write lock — eliminate watchdog TOCTOU race

[dizhaky]

Problem

save_config() writes config.yaml then separately writes the SHA256 seal in seal_config(). If the Config Integrity Watchdog fires in that gap (milliseconds), it sees current != sealed, declares tampering, and triggers a false restore — resurrecting the scanner/watchdog conflict fixed in #52.

_CONFIG_LOCK (a threading lock) protects same-process concurrent writes but does nothing for the watchdog, which runs in a separate cron process.

Slack thread: https://mfc-nyc.slack.com/archives/C0BD8QBUSJF/p1782743855322599

Solution

An OS-level file lock (fcntl.flock on POSIX, msvcrt.locking on Windows) that save_config() holds exclusively from before atomic_yaml_write through the seal_config() write. No external process can observe an intermediate state.

Changes

hermes_cli/config.py

Function	Description
get_config_lock_path()	Returns ~/.hermes/config.yaml.lock
config_write_lock()	Exclusive OS file lock context manager — hold during write + seal
config_read_lock()	Shared lock context manager — for external readers (e.g. the watchdog) to acquire before checking integrity
_write_config_to_disk()	Private helper extracted from save_config() to avoid fcntl.flock re-entrancy deadlock when restore_config() calls into save_config()
save_config()	Now acquires config_write_lock() around write + seal — zero race window
verify_config_integrity(locked=False)	New locked kwarg: when True, acquires config_read_lock() before reading, guaranteeing consistent state
restore_config(content, *, reason="")	Safe restore helper: acquires lock → backs up current config → writes + reseals atomically. Replaces raw file manipulation in restore scripts like restore_deepseek_config.py

tests/hermes_cli/test_config_lock.py

17 new tests across 5 classes: lock paths, write lock lifecycle, read lock (including concurrent readers), verify_config_integrity (tamper detection, locked mode, seal update on save), and restore_config (dict/YAML string/reason in backup name/seal update after restore).

Implementation note

fcntl.flock(LOCK_EX) is not reentrant on POSIX — re-acquiring an exclusive lock from the same process deadlocks. restore_config() holding the OS lock and calling save_config() (which would re-acquire it) deadlocked in initial testing. Fixed by extracting _write_config_to_disk() as a private helper: save_config() calls config_write_lock() then _write_config_to_disk(); restore_config() acquires both _CONFIG_LOCK and config_write_lock() and calls _write_config_to_disk() directly.

---

Generated by Claude Code

[github-actions]

🔎 Lint report: claude/config-write-lock 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: 8653 on HEAD, 8650 on base (🆕 +3)

🆕 New issues (3):

Rule	Count
invalid-assignment	2
unresolved-import	1

First entries

hermes_cli/config.py:39: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to `<module 'msvcrt'>`
hermes_cli/config.py:34: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to `<module 'fcntl'>`
tests/hermes_cli/test_config_lock.py:8: [unresolved-import] unresolved-import: Cannot resolve imported module `pytest`

✅ Fixed issues: none

Unchanged: 4570 pre-existing issues carried over.

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

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.