threadkeeper 0.6.1__tar.gz → 0.6.2__tar.gz

{threadkeeper-0.6.1 → threadkeeper-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.6.1
+Version: 0.6.2
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT

{threadkeeper-0.6.1 → threadkeeper-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.6.1"
+version = "0.6.2"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]

{threadkeeper-0.6.1 → threadkeeper-0.6.2}/tests/test_memory_guard.py

@@ -108,6 +108,7 @@ def test_memory_guard_status_tool_reports_thresholds(mp_with_cid, monkeypatch):
     assert "state=active" in txt
     assert "warn_mb=1000" in txt
     assert "kill_mb=2000" in txt
+    assert "coordinator=on" in txt
     assert "ok pid=1001" in txt
     assert "WARN pid=1002" in txt
     assert "KILL pid=1003" in txt
@@ -172,17 +173,51 @@ def test_check_apply_requests_peer_trim_on_aggregate_warn(mp_with_cid, monkeypat
     })
     monkeypatch.setattr(process_health, "scan", lambda: [
         _proc(os.getpid(), 900),
-        _proc(1002, 1200, ppid=os.getpid()),
+        _proc(os.getpid() + 1002, 1200, ppid=os.getpid()),
     ])
 
     out = memory_guard.check_once(dry_run=False, notify=False)
-    assert sorted(out["reclaim_requests"]["requested"]) == sorted([os.getpid(), 1002])
+    peer_pid = os.getpid() + 1002
+    assert sorted(out["reclaim_requests"]["requested"]) == sorted(
+        [os.getpid(), peer_pid]
+    )
 
     conn = pkg["db"].get_db()
     rows = conn.execute(
         "SELECT target_pid FROM resource_controls WHERE action='trim'"
     ).fetchall()
-    assert sorted(r["target_pid"] for r in rows) == sorted([os.getpid(), 1002])
+    assert sorted(r["target_pid"] for r in rows) == sorted([os.getpid(), peer_pid])
+
+
+def test_aggregate_side_effects_only_run_on_coordinator(mp_with_cid, monkeypatch):
+    mp_with_cid(_FAKE_CID)
+    from threadkeeper import memory_guard, process_health
+
+    self_pid = os.getpid()
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_WARN_MB", 5000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_KILL_MB", 6000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_WARN_MB", 2000)
+    monkeypatch.setattr(memory_guard, "MEMORY_GUARD_AGG_KILL_MB", 0)
+    monkeypatch.setattr(process_health, "scan", lambda: [
+        _proc(self_pid - 1, 1200),
+        _proc(self_pid, 1200),
+    ])
+    reclaim_calls: list[str] = []
+    monkeypatch.setattr(
+        memory_guard,
+        "reclaim_memory",
+        lambda reason="": reclaim_calls.append(reason) or {
+            "before_mb": 1200, "after_mb": 1100, "freed_mb": 100,
+            "pid": self_pid, "actions": [],
+        },
+    )
+
+    out = memory_guard.check_once(dry_run=False, notify=False)
+    assert out["aggregate"]["warn"] is True
+    assert out["coordinator"] is False
+    assert out["reclaim_requests"]["count"] == 0
+    assert out["local_reclaim"] is None
+    assert reclaim_calls == []
 
 
 def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, monkeypatch):
