Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

fix(hermes): keep parent-death protection on Hermes 0.23+ (spawn_owned) (#300)

mmchuangyt-ai0f5eb07d003f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2305f741..de6ef8d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- **A snapshot or restore can no longer hang forever on a stuck `tar` or `zstd`.** The snapshot module is synchronous, so a child that never exited froze the hook, CLI verb or MCP call that took the recovery point, with nothing able to interrupt it. Every `tar` and `zstd` run of a snapshot, a derived-store archive and a restore now has a timeout (fifteen minutes by default, `OPEN_SECOND_BRAIN_SNAPSHOT_TIMEOUT_MS` to change it); a run that hits it is killed and the snapshot fails with an error that names the tool and the bound, leaving no partial archive.
+- **The Hermes bridge keeps the host's parent-death protection on Hermes 0.23+.** Hermes removed `tools.mcp_stdio_watchdog` (hermes-agent `2d783a15`, "one parent-death supervisor per process, not one per stdio server") in favour of `hermes_cli.process_identity.spawn_owned`, so the bridge's `from tools import mcp_stdio_watchdog` stopped resolving: every provider load logged "parent-death watchdog module unavailable" and the `o2b mcp` child sat outside the host's reaping - the one case the guarantee exists for, a host killed by SIGKILL, OOM or a crash. The spawn now prefers `spawn_owned`, recording the child in the host's spawn ledger under `open-second-brain-mcp-bridge` and handing its process group to the per-process supervisor, and returns that group through `release_process_group_once_empty` once the bridge stops the child itself, so a stopped child's pgid cannot be reaped as a stranger's after the kernel recycles it. A host that only has the legacy wrapper still gets it unchanged, a host with neither (a standalone checkout, or any non-Hermes harness) still falls back to a plain spawn with the existing once-per-process warning, and an import that raises anything rather than `ImportError` degrades the same way instead of failing the bridge. Claude Code, Codex and the other harnesses never had a watchdog seam and are untouched; Windows keeps its plain `Popen`, since the layer-3 job object already owns the child there.
- **Token callers are attributed to their token on `brain_note` and `brain_expire` even without an `agent` argument.** Both handlers refused a cross-agent claim but then let an omitted agent resolve through the process config, so a token-minted caller's log line and expiration audit stamp could name the config identity instead of the credential's agent; both now fall back to the request identity after the claim check only when the caller arrived by token, and a shared-key caller keeps the config-path resolution it always had.
- **A retried `brain_feedback` force-confirmed capture no longer stays unwritten - and a replay can no longer resurrect a forgotten rule.** A first call that failed after its signal landed left an idempotency receipt whose retry answered `deduped` and never created the confirmed rule; the call now leaves a pending capture marker in the idempotency ledger before the preference write and a completion marker after it, and a deduped retry resumes only on that pending marker, with the same capture payload (the marker hash names `force_confirmed` and the expiration, so a forced retry of an unforced capture and a retry with a different lifetime both stay true no-ops) and with the signal still present. A crash that landed after the preference write but before the completion marker leaves the rule already active, so a replay that finds an active rule matching the captured slug and payload now closes the ledger and answers deduped instead of attempting the write a second time and refusing on the existing rule - and only a rule this capture can prove it wrote: the rule must read `confirmed` and name the deduped signal under `evidenced_by`, so a pre-existing same-slug same-payload rule falls through and surfaces its conflict instead of being adopted. A capture completed once, a capture whose signal `delete-by-source` later forgot, and a first call made without `force_confirmed` all stay true no-ops on replay; receipts written before the marker existed simply never resume, so old keys stay readable. The marker keys are digests of the trimmed client key rather than the key plus a suffix, so a key near the ledger's 256-character limit still captures fresh and replays deduped instead of failing its marker lookup, and a retry whose key differs only in surrounding whitespace finds the original capture's marker just as it dedupes its signal; the resume also answers a signal that moved since the failed write (the dream pass files inbox pages under `Brain/inbox/processed/`, an applied staged signal moves out of `Brain/pending/` into `Brain/inbox/`) by looking the id up in those folders, honors the server's config path when it consults the store, and stands down when the rule was retired in the crash window. The ledger's per-shard lock guarantees sequential retries dedupe exactly once on a device and, once synced, across devices; two truly concurrent retries can both pass the marker check, narrowed to a same-slug preference merge.
- **`brain_foresight` withholds private continuity records below local reach.** The extract fold read the raw continuity store, whose private records the read model drops, and served a private record's text as an item title with its source refs; the fold now takes the same withholding flag every other report fold takes, and local reach is unchanged. The recurring projection takes the flag too: a recurrence event the writer classified private - its source, or its scope, can name a private page whose name the projected item title carries - has its support dropped before the cadences are built, so no private-derived routine, support count or commitment reaches a caller below local reach.
diff --git a/plugins/hermes/bridge.py b/plugins/hermes/bridge.py
index 68221cd0..ff1d48ce 100644
--- a/plugins/hermes/bridge.py
+++ b/plugins/hermes/bridge.py
@@ -35,6 +35,55 @@ HARNESS_ARGV: tuple[str, ...] = ("--harness", "hermes")
CLIENT_NAME = "open-second-brain-hermes-provider"
logger = logging.getLogger(__name__)
+# Purpose recorded in Hermes' spawn ledger (``hermes_cli.process_identity``) for
+# the long-lived ``o2b mcp`` child, so an operator reading the ledger can tell
+# which plugin owns a process group.
+SPAWN_PURPOSE = "open-second-brain-mcp-bridge"
+
+
+def _hermes_spawn_owned() -> Any:
+ """Hermes' owner-death spawner, when this host provides it.
+
+ Hermes 0.23 replaced the per-child ``tools.mcp_stdio_watchdog`` wrapper with
+ one owner-death supervisor per process (hermes-agent commit 2d783a15):
+ ``spawn_owned`` puts the child in a new process group and hands that group to
+ the supervisor, so the child and every descendant that stays in the group die
+ when the host dies by any cause, SIGKILL included. Older Hermes has only the
+ wrapper (see ``McpBrainBridge._watchdog_argv``); a standalone checkout has
+ neither and degrades to a plain spawn.
+
+ Returning ``None`` means "this host has no such seam". Any import failure is
+ that answer, not an error: an older or non-Hermes host raises ImportError,
+ and a broken Hermes import raises something else - neither may take the
+ bridge down.
+ """
+ try:
+ from hermes_cli.process_identity import spawn_owned
+ except Exception: # noqa: BLE001 - absence is the expected answer, never fatal
+ return None
+ return spawn_owned
+
+
+def _release_owned_child(proc: Any) -> None:
+ """Hand a ``spawn_owned`` child's process group back after it was stopped.
+
+ Hermes prunes dead groups on its own, but that prune runs on the next
+ registration; releasing here closes the window in which a recycled pgid
+ could still be registered to a stranger's group. Best-effort by contract:
+ losing the bookkeeping must never fail a shutdown.
+ """
+ pid = getattr(proc, "pid", None)
+ if not isinstance(pid, int):
+ return
+ try:
+ from hermes_cli.process_identity import release_process_group_once_empty
+ except Exception: # noqa: BLE001 - older host: no ledger to hand back
+ return
+ try:
+ release_process_group_once_empty(pid, proc=proc)
+ except Exception: # noqa: BLE001 - shutdown is best-effort
+ return
+
# A shared bridge is one stdio stream, so its calls are serialised: a child
# that stops answering blocks every agent in the gateway rather than one
@@ -307,6 +356,9 @@ class McpBrainBridge:
self._client: JsonRpcStdioClient | None = None
self._tools: list[dict[str, Any]] = []
self._started = False
+ # True when the child was spawned through Hermes' owner-death
+ # supervisor, so stop() hands its process group back.
+ self._spawned_owned = False
def _argv(self) -> list[str]:
argv = list(self._command)
@@ -368,11 +420,13 @@ class McpBrainBridge:
# avoids the line-buffering deadlock that `text=True, bufsize=1`
# classically triggers with Popen pipes: a fast child writer +
# a slow parent reader fills the kernel buffer and both block.
- # Hermes' watchdog owns the real child process group, forwards the
- # stdio streams transparently, and kills the group when this gateway
- # exits unexpectedly.
- process = subprocess.Popen( # noqa: S603 - argv is a fixed command + config path
- self._watchdog_argv(argv),
+ #
+ # Parent-death protection has two shapes across Hermes versions, and
+ # whichever this host has is applied here rather than around the argv:
+ # `spawn_owned` (0.23+) owns the child's process group; the legacy
+ # `tools.mcp_stdio_watchdog` wrapped argv in a poller (see
+ # `_watchdog_argv`). A standalone checkout has neither.
+ popen_kwargs: dict[str, Any] = dict(
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
@@ -384,6 +438,16 @@ class McpBrainBridge:
# for the life of the bridge. No-op flag value on POSIX.
creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
)
+ spawn_owned = _hermes_spawn_owned()
+ if spawn_owned is not None:
+ process = spawn_owned(argv, purpose=SPAWN_PURPOSE, **popen_kwargs)
+ self._spawned_owned = True
+ else:
+ self._spawned_owned = False
+ process = subprocess.Popen( # noqa: S603 - argv is a fixed command + config path
+ self._watchdog_argv(argv),
+ **popen_kwargs,
+ )
stderr_thread = threading.Thread(
target=self._drain_stderr,
args=(process,),
@@ -620,6 +684,9 @@ class McpBrainBridge:
close()
except Exception: # noqa: BLE001
pass
+ if self._spawned_owned:
+ _release_owned_child(proc)
+ self._spawned_owned = False
logger.debug("open-second-brain MCP child stopped pid=%s", pid)
def _ensure_started(self) -> None:
diff --git a/tests/python/test_bridge_spawn.py b/tests/python/test_bridge_spawn.py
new file mode 100644
index 00000000..70112231
--- /dev/null
+++ b/tests/python/test_bridge_spawn.py
@@ -0,0 +1,236 @@
+"""Tests for the bridge's parent-death spawn seam.
+
+Hermes 0.23 replaced the per-child ``tools.mcp_stdio_watchdog`` wrapper with one
+owner-death supervisor per process (hermes-agent commit 2d783a15); the seam it
+exposes is ``hermes_cli.process_identity.spawn_owned``. These tests pin the
+three-way precedence the bridge promises, in the order a host can offer it:
+
+1. a host with ``spawn_owned`` - the child is spawned through it, so its process
+ group reaches the supervisor;
+2. an older Hermes with only ``tools.mcp_stdio_watchdog`` - argv is wrapped in
+ that poller, exactly as before;
+3. neither (a standalone checkout, or any non-Hermes harness) - a plain spawn,
+ with one warning that the guarantee is unavailable.
+
+The imports are simulated through ``sys.modules`` so the tests never require a
+Hermes checkout, and the same code runs on the CI Python that has no host at all.
+"""
+
+import logging
+import os
+import subprocess
+import sys
+import types
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+from plugins.hermes import bridge as bridge_mod # noqa: E402
+from plugins.hermes.bridge import McpBrainBridge, SPAWN_PURPOSE # noqa: E402
+
+_MANAGED_MODULES = ("hermes_cli", "hermes_cli.process_identity", "tools", "tools.mcp_stdio_watchdog")
+
+
+class SpawnSeamTests(unittest.TestCase):
+ def setUp(self) -> None:
+ self._saved = {name: sys.modules.get(name) for name in _MANAGED_MODULES}
+ # A None entry makes the import raise ImportError even on a machine
+ # with Hermes installed, so "absent" means absent; a test that needs
+ # a host installs its fake modules over these entries.
+ for name in _MANAGED_MODULES:
+ sys.modules[name] = None
+ McpBrainBridge._watchdog_absent_warned = False
+ self.bridge = McpBrainBridge(vault=None)
+
+ def tearDown(self) -> None:
+ for name, module in self._saved.items():
+ if module is None:
+ sys.modules.pop(name, None)
+ else:
+ sys.modules[name] = module
+ McpBrainBridge._watchdog_absent_warned = False
+
+ def _install_spawn_owned(self, recorder):
+ package = types.ModuleType("hermes_cli")
+ package.__path__ = [] # a package, so the submodule import resolves
+ identity = types.ModuleType("hermes_cli.process_identity")
+ setattr(identity, "spawn_owned", recorder)
+ setattr(package, "process_identity", identity)
+ sys.modules["hermes_cli"] = package
+ sys.modules["hermes_cli.process_identity"] = identity
+
+ def _install_legacy_watchdog(self):
+ package = types.ModuleType("tools")
+ package.__path__ = []
+ watchdog = types.ModuleType("tools.mcp_stdio_watchdog")
+ watchdog.__file__ = "/host/tools/mcp_stdio_watchdog.py"
+ setattr(package, "mcp_stdio_watchdog", watchdog)
+ sys.modules["tools"] = package
+ sys.modules["tools.mcp_stdio_watchdog"] = watchdog
+
+ def test_spawn_owned_is_preferred_when_the_host_provides_it(self) -> None:
+ calls = []
+
+ def spawn_owned(argv, *, purpose, **popen_kwargs):
+ calls.append((argv, purpose, popen_kwargs))
+ return mock.sentinel.process
+
+ self._install_spawn_owned(spawn_owned)
+ with mock.patch("subprocess.Popen", side_effect=AssertionError("plain Popen must not run")):
+ process = self.bridge._default_spawn(["o2b", "mcp"])
+
+ self.assertIs(process, mock.sentinel.process)
+ self.assertEqual(len(calls), 1)
+ argv, purpose, popen_kwargs = calls[0]
+ self.assertEqual(argv, ["o2b", "mcp"])
+ self.assertEqual(purpose, SPAWN_PURPOSE)
+ self.assertEqual(popen_kwargs["bufsize"], 0)
+ self.assertIn("cwd", popen_kwargs)
+ self.assertIn("env", popen_kwargs)
+
+ @unittest.skipIf(os.name != "posix", "the legacy watchdog wraps POSIX children only; Windows relies on the layer-3 job object")
+ def test_legacy_watchdog_wraps_argv_when_spawn_owned_is_absent(self) -> None:
+ self._install_legacy_watchdog()
+ with mock.patch("subprocess.Popen", return_value=mock.sentinel.process) as popen:
+ process = self.bridge._default_spawn(["o2b", "mcp"])
+
+ self.assertIs(process, mock.sentinel.process)
+ spawned = popen.call_args.args[0]
+ self.assertEqual(
+ spawned,
+ [
+ sys.executable,
+ "/host/tools/mcp_stdio_watchdog.py",
+ "--ppid",
+ str(os.getpid()),
+ "--",
+ "o2b",
+ "mcp",
+ ],
+ )
+
+ @unittest.skipIf(os.name != "posix", "the legacy watchdog wraps POSIX children only; Windows relies on the layer-3 job object")
+ def test_plain_spawn_warns_once_when_no_host_seam_exists(self) -> None:
+ with mock.patch("subprocess.Popen", return_value=mock.sentinel.process) as popen:
+ with self.assertLogs(bridge_mod.logger, level=logging.WARNING) as logs:
+ self.bridge._default_spawn(["o2b", "mcp"])
+ self.bridge._default_spawn(["o2b", "mcp"])
+
+ self.assertEqual(popen.call_args.args[0], ["o2b", "mcp"])
+ warnings = [line for line in logs.output if "parent-death watchdog module unavailable" in line]
+ self.assertEqual(len(warnings), 1, "the absence is a property of the install, not of the call")
+
+ def test_broken_host_import_degrades_to_plain_spawn(self) -> None:
+ package = types.ModuleType("hermes_cli")
+ package.__path__ = []
+ sys.modules["hermes_cli"] = package
+
+ class Broken(types.ModuleType):
+ def __getattr__(self, name): # noqa: D105 - attribute access is the failure
+ raise RuntimeError("host import is broken")
+
+ sys.modules["hermes_cli.process_identity"] = Broken("hermes_cli.process_identity")
+
+ with mock.patch("subprocess.Popen", return_value=mock.sentinel.process) as popen:
+ process = self.bridge._default_spawn(["o2b", "mcp"])
+
+ self.assertIs(process, mock.sentinel.process)
+ self.assertEqual(popen.call_args.args[0], ["o2b", "mcp"])
+
+
+class SpawnOwnedProbeTests(unittest.TestCase):
+ def test_probe_returns_none_without_the_host_module(self) -> None:
+ names = ("hermes_cli", "hermes_cli.process_identity")
+ saved = {name: sys.modules.get(name) for name in names}
+ for name in names:
+ sys.modules[name] = None # blocks a real install too
+ try:
+ self.assertIsNone(bridge_mod._hermes_spawn_owned())
+ finally:
+ for name, module in saved.items():
+ if module is None:
+ sys.modules.pop(name, None)
+ else:
+ sys.modules[name] = module
+
+ def test_probe_returns_the_host_callable(self) -> None:
+ package = types.ModuleType("hermes_cli")
+ package.__path__ = []
+ identity = types.ModuleType("hermes_cli.process_identity")
+ setattr(identity, "spawn_owned", lambda *a, **k: None)
+ sys.modules["hermes_cli"] = package
+ sys.modules["hermes_cli.process_identity"] = identity
+ try:
+ self.assertIs(bridge_mod._hermes_spawn_owned(), identity.spawn_owned)
+ finally:
+ sys.modules.pop("hermes_cli", None)
+ sys.modules.pop("hermes_cli.process_identity", None)
+
+
+
+class _FakeProc:
+ """A child that reports clean exit, so stop() reaches its release path."""
+
+ def __init__(self, pid: int = 4242) -> None:
+ self.pid = pid
+ self.terminated = False
+ self.stdin = None
+ self.stdout = None
+ self.stderr = None
+
+ def poll(self):
+ return None
+
+ def terminate(self) -> None:
+ self.terminated = True
+
+ def wait(self, timeout=None):
+ return 0
+
+ def kill(self) -> None: # pragma: no cover - terminate/wait succeed first
+ pass
+
+
+class OwnedChildReleaseTests(unittest.TestCase):
+ """A supervised child's process group is handed back when the bridge stops."""
+
+ def setUp(self) -> None:
+ self.proc = _FakeProc()
+ self.released = []
+ package = types.ModuleType("hermes_cli")
+ package.__path__ = []
+ identity = types.ModuleType("hermes_cli.process_identity")
+ setattr(identity, "spawn_owned", lambda argv, *, purpose, **kw: self.proc)
+
+ def release(pid, *, proc=None):
+ self.released.append((pid, proc))
+
+ setattr(identity, "release_process_group_once_empty", release)
+ setattr(package, "process_identity", identity)
+ sys.modules["hermes_cli"] = package
+ sys.modules["hermes_cli.process_identity"] = identity
+ self.bridge = McpBrainBridge(vault=None)
+
+ def tearDown(self) -> None:
+ sys.modules.pop("hermes_cli", None)
+ sys.modules.pop("hermes_cli.process_identity", None)
+
+ def test_stop_releases_the_supervised_group_once(self) -> None:
+ self.bridge._proc = self.bridge._default_spawn(["o2b", "mcp"])
+ self.assertTrue(self.bridge._spawned_owned)
+ self.bridge.stop()
+ self.assertEqual(self.released, [(self.proc.pid, self.proc)])
+ self.assertFalse(self.bridge._spawned_owned)
+
+ def test_stop_without_a_supervised_child_releases_nothing(self) -> None:
+ self.bridge._proc = _FakeProc()
+ self.bridge.stop()
+ self.assertEqual(self.released, [])
+
+
+if __name__ == "__main__":
+ unittest.main()