@@ -204,13 +239,13 @@ def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, m
     def scan():
         return [
             _proc(os.getpid(), 900),
-            _proc(1001, 1200, ppid=1) | {
+            _proc(os.getpid() + 1001, 1200, ppid=1) | {
                 "heartbeat_age_s": None,
                 "parent_alive": False,
                 "is_orphaned": True,
                 "orphan_reason": "parent_gone + no_heartbeat",
             },
-            _proc(1002, 800, ppid=os.getpid()) | {"heartbeat_age_s": 5},
+            _proc(os.getpid() + 1002, 800, ppid=os.getpid()) | {"heartbeat_age_s": 5},
         ]
 
     monkeypatch.setattr(process_health, "scan", scan)
@@ -221,8 +256,9 @@ def test_check_apply_retires_idle_candidate_on_aggregate_pressure(mp_with_cid, m
     )
 
     out = memory_guard.check_once(dry_run=False, notify=False)
-    assert out["retired"] == [1001]
-    assert calls == [(1001, _sig.SIGTERM)]
+    stale_pid = os.getpid() + 1001
+    assert out["retired"] == [stale_pid]
+    assert calls == [(stale_pid, _sig.SIGTERM)]
 
 
 def test_aggregate_retire_skips_live_parent_without_opt_in(mp_with_cid, monkeypatch):
@@ -242,7 +278,7 @@ def test_aggregate_retire_skips_live_parent_without_opt_in(mp_with_cid, monkeypa
     })
     monkeypatch.setattr(process_health, "scan", lambda: [
         _proc(os.getpid(), 900),
-        _proc(1001, 1200, ppid=os.getpid()) | {"heartbeat_age_s": None},
+        _proc(os.getpid() + 1001, 1200, ppid=os.getpid()) | {"heartbeat_age_s": None},
     ])
     calls: list[tuple[int, int]] = []
     monkeypatch.setattr(

{threadkeeper-0.6.1 → threadkeeper-0.6.2}/threadkeeper/memory_guard.py

@@ -73,13 +73,19 @@ def _log_line(line: str) -> None:
         logger.debug("memory_guard: failed to append log", exc_info=True)
 
 
-def _emit_event(kind: str, pid: int, summary: str) -> None:
+def _emit_event(kind: str, target: int | str, summary: str) -> None:
     try:
         conn = get_db()
         conn.execute(
             "INSERT INTO events (session_id, kind, target, summary, created_at) "
             "VALUES (?,?,?,?,?)",
-            (identity._session_id or "", kind, str(pid), summary[:200], int(time.time())),
+            (
+                identity._session_id or "",
+                kind,
+                str(target),
+                summary[:200],
+                int(time.time()),
+            ),
         )
         conn.commit()
     except Exception:
@@ -228,6 +234,18 @@ def _pending_recent_control(conn, action: str, pid: int, now: int) -> bool:
     return row is not None
 
 
+def _recent_event(conn, kind: str, target: str, now: int) -> bool:
+    if MEMORY_GUARD_COOLDOWN_S <= 0:
+        return False
+    row = conn.execute(
+        "SELECT 1 FROM events "
+        "WHERE kind=? AND target=? AND created_at>=? "
+        "ORDER BY id DESC LIMIT 1",
+        (kind, target, now - max(1, MEMORY_GUARD_COOLDOWN_S)),
+    ).fetchone()
+    return row is not None
+
+
 def request_reclaim(procs: list[dict] | None = None, reason: str = "manual") -> dict:
     """Queue trim requests for the given process rows, deduped by cooldown."""
     if procs is None:
@@ -293,6 +311,33 @@ def _aggregate_state(procs: list[dict]) -> dict:
     }
 
 
+def _global_guard_coordinator_pid(procs: list[dict]) -> int | None:
+    candidates = [
+        int(p["pid"])
+        for p in procs
+        if int(p.get("pid") or 0) > 0 and not p.get("is_orphaned")
+    ]
+    if not candidates:
+        candidates = [int(p["pid"]) for p in procs if int(p.get("pid") or 0) > 0]
+    return min(candidates) if candidates else None
+
+
+def is_global_guard_coordinator(procs: list[dict]) -> bool:
+    """True when this server owns process-wide aggregate side effects.
+
+    Every MCP server runs its own local daemon. Without coordination, N open
+    conversations produce N aggregate warnings, N trim sweeps, and racing retire
+    attempts. The oldest non-orphaned server is the single coordinator; if the
+    scanner somehow misses this process, treat the current manual caller as the
+    coordinator so diagnostics/tests still apply side effects.
+    """
+    self_pid = os.getpid()
+    pids = {int(p["pid"]) for p in procs if int(p.get("pid") or 0) > 0}
+    if self_pid not in pids:
+        return True
+    return self_pid == _global_guard_coordinator_pid(procs)
+
+
 def _idle_retire_candidates(procs: list[dict]) -> list[dict]:
     candidates: list[dict] = []
     for p in procs:
@@ -351,12 +396,15 @@ def scan_over_limit() -> dict:
             warn.append(p)
     aggregate = _aggregate_state(procs)
     retire = _retire_plan(procs, aggregate)
+    coordinator = is_global_guard_coordinator(procs)
     return {
         "procs": procs,
         "warn": warn,
         "kill": kill,
         "aggregate": aggregate,
         "retire": retire,
+        "coordinator": coordinator,
+        "coordinator_pid": _global_guard_coordinator_pid(procs),
         "warn_mb": MEMORY_GUARD_WARN_MB,
         "kill_mb": MEMORY_GUARD_KILL_MB,
         "reclaim_mb": MEMORY_GUARD_RECLAIM_MB,
@@ -377,6 +425,7 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
         handled_controls = handle_resource_controls()
 
     result = scan_over_limit()
+    is_coordinator = bool(result.get("coordinator"))
     killed: list[int] = []
     failed: list[dict] = []
     retired: list[int] = []
@@ -384,6 +433,8 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
     local_reclaim: dict | None = None
 
     for p in result["warn"]:
+        if p["pid"] != os.getpid():
+            continue
         msg = (
             f"pid {p['pid']} RSS {p['rss_mb']}MB crossed warn "
             f"threshold {MEMORY_GUARD_WARN_MB}MB"
@@ -396,21 +447,24 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
             _maybe_notify(p["pid"], "warn", msg)
 
     aggregate = result["aggregate"]
-    if aggregate["warn"]:
+    if aggregate["warn"] and is_coordinator:
         msg = (
             f"aggregate RSS {aggregate['rss_mb']}MB crossed warn "
             f"threshold {aggregate['warn_mb']}MB across "
             f"{len(result['procs'])} server process(es)"
         )
         if not dry_run:
-            _emit_event("memory_guard_aggregate_warn", os.getpid(), msg)
-            reclaim_requests = request_reclaim(
-                result["procs"], reason="aggregate_warn"
-            )
-            if any(p["pid"] == os.getpid() for p in result["procs"]):
-                local_reclaim = reclaim_memory(reason="aggregate_warn")
-        if notify and not dry_run:
-            _maybe_notify(os.getpid(), "aggregate_warn", msg)
+            conn = get_db()
+            now = int(time.time())
+            if not _recent_event(conn, "memory_guard_aggregate_warn", "aggregate", now):
+                _emit_event("memory_guard_aggregate_warn", "aggregate", msg)
+                reclaim_requests = request_reclaim(
+                    result["procs"], reason="aggregate_warn"
+                )
+                if any(p["pid"] == os.getpid() for p in result["procs"]):
+                    local_reclaim = reclaim_memory(reason="aggregate_warn")
+                if notify:
+                    _maybe_notify(os.getpid(), "aggregate_warn", msg)
 
     kill_rows = sorted(
         result["kill"], key=lambda p: p["pid"] == os.getpid()
@@ -422,6 +476,8 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
         )
         if dry_run:
             continue
+        if p["pid"] != os.getpid() and not is_coordinator:
+            continue
         _emit_event("memory_guard_kill", p["pid"], msg)
         if notify:
             _maybe_notify(p["pid"], "kill", msg, force=True)
@@ -431,7 +487,7 @@ def check_once(*, dry_run: bool = True, notify: bool = True) -> dict:
         except (ProcessLookupError, PermissionError, OSError) as e:
             failed.append({"pid": p["pid"], "err": str(e)})
 
-    if aggregate["warn"] and result["retire"]:
+    if aggregate["warn"] and is_coordinator and result["retire"]:
         for p in result["retire"]:
             msg = (
                 f"aggregate RSS {aggregate['rss_mb']}MB; retiring idle "

{threadkeeper-0.6.1 → threadkeeper-0.6.2}/threadkeeper/tools/memory_guard.py

@@ -33,6 +33,8 @@ def memory_guard_status() -> str:
         f"agg_warn_mb={agg['warn_mb']} agg_kill_mb={agg['kill_mb']} "
         f"target_servers={agg['target_servers']} "
         f"retire_live={'on' if agg['retire_live'] else 'off'} "
+        f"coordinator={'on' if result['coordinator'] else 'off'} "
+        f"coordinator_pid={result['coordinator_pid'] or '-'} "
         f"notify={'on' if result['notify'] else 'off'}",
         f"processes={len(procs)} rss_total={total_mb}MB aggregate={agg_marker}",
     ]

{threadkeeper-0.6.1 → threadkeeper-0.6.2}/threadkeeper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.6.1
+Version: 0.6.2
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Gemini, Copilot, VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT